Skip to main content
POST
cURL
Utility endpoint — not org-scoped. Upload requires authentication; the response includes a download URL (~24h). Anyone with the URL can download until expiry — treat it as a secret. Not for sensitive or regulated data.
Ephemeral staging only (~24h lifecycle); there is no durable org file record behind this route. For durable storage, parsing, embedding, and reuse across a knowledge base, use Knowledge Bases → Files (POST /orgs/{org_id}/k2/{kb_id}/files) instead.

Authorizations

Authorization
string
header
required

Timbal API key. Obtain your API key from the Timbal platform settings. See Authentication for more information.

Body

multipart/form-data
file
integer<int32>[]
required

Binary contents of the file. Max 100 MB.

Required range: x >= 0

Response

File uploaded

Short-lived upload metadata returned by POST /files.

content_length
integer<int64>
required

Size of the uploaded payload in bytes.

content_type
string
required

MIME type as reported by the client.

created_at
string<date-time>
required

Time the file was uploaded.

expires_at
string<date-time>
required

When the download URL is expected to stop working (~24h after upload).

name
string
required

Original filename (sanitized — slashes / control characters replaced).

url
string
required

Download URL. Anyone with this URL can fetch the file until it expires.