Skip to main content

Upload from URL

POST 
/:workspace/media/remote/initiate

Downloads a file from a remote URL into the media library.

The URL is checked before the download starts (with a HEAD request, falling back to a ranged GET): the file must be reachable, its Content-Type must be resolvable and among the MIME types allowed by your instance, and — when the remote server advertises a Content-Length — that size must not exceed the maximum for its MIME type.

The download then runs either synchronously or in the background, decided against a fixed 10 MB threshold (this is a separate, hard-coded value and is not affected by MIXPOST_CHUNKED_UPLOAD_THRESHOLD):

  • Files whose Content-Length is under 10 MB — and any file whose Content-Length the remote server does not report, regardless of its actual size — are downloaded synchronously, and the response returns the media immediately with status: completed.
  • Everything else is queued for background download and returns status: pending with a download_id; poll GET /{workspace}/media/remote/{downloadId}/status for the result.

Request​

Responses​

This endpoint always responds with 200 — a failed synchronous download is reported as status: failed in the body rather than as an HTTP error status.

Note that the media object returned here has a different, richer shape than the one returned by the other media endpoints: it carries extra descriptive fields such as source_url, credit_url, author, source and alt_text, and it has no created_at.