Skip to main content
A file sent in a request body stops at 100 MB, whatever the plan. A direct upload has no such limit: the bytes go from you to storage, and only the start and the finish pass through the API. Use it for a file on your own disk that is bigger than 100 MB, or whenever you would rather not hold a connection open while a run starts. Three calls:
  1. POST /api/v1/uploads — say what the file is. You get back where to send it.
  2. PUT the bytes to the URL, or to each part’s URL.
  3. POST /api/v1/uploads/{id}/complete — we check the file and answer with what it turned out to be.
Then send its upload_id to /run/{skill}, /runs or /convert in place of file or url. An upload can be run as many times as you like. Opening and completing an upload needs a key with the run scope. Reading one back needs read.

Open an upload

The file is held to your plan before any byte moves: a type we take, and a size under your plan’s ceiling. Over it is 413 file_too_large, and the message names the plan that takes it.

Up to 100 MB: one PUT

Send the file with the headers given — the type is part of the signature, so a PUT without it is refused. So is its length: the body has to be exactly size_bytes. Every HTTP client sets Content-Length from the body on its own; a chunked PUT, with no length, is refused.

Over 100 MB: parts

Cut the file into part_size slices — every part that size except the last — and PUT slice n to part n’s URL. Parts can go in any order and several at once. Keep the ETag header each PUT answers with; complete needs them.
A single PUT’s URL lasts an hour; part URLs last six hours (expires_at). An upload that runs past that is opened again. Complete it within a day of the last PUT: bytes never completed are cleared after that.

Complete it

A single PUT sends no body. Parts send every part_number with its etag, once each. The file is then checked the way every upload is: its real type, read from its bytes, and its real size against your plan. What it turned out to be comes back:
A file that fails the check is deleted. Completing twice answers the same as the first time. The URLs write to a holding place, not to the file itself. complete moves what arrived into place once, and the file you run is the one it checked: a PUT to the same URL afterwards changes nothing.

Run it

Each run gets a job of its own and reads the same stored file, so running a second skill over an upload leaves the first one’s results alone.

Read one back

GET /api/v1/uploads/{id} answers the same shape, with "status": "pending" until the upload is completed.

Errors