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

# Workspaces

> Create personal workspaces and assign personal CREAO agents through the Developer API.

## Overview

Workspaces group related personal agents. The Developer API can create a workspace, list your personal workspaces, add an agent, and unassign an agent. Team workspaces are not included.

`agent_id` is the same personal-agent UUID used by `/v1/agents` and `/v1/runs`. Adding an agent to a workspace does not copy or delete the agent.

## Create a workspace

```bash theme={null}
curl -X POST https://developer.creao.ai/v1/workspaces \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales research",
    "agent_ids": ["00000000-0000-4000-8000-000000000000"]
  }'
```

```json theme={null}
{
  "id": "66666666-6666-4666-8666-666666666666",
  "name": "Sales research",
  "description": null,
  "agent_ids": ["00000000-0000-4000-8000-000000000000"],
  "created_at": "2026-08-16T00:00:00.000Z",
  "updated_at": "2026-08-16T00:00:00.000Z"
}
```

`name` is required and must be unique among your personal workspaces. Optional `agent_ids` are validated before the workspace is created — if any agent is missing or not personal, the request fails and no workspace is created.

## List workspaces

```bash theme={null}
curl https://developer.creao.ai/v1/workspaces \
  -H "Authorization: Bearer cr_sk_your_key_here"
```

```json theme={null}
{
  "workspaces": [
    {
      "id": "66666666-6666-4666-8666-666666666666",
      "name": "Sales research",
      "description": null,
      "agent_ids": ["00000000-0000-4000-8000-000000000000"],
      "created_at": "2026-08-16T00:00:00.000Z",
      "updated_at": "2026-08-16T00:00:00.000Z"
    }
  ]
}
```

This endpoint is not paginated. Use `GET /v1/workspaces/{workspace_id}` to re-read one workspace after adding or removing agents.

## Add an agent

```bash theme={null}
curl -X POST https://developer.creao.ai/v1/workspaces/66666666-6666-4666-8666-666666666666/agents \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "00000000-0000-4000-8000-000000000000"
  }'
```

The assignment is idempotent. The response is the updated workspace.

## Remove an agent

```bash theme={null}
curl -X DELETE https://developer.creao.ai/v1/workspaces/66666666-6666-4666-8666-666666666666/agents/00000000-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer cr_sk_your_key_here"
```

```json theme={null}
{
  "unassigned": true
}
```

This only removes the workspace membership. The agent remains available for `/v1/runs`.

## Workspace files

Upload, list, download, and delete root files for a personal workspace at `/v1/workspaces/{workspace_id}/files`. Pass the same `workspace_id` on `/v1/runs` so the agent can read those files. See [Workspace files](/developer-api/workspace-files).

The agent does not need to be assigned to the workspace.

## Errors

| Code                       | When                                                                              |
| -------------------------- | --------------------------------------------------------------------------------- |
| `WORKSPACE_NOT_FOUND`      | Workspace is missing, is a team workspace, or is not owned by the API key account |
| `AGENT_NOT_FOUND`          | Agent is missing, not personal, or not owned by the API key account               |
| `DUPLICATE_WORKSPACE_NAME` | A personal workspace with this name already exists                                |
| `INVALID_INPUT`            | Bad UUID, missing `name`, or unknown field                                        |

See also the OpenAPI operations under [Workspaces](/developer-api/workspaces/list-workspaces).