Files API
Manage files attached to your agents. You can upload files for an agent to access, list existing files, and delete them. All endpoints require session authentication.
List files
GET /api/files?agentId=default
Query parameters
| Parameter | Type | Required | Description |
|---|
agentId | string | No | Filter files by agent ID |
Response
{
"files": [
{
"id": "clx1abc123",
"filename": "training-data.csv",
"url": "/api/files/download?id=clx1abc123",
"size": 24576,
"mimeType": "text/csv",
"agentId": "default",
"createdAt": "2026-03-25T10:00:00.000Z"
}
],
"totalSize": 24576,
"count": 1
}
File object
| Field | Type | Description |
|---|
id | string | Unique file identifier |
filename | string | Original filename |
url | string | Download URL for the file |
size | number | File size in bytes |
mimeType | string | MIME type of the file |
agentId | string | ID of the agent this file belongs to |
createdAt | string | ISO 8601 timestamp when the file was uploaded |
Errors
| Code | Description |
|---|
| 401 | Unauthorized |
| 500 | Failed to list files |
Upload a file
Upload a file for an agent. The request must use multipart/form-data encoding.
Request body (multipart/form-data)
| Field | Type | Required | Description |
|---|
file | File | Yes | The file to upload |
agentId | string | Yes | ID of the agent to attach the file to |
Response (201)
{
"success": true,
"file": {
"id": "clx1abc123",
"name": "training-data.csv",
"size": 24576,
"type": "text/csv",
"url": "/api/files/download?id=clx1abc123",
"uploaded": "2026-03-25T10:00:00.000Z"
}
}
Upload response fields
| Field | Type | Description |
|---|
file.id | string | Unique file identifier |
file.name | string | Original filename |
file.size | number | File size in bytes |
file.type | string | MIME type of the file |
file.url | string | Download URL for the file |
file.uploaded | string | ISO 8601 timestamp when the file was uploaded |
The GET endpoint returns filename while the POST response returns name. Both refer to the original filename of the uploaded file.
Errors
| Code | Description |
|---|
| 400 | No file provided or agentId required |
| 401 | Unauthorized |
| 404 | Agent not found |
| 413 | Storage limit exceeded — upgrade your plan for more storage |
| 500 | Upload failed |
Delete a file
Delete a file by its ID.
Request body
| Field | Type | Required | Description |
|---|
fileId | string | Yes | ID of the file to delete |
Response
{
"success": true,
"fileId": "clx1abc123"
}
Errors
| Code | Description |
|---|
| 400 | fileId required |
| 401 | Unauthorized |
| 404 | File not found |
| 500 | Delete failed |
