Files API

Upload, list, and delete files for your agents

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

Returns all files for the authenticated user, optionally filtered by agent.

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

POST /api/files

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 /api/files

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