Skip to main content
POST
/
orgs
/
{org_id}
/
k2
/
{kb_id}
/
files
/
{file_id}
/
chunks
cURL
curl --request POST \
  --url https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}/chunks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "<string>",
  "after_uid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "before_uid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "embed": "<string>",
  "page_end": 123,
  "page_start": 123
}
'
{
  "blocks": {},
  "content": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "embed": "<string>",
  "index_status": "<string>",
  "kb_file_id": "<string>",
  "ordinal": "<string>",
  "revision": "<string>",
  "source": "<string>",
  "uid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "updated_at": "2023-11-07T05:31:56Z",
  "index_error": "<string>",
  "indexed_at": "2023-11-07T05:31:56Z",
  "page_end": 123,
  "page_start": 123
}

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
​
file_id
string
required

Body

application/json
​
content
string
required
​
after_uid
string<uuid> | null

Place the new chunk immediately after this chunk_uid. Mutually exclusive with before_uid. If neither is set, the chunk is appended at the end of the file.

​
before_uid
string<uuid> | null

Place the new chunk immediately before this chunk_uid. Mutually exclusive with after_uid.

​
embed
string | null

Text used for vector / full-text indexing. Defaults to content when omitted; provide an explicit value to keep an indexing-optimized variant distinct from the user-visible text.

​
page_end
integer<int32> | null
​
page_start
integer<int32> | null

Response

Chunk inserted. Search results reflect the change after re-indexing completes (index_status field).

​
blocks
object
required

Source-document layout metadata (e.g. bounding boxes, page coords) when available. null for chunks created or edited by the user.

​
content
string
required
​
created_at
string<date-time>
required
​
embed
string
required
​
index_status
string
required

Indexing state. One of pending, indexing, indexed, failed. While not indexed, the chunk's contribution to search results may be stale.

​
kb_file_id
string
required
​
ordinal
string
required

Ordering key. Chunks in a file are returned in ascending ordinal order. Treat the value as opaque — placement on insert is controlled by after_uid / before_uid, not by setting ordinal directly.

​
revision
string
required

Optimistic concurrency token. Send back as If-Match: <revision> on the next mutation (PATCH / DELETE).

​
source
string
required

Origin of the chunk: parser, user_edit, or insert.

​
uid
string<uuid>
required

Stable per-chunk identity.

​
updated_at
string<date-time>
required
​
index_error
string | null
​
indexed_at
string<date-time> | null
​
page_end
integer<int32> | null
​
page_start
integer<int32> | null