Workspaces API

Base path: /v1/workspaces

List workspaces

GET /v1/workspaces

Returns workspaces the authenticated user is a member of (via workspace memberships).

Permission: implicit via membership

curl -s -H "Authorization: Bearer $TOKEN" \
  "$CP_URL/v1/workspaces" | jq .

Query parameters

Name	Type	Default	Description
`limit`	integer	100	Max workspaces returned

Response `200`

[
  {
    "id": "8ca7d2a2-…",
    "account_id": "…",
    "name": "Production",
    "slug": "production",
    "status": "active",
    "region": "us-east-1",
    "tenancy_model": "dedicated",
    "created_at": "2026-05-01T12:00:00Z"
  }
]

Create workspace

POST /v1/workspaces

Starts the provisioning saga (environments, Dataplane, SpiceDB relationships). Returns 202 Accepted with a provisioning run ID — not the final workspace synchronously.

Permission: administer on parent account

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"<account_uuid>","name":"Development","region":"us-east-1"}' \
  "$CP_URL/v1/workspaces" | jq .

Request body

Field	Type	Required	Description
`account_id`	uuid	Yes	Parent account
`name`	string	Yes	Display name
`region`	string	Yes	Residency cell
`slug`	string	No	URL slug (auto-generated if omitted)

Get workspace

GET /v1/workspaces/{workspace_id}

Permission: read on workspace

List workspaces by account

GET /v1/workspaces/by-account/{account_id}

Permission: read on account

List environments

GET /v1/workspaces/{workspace_id}/environments

Returns dev, staging, prod environments for the workspace.

Permission: read on workspace

Patch workspace status

PATCH /v1/workspaces/{workspace_id}/status

Freeze or unfreeze a workspace.

Permission: administer on workspace

Export workspace data

GET /v1/workspaces/{workspace_id}/export

Streams a workspace export (CSV/JSON depending on configuration).

Permission: read on workspace

Workspace audit

GET /v1/workspaces/{workspace_id}/audit?limit=50

Permission: read on workspace

All scoped under /v1/workspaces/{workspace_id}/:

Pillar	Path prefix
Secrets	`/secrets`
Files	`/files`
Data Vault	`/vault`
Process Log	`/logs`
Apps	`/apps`
Coderunners	`/coderunners`