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 file=1 \
  --form 'metadata={}' \
  --form 'directory=<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 uploading a file to a knowledge base.

​
file
integer<int32>[]
required

The file to upload.

Required range: x >= 0
​
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.

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