Skip to main content
POST
/
files
cURL
curl --request POST \
  --url https://api.timbal.ai/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=1
{
  "content_length": 123,
  "content_type": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "url": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt

Use this file to discover all available pages before exploring further.

Utility endpoint — not org-scoped. Use it to conveniently pass binary data into agents and workflows (e.g. attachments, generated artifacts) and to receive short-lived URLs when components return files. Responses are temporary (~24h lifecycle); there is no durable org file record behind this route.
If you need long-lived storage, parsing, embedding, and reuse across a knowledge base, use the Knowledge Bases → Files APIs under /orgs/{org_id}/k2/{kb_id}/files instead (upload, list, chunks, etc.).

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

Stateless temporary file metadata. Stored under a dedicated tmp/ prefix in object storage and removed by storage lifecycle policy ~24h after upload. No database row is created; clients must persist the URL/name themselves if they need to track it.

​
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

Advisory expiration (~24h after upload). Object deletion is performed by storage lifecycle and may lag this timestamp by up to a day. Treat HTTP 404 from url as "expired".

​
name
string
required

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

​
url
string
required

Public URL where the file can be downloaded until it expires.