Agents Datasets
API endpoints for Agents Datasets
/api/agents/{agent_id}/datasets List returns datasets for an agent.
Retrieves paginated dataset knowledge sources for the specified agent. Returns 400 for invalid agent ID, 500 on service error, 200 OK with paginated datasets on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 500 | Internal server error |
Success
Response response.PaginatedDatasets
Paginated Datasets
| Property | Type | Description |
|---|---|---|
| data | string[] | Array of datasets for current page |
| meta | string | Pagination metadata |
/api/agents/{agent_id}/datasets Create creates a dataset knowledge source.
Accepts base64-encoded CSV or JSON file and stores it as a dataset for the agent. The dataset is parsed and indexed for RAG retrieval. Returns 404 if agent not found, 400 for validation errors, 500 on storage or creation failure, 201 Created with the dataset on success.
Request Body request.Dataset
Dataset
| Property | Type | Description |
|---|---|---|
| title* | string | Display name for the dataset |
| file_base64* | string | Base64-encoded dataset file content |
| file_filename* | string | Original filename with extension |
| type* | "csv" | "json" | "excel" | File format: csv, json, or excel |
| template* | string | Template for converting rows to text chunks (uses Go template syntax with row data) |
| primary_key_field | string | null | Field name to use as unique identifier for detecting changes |
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.DatasetResponse
Dataset
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique dataset identifier |
| agent_id | integer (int64) | ID of agent this dataset belongs to |
| title | string | Display title |
| file_path | string | Storage path to dataset file |
| type | string | File format: csv, json, or excel |
| template | string | null | Template for converting rows to text |
| primary_key_field | string | null | Field name used as unique identifier |
| ingest_status | string | Processing status (pending, processing, completed, failed) |
| last_unfurled_at | string (date-time) | null | Timestamp when dataset was last processed |
| source_count | integer (int32) | Number of sources generated from dataset |
| created_at | string (date-time) | Timestamp when dataset was created |
| updated_at | string (date-time) | Timestamp when dataset was last updated |
/api/agents/{agent_id}/datasets/{id} Get returns a dataset by ID.
Retrieves a single dataset by its ID. Returns 400 for invalid ID, 404 if not found or belongs to different agent, 200 OK with the dataset on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
Success
Response response.DatasetResponse
Dataset
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique dataset identifier |
| agent_id | integer (int64) | ID of agent this dataset belongs to |
| title | string | Display title |
| file_path | string | Storage path to dataset file |
| type | string | File format: csv, json, or excel |
| template | string | null | Template for converting rows to text |
| primary_key_field | string | null | Field name used as unique identifier |
| ingest_status | string | Processing status (pending, processing, completed, failed) |
| last_unfurled_at | string (date-time) | null | Timestamp when dataset was last processed |
| source_count | integer (int32) | Number of sources generated from dataset |
| created_at | string (date-time) | Timestamp when dataset was created |
| updated_at | string (date-time) | Timestamp when dataset was last updated |
/api/agents/{agent_id}/datasets/analyze Analyze analyzes an uploaded dataset file and saves it temporarily.
Analyzes CSV or JSON file content to detect structure, suggest a template for chunk generation, and return sample fields. Saves the file for later use when creating the dataset. Returns 400 for invalid base64, unsupported file type, or analysis errors, 200 OK with analysis result on success.
Request Body request.DatasetAnalyze
Dataset Analyze
| Property | Type | Description |
|---|---|---|
| file_base64* | string | Base64-encoded dataset file content |
| file_filename* | string | Original filename with extension |
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
| 422 | Validation failed |
| 500 | Internal server error |
/api/agents/{agent_id}/datasets/{id} Update updates a dataset.
Updates the specified dataset with new metadata or settings. When template changes, the ingest status is reset to pending to trigger re-processing. Returns 400 for invalid ID, 404 if not found, 422 for validation errors, 200 OK with the updated dataset on success.
Request Body request.DatasetUpdate
Dataset Update
| Property | Type | Description |
|---|---|---|
| title | string | null | Display name for the dataset |
| template | string | null | Template for converting rows to text chunks |
| primary_key_field | string | null | Field name to use as unique identifier |
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
| 422 | Validation failed |
| 500 | Internal server error |
Success
Response response.DatasetResponse
Dataset
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique dataset identifier |
| agent_id | integer (int64) | ID of agent this dataset belongs to |
| title | string | Display title |
| file_path | string | Storage path to dataset file |
| type | string | File format: csv, json, or excel |
| template | string | null | Template for converting rows to text |
| primary_key_field | string | null | Field name used as unique identifier |
| ingest_status | string | Processing status (pending, processing, completed, failed) |
| last_unfurled_at | string (date-time) | null | Timestamp when dataset was last processed |
| source_count | integer (int32) | Number of sources generated from dataset |
| created_at | string (date-time) | Timestamp when dataset was created |
| updated_at | string (date-time) | Timestamp when dataset was last updated |
/api/agents/{agent_id}/datasets/{id} Delete deletes a dataset.
Permanently removes a dataset 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}/datasets/{id}/process Process triggers reprocessing of a dataset.
Resets the dataset status to pending and enqueues a sync job. This will re-parse the file, recreate sources, and regenerate embeddings. Returns 400 for invalid ID, 404 if not found, 200 OK with processing status on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
| 500 | Internal server error |