Skip to main content
Two routes, both returning an upload_id that is accepted wherever an item id or ref is.

​
A file you hold

  1. POST /api/v1/uploads with file_name, content_type and file_size returns upload_url, valid for one hour, and r2_key. One upload carries up to 5 GB; a larger file goes through import_media in link mode.
  2. PUT the bytes to upload_url with the same content type.
  3. POST /api/v1/uploads/confirm with r2_key, file_name, file_size and content_type turns the file into a library item and returns upload_id and its type. description sets the item’s description. enrich: true describes and tags an image, using cloud processing. made_from records what the file was made from.
Confirming the same key twice returns 200 with the item already created. The size ceilings per type are in Limits.

​
A file at a URL

POST /api/v1/uploads/import fetches a public URL into the library in one call, keeping the original bytes. Send url for one file, or items for up to 20, each with its own file_name, description and made_from. A batch returns results in input order, each with a status of imported, duplicate or failed, and a summary. A failed item is a status in the list, not an error. folder_id accepts an id or a path. A duplicate, meaning a file the library already holds byte for byte, returns 200 with the existing item and duplicate: true.

​
The same over the tools

import_media does the same through any interface, in url, file, presign and confirm modes, and through the desktop app in local mode for a path on that computer. See Library.