API Endpoints

Knowledge Bases

All endpoints scoped to a workspace:

Method	Endpoint	Description
GET	`/api/workspaces/{ws}/knowledge-bases/`	List knowledge bases
POST	`/api/workspaces/{ws}/knowledge-bases/`	Create knowledge base
GET	`/api/workspaces/{ws}/knowledge-bases/{id}/`	Retrieve KB
PUT	`/api/workspaces/{ws}/knowledge-bases/{id}/`	Update KB
DELETE	`/api/workspaces/{ws}/knowledge-bases/{id}/`	Delete KB
POST	`/api/workspaces/{ws}/knowledge-bases/{id}/add-documents/`	Add documents to KB
POST	`/api/workspaces/{ws}/knowledge-bases/{id}/remove-documents/`	Remove documents from KB
GET	`/api/workspaces/{ws}/knowledge-bases/{id}/documents/`	List documents in KB

Team Access

Method	Endpoint	Description
GET	`/api/workspaces/{ws}/knowledge-bases/{id}/team-access/`	View team access rules
POST	`/api/workspaces/{ws}/knowledge-bases/{id}/team-access/`	Grant team access
DELETE	`/api/workspaces/{ws}/knowledge-bases/{id}/team-access/`	Revoke team access

Create Knowledge Base

POST /api/workspaces/{workspace_id}/knowledge-bases/

{
  "name": "Product Documentation",
  "description": "Internal product docs and guides",
  "is_shared_with_workspace": true
}

Add Documents to Knowledge Base

POST /api/workspaces/{workspace_id}/knowledge-bases/{kb_id}/add-documents/

{
  "document_ids": ["uuid1", "uuid2"]
}

Documents are linked via the KnowledgeBaseDocument through table. Chunks are never duplicated — the same document can belong to multiple knowledge bases.

Documents

Method	Endpoint	Description
GET	`/api/workspaces/{ws}/documents/`	List the documents you can see
GET	`/api/workspaces/{ws}/documents/{id}/`	Retrieve document
PUT/PATCH	`/api/workspaces/{ws}/documents/{id}/`	Update document (uploader or admin)
DELETE	`/api/workspaces/{ws}/documents/{id}/`	Delete document and its stored file (uploader or admin)
POST	`/api/workspaces/{ws}/documents/upload/`	Get presigned upload URL
POST	`/api/workspaces/{ws}/documents/{id}/confirm-upload/`	Confirm upload, trigger ingestion
GET	`/api/workspaces/{ws}/documents/{id}/download-url/`	Get presigned download URL (as an attachment)
GET	`/api/workspaces/{ws}/documents/{id}/processing-status/`	Poll processing status
POST	`/api/workspaces/{ws}/documents/{id}/reprocess/`	Re-trigger ingestion (uploader or admin; needs credit)
GET	`/api/workspaces/{ws}/documents/{id}/chunks/`	Get all chunks
POST	`/api/workspaces/{ws}/documents/from-url/`	Ingest from web URL or YouTube

Upload Flow

See the S3 Uploads page for the complete presigned URL upload flow.

Ingest from URL

POST /api/workspaces/{workspace_id}/documents/from-url/

{
  "url": "https://example.com/article",
  "name": "Example Article",
  "knowledge_base_ids": ["uuid1"]
}

The URL is automatically classified as web_url or youtube. A Celery task handles extraction and embedding.

Only public http(s) addresses are fetched: private, loopback, link-local and internal addresses are refused, and so is a redirect to one. The plan's document limits and the workspace's credit are checked first, and imports share the documents rate limit (THROTTLE_DOCUMENT_UPLOADS, 30/hour per user).

Processing Status

GET /api/workspaces/{workspace_id}/documents/{id}/processing-status/

{
  "processing_status": "failed",
  "task": {
    "id": "uuid",
    "document": "uuid",
    "task_id": "abc123-...",
    "status": "FAILURE",
    "error_message": "We couldn't process this file. Try again, or upload it in another format.",
    "created_at": "2026-10-04T09:12:44Z"
  }
}

processing_status is the document's: pending, processing, ready or failed. The task's status is one of PENDING, STARTED, SUCCESS, FAILURE, RETRY, REVOKED. task is null before the first ingestion is queued. Error messages are written for the user; details stay in the server log.

Chat Session Knowledge Bases

Attach knowledge bases to chat sessions so the AI agent can search them:

Method	Endpoint	Description
GET	`/api/workspaces/{ws}/chats/{session}/knowledge-bases/`	List attached KBs
POST	`/api/workspaces/{ws}/chats/{session}/knowledge-bases/attach/`	Attach KBs
POST	`/api/workspaces/{ws}/chats/{session}/knowledge-bases/detach/`	Detach KBs

Attach Knowledge Bases

POST /api/workspaces/{workspace_id}/chats/{session_id}/knowledge-bases/attach/

{
  "knowledge_base_ids": ["uuid1", "uuid2"]
}

Once attached, the agent's search_knowledge_base tool will search documents in these KBs during conversation.

On this page