List documents and ingestion status
/v1/bots/{botId}/documentsscope: documents:readRequires the documents:read scope and access to the requested bot.
Parameters
botIdpath · stringrequired | — |
limitquery · integer | Default: 50 · Min: 1 · Max: 100 |
cursorquery · string | — |
Example
curl -X GET '$ORBCONTEXT_API_URL/v1/bots/{botId}/documents' \
-H "Authorization: Bearer $ORBCONTEXT_API_KEY"{
"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
Cursor-paginated documents.
Error responses share one shape; see Errors & limits.
Upload one knowledge document
/v1/bots/{botId}/documentsscope: documents:writeRequires the documents:write scope and access to the requested bot.
Parameters
botIdpath · 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'{
"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
Queued; poll the document until ready or failed.
Error responses share one shape; see Errors & limits.
Get ingestion status
/v1/documents/{documentId}scope: documents:readRequires the documents:read scope and access to the requested bot.
Parameters
documentIdpath · stringrequired | — |
Example
curl -X GET '$ORBCONTEXT_API_URL/v1/documents/{documentId}' \
-H "Authorization: Bearer $ORBCONTEXT_API_KEY"{
"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
Document metadata, no source content.
Error responses share one shape; see Errors & limits.
Remove a document
/v1/documents/{documentId}scope: documents:writeRequires the documents:write scope and access to the requested bot.
Parameters
documentIdpath · stringrequired | — |
Example
curl -X DELETE '$ORBCONTEXT_API_URL/v1/documents/{documentId}' \
-H "Authorization: Bearer $ORBCONTEXT_API_KEY"{
"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
Deletion queued.
Error responses share one shape; see Errors & limits.
Refresh a website document
/v1/documents/{documentId}/refreshscope: documents:writeRequires the documents:write scope and access to the requested bot.
Parameters
documentIdpath · stringrequired | — |
Example
curl -X POST '$ORBCONTEXT_API_URL/v1/documents/{documentId}/refresh' \
-H "Authorization: Bearer $ORBCONTEXT_API_KEY"{
"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
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.