Workspace files

Overview

Workspace files are the root uploads in a personal workspace — the same files the CREAO web Files panel shows for that workspace. They are not thread artifacts, agent skill files, personal drive items, or organization shared files. Typical journey:

POST /v1/workspaces to create a personal workspace
POST /v1/workspaces/{workspace_id}/files to upload a CSV, PDF, or image
POST /v1/runs with the same workspace_id and an agent_id
The agent can list and read those files during the run

The agent does not need to be assigned to the workspace. Both the workspace and the agent must belong to the Account API key owner. Team workspaces return WORKSPACE_NOT_FOUND. File operations do not consume credits. Uploading a file with the same display name again creates a new file; it does not overwrite.

Agent skill files stay on /v1/agents/{agent_id}/files. That API is list, download, and delete only — it does not upload.

Upload a file

Send multipart/form-data with a single file field.

curl -X POST https://developer.creao.ai/v1/workspaces/66666666-6666-4666-8666-666666666666/files \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -F "file=@sales.csv"

{
  "id": "55555555-5555-4555-8555-555555555555",
  "name": "sales.csv",
  "mime_type": "text/csv",
  "size_bytes": 1204,
  "sha256": "abc123...",
  "created_at": "2026-08-18T00:00:00.000Z"
}

The response is 201. id is the stable file_id for later get or delete calls. Limits match the web Files panel: 10 MB by default, 100 MB for Volume accounts. Accepted types follow the same allowlist as web uploads (common documents, images, spreadsheets, archives, and code files). Oversized files return 413 FILE_TOO_LARGE. Rejected types return 400 UNSUPPORTED_FILE_TYPE.

List files

curl "https://developer.creao.ai/v1/workspaces/66666666-6666-4666-8666-666666666666/files?limit=20&offset=0" \
  -H "Authorization: Bearer cr_sk_your_key_here"

{
  "files": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "name": "sales.csv",
      "mime_type": "text/csv",
      "size_bytes": 1204,
      "sha256": "abc123...",
      "created_at": "2026-08-18T00:00:00.000Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

Query parameters:

Param	Default	Notes
`limit`	`20`	1–100
`offset`	`0`	Skip this many files
`name_contains`	—	Case-insensitive substring of the display name
`mime_type`	—	Exact MIME type filter

The list includes only workspace-root uploads. Thread products created during chats or runs are not returned.

Download a file

curl https://developer.creao.ai/v1/workspaces/66666666-6666-4666-8666-666666666666/files/55555555-5555-4555-8555-555555555555 \
  -H "Authorization: Bearer cr_sk_your_key_here"

{
  "id": "55555555-5555-4555-8555-555555555555",
  "name": "sales.csv",
  "mime_type": "text/csv",
  "size_bytes": 1204,
  "sha256": "abc123...",
  "created_at": "2026-08-18T00:00:00.000Z",
  "download_url": "https://s3.example/sales.csv?X-Amz-Signature=...",
  "download_url_expires_at": "2026-08-18T01:00:00.000Z"
}

download_url is a presigned URL that expires in 1 hour.

Delete a file

curl -X DELETE https://developer.creao.ai/v1/workspaces/66666666-6666-4666-8666-666666666666/files/55555555-5555-4555-8555-555555555555 \
  -H "Authorization: Bearer cr_sk_your_key_here"

{
  "deleted": true
}

Use files in a run

Pass the same workspace_id on POST /v1/runs or POST /v1/realtime/runs. The agent then sees the uploaded files as workspace uploads.

curl -X POST https://developer.creao.ai/v1/runs \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000",
    "workspace_id": "66666666-6666-4666-8666-666666666666",
    "input": { "task": "Summarize sales.csv" }
  }'

Binding rules:

New conversation — CREAO stores workspace_id on the conversation and returns it on the run.
Existing conversation, omit workspace_id — the run inherits the conversation’s bound workspace.
Existing conversation, first bind — if the conversation has no workspace yet, the provided workspace_id is written.
Mismatch — if the conversation is already bound to a different workspace, the request returns 409 WORKSPACE_MISMATCH.

GET /v1/runs/{run_id} includes workspace_id when the conversation is bound. Agent create and edit runs do not accept workspace_id.

Errors

Code	When
`WORKSPACE_NOT_FOUND`	Workspace is missing, is a team workspace, or is not owned by the API key account
`FILE_NOT_FOUND`	File ID is unknown or is not a root upload in this workspace
`FILE_TOO_LARGE`	File exceeds the account upload size limit
`UNSUPPORTED_FILE_TYPE`	File type is outside the web Files allowlist
`WORKSPACE_MISMATCH`	`workspace_id` on a follow-up run does not match the conversation’s bound workspace
`INVALID_INPUT`	Bad UUID, missing `file` field, or malformed multipart body

See also the OpenAPI operations under Workspace Files.

Get Started

Agents

Agent Memory

Agent Files

Runs

Models

Workspaces

Secrets

Skills

Concepts

Workspace files

Overview

Upload a file

List files

Download a file

Delete a file

Use files in a run

Errors

​Overview

​Upload a file

​List files

​Download a file

​Delete a file

​Use files in a run

​Errors

Overview

Upload a file

List files

Download a file

Delete a file

Use files in a run

Errors