BackendDocuments & RAG
API Endpoints
REST API for knowledge bases, documents, and chat-session KB attachments.
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 documents |
| POST | /api/workspaces/{ws}/documents/ | Create document metadata |
| GET | /api/workspaces/{ws}/documents/{id}/ | Retrieve document |
| PUT | /api/workspaces/{ws}/documents/{id}/ | Update document |
| DELETE | /api/workspaces/{ws}/documents/{id}/ | Delete document (+ S3 object) |
| 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 |
| GET | /api/workspaces/{ws}/documents/{id}/processing-status/ | Poll processing status |
| POST | /api/workspaces/{ws}/documents/{id}/reprocess/ | Re-trigger ingestion |
| 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.
Processing Status
GET /api/workspaces/{workspace_id}/documents/{id}/processing-status/{
"status": "processing",
"task_id": "abc123-...",
"error_message": null
}Possible statuses: PENDING, STARTED, SUCCESS, FAILURE, RETRY, REVOKED.
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.