Skip to main content
POST
Uploads go straight to cloud storage — the API only hands you a presigned target and never receives the bytes. The response’s upload_type tells you which of two flows to run; it’s picked automatically from the bytes you declare (large files use multipart), and there’s no maximum file size.

​
Small files — upload_type: "single"

  1. POST /files/uploads (this call) — returns a file_id, a presigned upload_url, and the fields to send with the bytes.
  2. Upload the bytes — POST them to upload_url as multipart form-data, with every key in fields included as a form field (204 No Content on success).
  3. POST /files/{file_id}/finalize — confirm the upload (empty body).

​
Large files — upload_type: "multipart"

  1. POST /files/uploads returns a file_id, an upload_id, a part_size, and a part_count (no upload_url).
  2. Split the file into part_count chunks of part_size bytes (the last chunk is whatever’s left).
  3. POST /files/{file_id}/parts with the upload_id and the part numbers you want → returns a presigned PUT URL per part. You can request them in batches.
  4. PUT each chunk to its URL and keep the ETag response header for that part number.
  5. POST /files/{file_id}/finalize with { "upload_id": "…", "parts": [{ "part_number": 1, "etag": "…" }, … ] } — cloud storage assembles the object.
Either way, once finalized, attach the file_id to a Task with "file_ids": [...] on POST /messages.

Authorizations

​
Authorization
string
header
required

Requires an API key. See the Authentication guide.

Body

application/json
​
project_id
string
required
​
filename
string
required
​
bytes
integer
required
​
purpose
enum<string>
default:input
Available options:
input,
output
​
mime_type
string | null

Response

200 - application/json

Upload started. upload_type=single → POST the bytes to upload_url with fields. upload_type=multipart → use upload_id + part_size + part_count with POST /files/{file_id}/parts.

​
project_id
string
required
​
filename
string
required
​
bytes
integer
required
​
object
string
default:upload_intent
Allowed value: "upload_intent"
​
file_id
string | null
​
path
string | null
​
upload_type
enum<string>
default:single
Available options:
single,
multipart
​
upload_url
string | null
​
fields
Fields · object
​
upload_id
string | null
​
part_size
integer | null
​
part_count
integer | null
​
expires_at
integer | null
​
mime_type
string | null