Skip to main content
There are two routes. Both return an upload_id, which works wherever an item id or ref does.

A file you have

  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 can be up to 5 GB. A larger file can be added by the user through the page import_media returns in link mode.
  2. PUT the bytes to upload_url with the same content type and exactly file_size bytes. Any other length is refused.
  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. It takes 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, in link mode for files the user can add from their own device, and through the desktop app in local mode for a path on that computer. See Library.