Register files and get each one's id and upload URL.

POST/o/{org}/files
View .md

Writes one file row per entry (owned by the caller, bound to no Project yet) and returns its id with a presigned single-shot PUT, so one call registers a whole drop: send each file's bytes to its own url with the headers given, then pass each id as a {"type": "file", "file_id": id} source in a session's or a follow-up's input. Bytes go straight to storage, so no file size is refused: this is the way to send a large private file. Each url lasts 60 seconds and is bound to that one file; re-sign an expired one, or upload a file in parts, with POST /o/{org}/files/{id}/sign. Files are returned in request order. Rate-limited to 30 calls a minute per caller (60 for admins).

Authenticate with a signed-in session token (an API key cannot call this route).

Path parameters

orgstringrequired

The org's slug or id. A caller with no role in the org gets 404.

Request body

filesarray of objectrequired
3 item fields
namestringrequired

File name. No /, \, .., leading ., or control characters.

at most 255 characters
mimestringrequired

A media type; parameters are dropped and the lowercased type/subtype is stored. Any type is accepted.

at most 512 characters
sizeintegerrequired

Exact byte size; the signed PUT refuses a body of any other length.

min 1

Responses

200One ready-to-upload file per request entry, in request order.
filesarray of objectrequired
4 item fields
idstringrequired
Format uuid
urlstringrequired

Presigned single-shot PUT for this file's bytes. Valid 60 seconds.

Format uri
headersobjectrequired

The exact headers the PUT must send. The declared byte count is signed in too, so a body of any other length is refused.

1 fields
content-typestringrequired
view_urlstringrequired

Absolute GET /o/{org}/files/{id}, which redirects to a freshly signed download on every request. Readable once the bytes are uploaded.

Format uri
400Invalid JSON, empty files, an invalid entry, or more than 50 files (TOO_MANY_FILES; the other cases carry no code).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404No such resource for the caller, including one that exists in an org the caller cannot see.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
429Presign rate limit exceeded.

Presign rate limit exceeded. Retry-After is set.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional