Uploads
A presigned PUT for task inputs only. The gateway never receives the bytes: the client declares the file, PUTs it to the returned address with the given headers, then names the upl_ id in a task input. A customer model is never uploaded: it is imported from a model hub in the Console, as Import and run your model describes.
Note
Uploads are not offered in production yet: every route here answers 404 route_not_available until the upload limits are set. Send a task's input inline (data, base64) meanwhile.
/v1/uploadsnot offeredA presigned PUT for a task input. Not offered in production yet: 404 route_not_available.
/v1/uploads/{id}not offeredThe upload's status. Not offered in production yet: 404 route_not_available.
/v1/uploads/{id}not offeredDeletes the upload and its bytes. Not offered in production yet: 404 route_not_available.
Request
{"purpose": "input", "filename": "call.wav", "content_type": "audio/wav", "size_bytes": 10485760, "sha256": "<hex>"}answers 201:
Response
{ "object": "upload", "id": "upl_...", "purpose": "input", "status": "pending", "upload_url": "<presigned PUT>", "upload_headers": {"Content-Type": "audio/wav"}, "upload_expires_at": "...", "expires_at": "..."}The client PUTs the bytes to upload_url with the given headers, then names upl_... in inputs[].upload_id.
Parts list: Rules
purposeinput(a task or job input), the only purpose. Themodelpurpose is withdrawn: a customer model is imported from a model hub, never uploaded.purpose: "model"answers 400invalid_valuewithparam: "purpose"and a message naming the Console's import. The field stays required.statuspending(no bytes yet),ready(bytes received, size and type match),consumed(aninputupload used by a job on a workspace whose policy deletes inputs after use),expired.GET /v1/uploads/{id}returns it.MismatchBytes whose size, type or
sha256differ from the declaration make the uploadfailedand its use a 400upload_mismatch.LimitsSize per upload and uploads per day by plan Not decided yet; multipart for large inputs (long audio and video) Not decided yet.
RetentionAn upload is deleted at
expires_atNot decided yet or when consumed; where a region requirement applies, it is stored in that region Not decided yet.Customer modelsNot an upload. A customer model version comes from an import from a model hub, a Console action; this contract addresses only its deployment (
dep_). A public import route is open Not decided yet.The PUTTo
upload_url, carrying exactly theupload_headersof the answer:Content-Type,If-None-Match: *, andx-amz-checksum-sha256(the declaredsha256, 64 hex characters in the request, sent as base64 of its 32 bytes) when one was declared, so the store checks the bytes on arrival.DELETE /v1/uploads/{id}Deletes the upload and its bytes, answered whatever the workspace's state, since a customer may delete at any time. A
fullkey reaches every upload of its workspace; any other key, and a person's token, the uploads it created.Daily capUnder the workspace's daily cap on uploads, a presign and its 429 carry
x-ratelimit-limit-uploads,x-ratelimit-remaining-uploadsandx-ratelimit-reset-uploads(headers). Every answer of these routes carriesCache-Control: no-store.ReplaysPOST /v1/uploadstakes anidempotency-key; a replay answers the first upload withidempotent-replayed: true.
| Status | Type | Code | Situation | Retry |
|---|---|---|---|---|
| 400 | invalid_request_error | request_too_large, input_too_large, too_many_inputs, upload_too_large | A limit of the Limits page | No |
| 400 | invalid_request_error | upload_not_found, upload_expired, upload_incomplete, upload_mismatch, upload_consumed, upload_purpose_mismatch, upload_region_mismatch | An upload_id that is unknown or another workspace's, past expires_at, without bytes, with bytes that differ from the declaration, already consumed, of another purpose than the request needs, or stored in another region than the request's region requirement. Uploads are not offered in production yet | No (upload_incomplete: after the PUT) |
| 400 | invalid_request_error | invalid_idempotency_key, idempotency_key_reused, idempotency_in_progress | The idempotency rules | The last one, later |
| 404 | not_found_error | upload_not_found, file_not_found, batch_not_found | An id in the path, or input_file_id, that is unknown, deleted, expired, another workspace's, or out of the credential's reach. Batches and files are not offered in production yet | No |
| 404 | not_found_error | route_not_available | A route that is built and not offered on this gateway: uploads, files and batches in production, and POST /v1/messages/count_tokens | No |
| 429 | rate_limit_error | rate_limit_exceeded | A rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; Retry-After | Yes, after Retry-After |
- Status
- 400
- Type
invalid_request_error- Code
request_too_large,input_too_large,too_many_inputs,upload_too_large- Situation
- A limit of the Limits page
- Retry
- No
- Status
- 400
- Type
invalid_request_error- Code
upload_not_found,upload_expired,upload_incomplete,upload_mismatch,upload_consumed,upload_purpose_mismatch,upload_region_mismatch- Situation
- An
upload_idthat is unknown or another workspace's, pastexpires_at, without bytes, with bytes that differ from the declaration, already consumed, of another purpose than the request needs, or stored in another region than the request's region requirement. Uploads are not offered in production yet - Retry
- No (
upload_incomplete: after the PUT)
- Status
- 400
- Type
invalid_request_error- Code
invalid_idempotency_key,idempotency_key_reused,idempotency_in_progress- Situation
- The idempotency rules
- Retry
- The last one, later
- Status
- 404
- Type
not_found_error- Code
upload_not_found,file_not_found,batch_not_found- Situation
- An id in the path, or
input_file_id, that is unknown, deleted, expired, another workspace's, or out of the credential's reach. Batches and files are not offered in production yet - Retry
- No
- Status
- 404
- Type
not_found_error- Code
route_not_available- Situation
- A route that is built and not offered on this gateway: uploads, files and batches in production, and
POST /v1/messages/count_tokens - Retry
- No
- Status
- 429
- Type
rate_limit_error- Code
rate_limit_exceeded- Situation
- A rate limit;
paramisrequests,tokens,uploads,batches(batches created per hour) orknowledge_search;Retry-After - Retry
- Yes, after
Retry-After
Related sheets
- Sheet
- 18 of 20
- Detail
- L
- Updated
- 2026-11-11