Agents Documents
API endpoints for Agents Documents
/api/agents/{agent_id}/documents List returns documents for an agent.
Retrieves paginated document knowledge sources for the specified agent. Returns 400 for invalid agent ID, 500 on service error, 200 OK with paginated documents on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 500 | Internal server error |
Success
Response response.PaginatedDocuments
Paginated Documents
| Property | Type | Description |
|---|---|---|
| data | string[] | Array of documents for current page |
| meta | string | Pagination metadata |
/api/agents/{agent_id}/documents Create creates a document knowledge source.
Accepts base64-encoded file content and stores the document for the agent. Queues the document for processing and embedding generation. Returns 404 if agent not found, 400 for validation errors, 500 on storage or creation failure, 201 Created with the document on success.
Request Body request.Document
Document
| Property | Type | Description |
|---|---|---|
| file_base64* | string | Base64-encoded file content |
| file_filename* | string | Original filename with extension |
| title | string | null | Optional display title (defaults to filename) |
| description | string | null | Optional description of document contents |
| metadata | object | Custom metadata as JSON object |
Response Codes
| Status Code | Description |
|---|---|
| 201 | Resource created successfully |
| 400 | Invalid request |
| 404 | Resource not found |
| 422 | Validation failed |
| 500 | Internal server error |
Resource created successfully
Response response.DocumentResponse
Document
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique document identifier |
| agent_id | integer (int64) | ID of agent this document belongs to |
| title | string | Display title |
| description | string | null | Optional description of document contents |
| metadata | object | Custom metadata |
| original_filename | string | null | Original filename with extension |
| storage_path | string | null | Storage path to document file |
| file_type | string | null | MIME type or file extension |
| size | integer (int64) | null | File size in bytes |
| ingest_status | string | Processing status (pending, processing, completed, failed) |
| uploaded_at | string (date-time) | null | Timestamp when document was uploaded |
| created_at | string (date-time) | Timestamp when document was created |
| updated_at | string (date-time) | Timestamp when document was last updated |
/api/agents/{agent_id}/documents/{id} Get returns a document by ID.
Retrieves a single document by its ID. Returns 400 for invalid ID, 404 if not found or belongs to different agent, 200 OK with the document on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
Success
Response response.DocumentResponse
Document
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique document identifier |
| agent_id | integer (int64) | ID of agent this document belongs to |
| title | string | Display title |
| description | string | null | Optional description of document contents |
| metadata | object | Custom metadata |
| original_filename | string | null | Original filename with extension |
| storage_path | string | null | Storage path to document file |
| file_type | string | null | MIME type or file extension |
| size | integer (int64) | null | File size in bytes |
| ingest_status | string | Processing status (pending, processing, completed, failed) |
| uploaded_at | string (date-time) | null | Timestamp when document was uploaded |
| created_at | string (date-time) | Timestamp when document was created |
| updated_at | string (date-time) | Timestamp when document was last updated |
/api/agents/{agent_id}/documents/{id} Delete deletes a document.
Permanently removes a document and all associated chunks and embeddings. Cannot delete while processing. Returns 400 for invalid ID, 404 if not found, 409 if currently processing, 500 on service error, 204 No Content on success.
Response Codes
| Status Code | Description |
|---|---|
| 204 | Success with no content |
| 400 | Invalid request |
| 404 | Resource not found |
| 500 | Internal server error |
/api/agents/{agent_id}/documents/{id}/download Download returns a presigned URL to download a document.
Generates a time-limited presigned URL for downloading the original document file. URL expires after 15 minutes. Returns 400 for invalid ID or if document has no file, 404 if not found, 500 on URL generation failure, 200 OK with download URL on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
| 500 | Internal server error |
/api/agents/{agent_id}/documents/{id}/sync SyncSource triggers synchronization of a specific knowledge source.
Queues the knowledge source for reprocessing, which includes re-parsing content, regenerating chunks, and updating embeddings. Returns 400 for invalid ID, 404 if not found, 409 if already processing, 500 on service error, 200 OK with sync status on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
| 500 | Internal server error |