Upload from URL

Downloads a media file from a remote URL. Small files (under 10 MB) are downloaded synchronously and return the media record immediately. Large files (10 MB or more) are queued for background download and return a download_id for polling the status.

Method: POST

URL: https://example.com/<MIXPOST_CORE_PATH>/api/<workspaceUuid>/media/remote/initiate

Authorization: Bearer <token>

Body:

{
  "url": "https://example.com/photo.jpg"
}

Key	Format	Required	Description
url	string	required	The URL of the remote file to download. Must be a valid, accessible URL with an allowed MIME type.
alt_text	string		Alt text for the media. Max 255 characters.

Response:

200 (completed)

Returned when the file is small enough to be downloaded synchronously.

{
  "status": "completed",
  "media": {
    "id": "1",
    "uuid": "511b8c2d-c424-3a6a-a154-be271418ff01",
    "name": "photo.jpg",
    "mime_type": "image/jpeg",
    "type": "image",
    "url": "https://your-domain.com/storage/2576cb55-ab0f-3708-9388-6d03290fcb3f/uploads/03-2024/HsqEvFqHQYEU14DARrqULDnvoh7GMYopQGqYGhoi.jpg",
    "thumb_url": "https://your-domain.com/storage/2576cb55-ab0f-3708-9388-6d03290fcb3f/uploads/03-2024/HsqEvFqHQYEU14DARrqULDnvoh7GMYopQGqYGhoi-thumb.jpg",
    "is_video": false,
    "created_at": "2024-03-29 15:33:23"
  }
}

200 (pending)

Returned when the file is large and queued for background download. Use the download_id to poll the download status endpoint.

{
  "status": "pending",
  "download_id": "a3f1b2c4-d5e6-7890-abcd-ef1234567890"
}

200 (failed)

Returned when a synchronous download fails.

{
  "status": "failed",
  "error": "Failed to download file from the provided URL."
}

401

{
  "message": "Unauthenticated."
}

403

{
  "message": "Access forbidden."
}

404

{
  "message": "Workspace not found."
}

422

{
  "message": "Validation errors",
  "errors": {}
}