Workspaces

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

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"]
  }'

{
  "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

curl https://developer.creao.ai/v1/workspaces \
  -H "Authorization: Bearer cr_sk_your_key_here"

{
  "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

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

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"

{
  "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. 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.

Get Started

Agents

Agent Memory

Agent Files

Runs

Models

Workspace Files

Secrets

Skills

Concepts

Workspaces

Overview

Create a workspace

List workspaces

Add an agent

Remove an agent

Workspace files

Errors

​Overview

​Create a workspace

​List workspaces

​Add an agent

​Remove an agent

​Workspace files

​Errors

Overview

Create a workspace

List workspaces

Add an agent

Remove an agent

Workspace files

Errors