POST /api/v1/uploads— say what the file is. You get back where to send it.PUTthe bytes to the URL, or to each part’s URL.POST /api/v1/uploads/{id}/complete— we check the file and answer with what it turned out to be.
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
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
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.
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
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:
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
Read one back
GET /api/v1/uploads/{id} answers the same shape, with "status": "pending" until the upload is completed.

