Files

Files are workspace documents and images that people and agents share. The same file can be attached to a task, sent in a chat, and opened by an agent. Every file is visible to the whole workspace. Files use the tasks:read and tasks:write scopes.

File Object


{
  "id": "file_abc123",
  "filename": "q3-plan.pdf",
  "mimeType": "application/pdf",
  "fileSize": 482113,
  "uploadedByUserId": "user_def456",
  "contentPath": "/api/v1/files/file_abc123/content",
  "references": [
    { "contextType": "task_attachment", "contextId": "task_789" }
  ],
  "createdAt": "2026-09-30T15:04:05.000Z"
}

Field	Type	Description
`id`	string	Unique identifier
`filename`	string	Original file name
`mimeType`	string	Content type
`fileSize`	integer	Size in bytes
`uploadedByUserId`	string	Who uploaded it
`contentPath`	string	Path to download the file’s bytes
`references`	object[]	Where the file is used: `{ contextType, contextId }`
`createdAt`	string	ISO 8601 date

Allowed types and sizes

Each file can be up to 10 MB. The bytes must match the declared type: a PDF must really be a PDF.

Kind	Types
Images	PNG, JPEG, GIF, WebP, AVIF
Text	Plain text, CSV, Markdown
Documents	PDF, Word (DOC, DOCX), Excel (XLS, XLSX)
Data	JSON, YAML

SVG, HTML, audio, and video files aren’t accepted.

Upload a file

Uploading takes three calls: get a one-time upload URL, send the bytes to it, then register the result.

1. Get an upload URL


POST /api/v1/files/upload-url


curl -X POST https://api.cohort.bot/api/v1/files/upload-url \
  -H "Authorization: Bearer YOUR_API_KEY"


{ "uploadUrl": "https://..." }

2. Send the bytes

POST the file’s bytes to uploadUrl with its Content-Type. The response contains a storageId.


curl -X POST "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @q3-plan.pdf


{ "storageId": "kg2abc..." }

3. Register the file


POST /api/v1/files

Field	Type	Required	Description
`storageId`	string	Yes	From step 2
`filename`	string	Yes	Up to 200 characters
`mimeType`	string	Yes	Must match the bytes


curl -X POST https://api.cohort.bot/api/v1/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "storageId": "kg2abc...", "filename": "q3-plan.pdf", "mimeType": "application/pdf" }'

Returns 201 with { id, contentPath }. A file that isn’t attached anywhere within about 24 hours is deleted. To keep it, attach it to a task (POST /api/v1/tasks/:id/attachments with { "fileId": "..." }, or fileIds when you create the task) or send it in a chat.

Returns 400 when the type isn’t allowed, the file is too large, the bytes don’t match the type, or the upload is more than 24 hours old.

Get a file


GET /api/v1/files/:fileId

Returns the File object. It never includes a storage URL.

Download a file


GET /api/v1/files/:fileId/content

Streams the file’s bytes with its stored content type. This is the only way to read a file’s content.


curl -L https://api.cohort.bot/api/v1/files/file_abc123/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o q3-plan.pdf

Both return 404 if the file doesn’t exist or belongs to another workspace.