Agents Sources
API endpoints for Agents Sources
/api/agents/{agent_id}/sources List returns all knowledge sources for an agent.
Retrieves paginated knowledge sources for the specified agent, including documents, websites, datasets, and FAQs. Returns 400 for invalid agent ID, 500 on service error, 200 OK with paginated sources on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 500 | Internal server error |
Success
Response response.PaginatedSources
Paginated Sources
| Property | Type | Description |
|---|---|---|
| data | string[] | Array of sources for current page |
| meta | string | Pagination metadata |
/api/agents/{agent_id}/sources/{id} Get returns a knowledge source by ID.
Retrieves a single knowledge source by its ID, including type-specific metadata. Returns 400 for invalid ID, 404 if not found, 500 on service error, 200 OK with the source on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
| 500 | Internal server error |
Success
Response response.SourceResponse
Source
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique source identifier |
| agent_id | integer (int64) | ID of agent this source belongs to |
| title | string | Display title |
| extracted_text | string | null | Extracted text content for RAG |
| metadata | object | Custom metadata |
| sourceable_type | string | null | Type of parent sourceable (document, website, dataset, faq, transcript) |
| sourceable_id | integer (int64) | null | ID of parent sourceable |
| url | string | null | Source URL (for website sources) |
| source_record_key | string | null | Unique record key from parent sourceable |
| content_key | string | Unique content key for deduplication |
| sync_status | string | Embedding sync status (pending, syncing, synced, failed) |
| sync_error | string | null | Error message if sync failed |
| synced_at | string (date-time) | null | Timestamp when embeddings were synced |
| sync_batch_id | string | null | Batch identifier for sync operation |
| created_at | string (date-time) | Timestamp when source was created |
| updated_at | string (date-time) | Timestamp when source was last updated |
/api/agents/{agent_id}/sources/rebuild Rebuild triggers a rebuild of all sources.
Resets all sources for the agent to pending status, triggering re-embedding of all content. Returns 404 if agent not found, 200 OK with the count of reset sources on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 404 | Resource not found |
| 500 | Internal server error |
/api/agents/{agent_id}/sources/retry Retry retries syncing failed sources.
Resets the status of failed sources to pending and marks the agent for sync. Can optionally specify source IDs to retry only specific ones.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 404 | Resource not found |
| 500 | Internal server error |
/api/agents/{agent_id}/sources/sync Sync syncs all pending sources for an agent.
Marks the agent as needing sync, which triggers the worker to process pending sources. Returns the number of sources queued.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 404 | Resource not found |
| 500 | Internal server error |
/api/agents/{agent_id}/sources/{id} Update updates a knowledge source.
Updates the specified knowledge source with new metadata. Returns 400 for invalid ID, 404 if not found, 422 for validation errors, 200 OK with the updated source on success.
Request Body request.SourceUpdate
Source Update
| Property | Type | Description |
|---|---|---|
| title | string | null | Display title for the source |
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
| 422 | Validation failed |
| 500 | Internal server error |
Success
Response response.SourceResponse
Source
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique source identifier |
| agent_id | integer (int64) | ID of agent this source belongs to |
| title | string | Display title |
| extracted_text | string | null | Extracted text content for RAG |
| metadata | object | Custom metadata |
| sourceable_type | string | null | Type of parent sourceable (document, website, dataset, faq, transcript) |
| sourceable_id | integer (int64) | null | ID of parent sourceable |
| url | string | null | Source URL (for website sources) |
| source_record_key | string | null | Unique record key from parent sourceable |
| content_key | string | Unique content key for deduplication |
| sync_status | string | Embedding sync status (pending, syncing, synced, failed) |
| sync_error | string | null | Error message if sync failed |
| synced_at | string (date-time) | null | Timestamp when embeddings were synced |
| sync_batch_id | string | null | Batch identifier for sync operation |
| created_at | string (date-time) | Timestamp when source was created |
| updated_at | string (date-time) | Timestamp when source was last updated |
/api/agents/{agent_id}/sources/{id} Delete deletes a knowledge source.
Permanently removes a knowledge source 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}/sources/{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 |
/api/agents/{agent_id}/sources/failed Failed returns failed sources for an agent.
Returns paginated list of sources that failed to sync, including error messages and timestamps.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 404 | Resource not found |
| 500 | Internal server error |
/api/agents/{agent_id}/sources/status Status returns the source sync status for an agent.
Uses the agent_source_status view to aggregate counts from sources and all sourceable tables (documents, websites, datasets, faqs, transcripts). Returns sync status, progress, and processing counts in a single query.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
| 500 | Internal server error |
/api/agents/{agent_id}/sources/cancel Cancel cancels all pending syncs for an agent.
Cancels all in-progress or pending syncs for the agent by marking them as failed with a cancellation message. Returns 404 if agent not found, 200 OK with the count of cancelled sources on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 404 | Resource not found |
| 500 | Internal server error |