> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creao.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace files

> Upload, list, download, and delete personal workspace files through the Developer API, then bind them to agent runs.

## 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:

1. `POST /v1/workspaces` to create a personal workspace
2. `POST /v1/workspaces/{workspace_id}/files` to upload a CSV, PDF, or image
3. `POST /v1/runs` with the same `workspace_id` and an `agent_id`
4. 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.

<Note>
  Agent skill files stay on [`/v1/agents/{agent_id}/files`](/developer-api/agent-files). That API is list, download, and delete only — it does not upload.
</Note>

## Upload a file

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

```bash theme={null}
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"
```

```json theme={null}
{
  "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

```bash theme={null}
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"
```

```json theme={null}
{
  "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

```bash theme={null}
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"
```

```json theme={null}
{
  "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

```bash theme={null}
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"
```

```json theme={null}
{
  "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.

```bash theme={null}
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](/developer-api/workspace-files/list-workspace-files).