Files API

Base path: /api/files

All endpoints require authentication. See API Overview for auth details.

The Files API manages chat attachments — files uploaded during chat sessions for the agent to read and process. For workspace file management within agent tasks, agents use built-in file tools (read_file, write_file). For project-level file sharing, see the Projects API.

Upload a file

POST /api/files/upload
Content-Type: multipart/form-data

Upload a file as a chat attachment. The file is stored and associated with the current session.

Form fields:

file: the file content (required)

Example:

curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -F "file=@/local/path/document.pdf" \
  http://localhost:18781/api/files/upload

Response:

{
  "id": "att_abc123",
  "filename": "document.pdf",
  "size_bytes": 48291,
  "mime_type": "application/pdf",
  "created_at": "2026-03-02T14:00:00Z"
}

Download a file

GET /api/files/{attachment_id}

Returns the raw file content with the appropriate Content-Type header.

Get a thumbnail

GET /api/files/{attachment_id}/thumbnail

Returns a thumbnail image for image attachments. Returns 404 for non-image files.

Delete a file

DELETE /api/files/{attachment_id}

Response:

{"deleted": true}

Project files

For files shared across agents within a project, use the Projects API:

GET  /api/projects/{project_id}/output-files
POST /api/projects/{project_id}/files/upload
GET  /api/projects/{project_id}/files/raw?path=filename.py

Project files are accessible to any agent assigned to the project and persist for the lifetime of the project.