Skip to content
OrbContext
19 pages

API reference

Documents

Upload, list, poll and delete the knowledge behind a bot.

List documents and ingestion status

GET/v1/bots/{botId}/documentsscope: documents:read

Requires the documents:read scope and access to the requested bot.

Parameters

botId
path · stringrequired
—
limit
query · integer
Default: 50 · Min: 1 · Max: 100
cursor
query · string
—

Example

curl -X GET '$ORBCONTEXT_API_URL/v1/bots/{botId}/documents' \
  -H "Authorization: Bearer $ORBCONTEXT_API_KEY"
Response 200
{
  "items": [
    {
      "id": "d_your_document_id",
      "botId": "b_your_bot_id",
      "name": "knowledge.txt",
      "type": "txt",
      "status": "ready",
      "chunkCount": 8,
      "tokenCount": 1500,
      "sizeBytes": 4200,
      "error": null,
      "sourceUrl": null,
      "crawledPages": [],
      "refreshing": false,
      "effectiveFrom": null,
      "effectiveUntil": null,
      "replacesDocumentId": null,
      "location": "",
      "audience": "",
      "sheet": null,
      "resync": "weekly",
      "lastSyncedAt": null,
      "nextSyncAt": null,
      "createdAt": "2026-10-21T10:00:00.000Z",
      "ocr": null
    }
  ],
  "nextCursor": "string"
}

Responses

200400401402403404413415429500503

Cursor-paginated documents.

Error responses share one shape; see Errors & limits.

Upload one knowledge document

POST/v1/bots/{botId}/documentsscope: documents:write

Requires the documents:write scope and access to the requested bot.

Parameters

botId
path · stringrequired
—

Request body · multipart/form-data

Send one file field: PDF, DOCX, TXT, Markdown or CSV, within your plan's size limit.

Example

curl -X POST '$ORBCONTEXT_API_URL/v1/bots/{botId}/documents' \
  -H "Authorization: Bearer $ORBCONTEXT_API_KEY" \
  -F 'file=@knowledge.txt'
Response 202
{
  "id": "d_your_document_id",
  "botId": "b_your_bot_id",
  "name": "knowledge.txt",
  "type": "txt",
  "status": "ready",
  "chunkCount": 8,
  "tokenCount": 1500,
  "sizeBytes": 4200,
  "error": null,
  "sourceUrl": null,
  "crawledPages": [],
  "refreshing": false,
  "effectiveFrom": null,
  "effectiveUntil": null,
  "replacesDocumentId": null,
  "location": "",
  "audience": "",
  "sheet": null,
  "resync": "weekly",
  "lastSyncedAt": null,
  "nextSyncAt": null,
  "createdAt": "2026-10-21T10:00:00.000Z",
  "ocr": null
}

Responses

202400401402403404413415429500503

Queued; poll the document until ready or failed.

Error responses share one shape; see Errors & limits.

Get ingestion status

GET/v1/documents/{documentId}scope: documents:read

Requires the documents:read scope and access to the requested bot.

Parameters

documentId
path · stringrequired
—

Example

curl -X GET '$ORBCONTEXT_API_URL/v1/documents/{documentId}' \
  -H "Authorization: Bearer $ORBCONTEXT_API_KEY"
Response 200
{
  "id": "d_your_document_id",
  "botId": "b_your_bot_id",
  "name": "knowledge.txt",
  "type": "txt",
  "status": "ready",
  "chunkCount": 8,
  "tokenCount": 1500,
  "sizeBytes": 4200,
  "error": null,
  "sourceUrl": null,
  "crawledPages": [],
  "refreshing": false,
  "effectiveFrom": null,
  "effectiveUntil": null,
  "replacesDocumentId": null,
  "location": "",
  "audience": "",
  "sheet": null,
  "resync": "weekly",
  "lastSyncedAt": null,
  "nextSyncAt": null,
  "createdAt": "2026-10-21T10:00:00.000Z",
  "ocr": null
}

Responses

200400401402403404413415429500503

Document metadata, no source content.

Error responses share one shape; see Errors & limits.

Remove a document

DELETE/v1/documents/{documentId}scope: documents:write

Requires the documents:write scope and access to the requested bot.

Parameters

documentId
path · stringrequired
—

Example

curl -X DELETE '$ORBCONTEXT_API_URL/v1/documents/{documentId}' \
  -H "Authorization: Bearer $ORBCONTEXT_API_KEY"
Response 202
{
  "id": "d_your_document_id",
  "botId": "b_your_bot_id",
  "name": "knowledge.txt",
  "type": "txt",
  "status": "ready",
  "chunkCount": 8,
  "tokenCount": 1500,
  "sizeBytes": 4200,
  "error": null,
  "sourceUrl": null,
  "crawledPages": [],
  "refreshing": false,
  "effectiveFrom": null,
  "effectiveUntil": null,
  "replacesDocumentId": null,
  "location": "",
  "audience": "",
  "sheet": null,
  "resync": "weekly",
  "lastSyncedAt": null,
  "nextSyncAt": null,
  "createdAt": "2026-10-21T10:00:00.000Z",
  "ocr": null
}

Responses

202400401402403404413415429500503

Deletion queued.

Error responses share one shape; see Errors & limits.

Refresh a website document

POST/v1/documents/{documentId}/refreshscope: documents:write

Requires the documents:write scope and access to the requested bot.

Parameters

documentId
path · stringrequired
—

Example

curl -X POST '$ORBCONTEXT_API_URL/v1/documents/{documentId}/refresh' \
  -H "Authorization: Bearer $ORBCONTEXT_API_KEY"
Response 202
{
  "id": "d_your_document_id",
  "botId": "b_your_bot_id",
  "name": "knowledge.txt",
  "type": "txt",
  "status": "ready",
  "chunkCount": 8,
  "tokenCount": 1500,
  "sizeBytes": 4200,
  "error": null,
  "sourceUrl": null,
  "crawledPages": [],
  "refreshing": false,
  "effectiveFrom": null,
  "effectiveUntil": null,
  "replacesDocumentId": null,
  "location": "",
  "audience": "",
  "sheet": null,
  "resync": "weekly",
  "lastSyncedAt": null,
  "nextSyncAt": null,
  "createdAt": "2026-10-21T10:00:00.000Z",
  "ocr": null
}

Responses

202400401402403404413415429500503

Re-crawl queued. The current version keeps answering (`refreshing: true`) until the new one is ready; a failed refresh leaves it in place. Website documents only, at most once an hour.

Error responses share one shape; see Errors & limits.