Skip to main content
POST
/
orgs
/
{org_id}
/
k2
/
{kb_id}
/
files
cURL
curl --request POST \
  --url https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'metadata={}' \
  --form 'directory=<string>' \
  --form file=1 \
  --form parse=true \
  --form 'url=<string>'
{
  "content_length": 123,
  "content_type": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "id": 123,
  "kb_id": 123,
  "metadata": "<unknown>",
  "name": "<string>",
  "parse_state": "<string>",
  "uid": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "url": "<string>",
  "directory": "<string>"
}
File names must be unique within a directory. Uploading report.pdf to docs/ when it already exists returns 409. Folders and files share the same namespace: you cannot upload a file whose name matches an existing folder in the same directory.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
org_id
string
required
​
kb_id
string
required

Body

multipart/form-data

Request body for adding a file to a knowledge base.

Provide either file (raw bytes via multipart) or url (http/https URL the server fetches directly). Exactly one is required.

​
metadata
object
required

Optional JSON metadata to attach to the file.

​
directory
string | null

Optional subdirectory path to organize the file within the knowledge base.

​
file
integer<int32>[] | null

File bytes (multipart file field). Mutually exclusive with url.

Required range: x >= 0
​
parse
boolean | null

Per-upload override for the parse/chunk/embed pipeline. Accepts "true"/"false" (or "1"/"0"). When omitted, the knowledge base's auto-processing setting and the file extension decide. true forces parsing even when the KB has auto-processing off (still credit-gated; unsupported extensions silently fall back to stored-as-is). false stores the file as-is and never runs the pipeline.

​
url
string | null

Public http/https URL the server fetches and ingests directly. SSRF-hardened (internal hosts blocked). Mutually exclusive with file.

Response

File uploaded

​
content_length
integer<int64>
required
​
content_type
string
required
​
created_at
string<date-time>
required
​
id
integer<int64>
required
​
kb_id
integer<int64>
required
​
metadata
any
required
​
name
string
required
​
parse_state
string
required

Pipeline state for parsing + embedding.

One of pending (pipeline in flight), success (parse + embed both completed), failed (latest attempt failed), or skipped (format unsupported, never parsed). Unsupported files are stored as-is; the indicator lets clients flag them in listings rather than rejecting the upload.

​
uid
string
required
​
updated_at
string<date-time>
required
​
url
string
required
​
directory
string | null