Robots Center Agents Network
Log in Create workspace
Skip to content

API reference

Operator - Workspaces

One tag: method, path, summary, auth, and scopes. Request and response fields ship in this page — expand a row to read the contract.

Browse docs

Endpoints

3
GET
/api/v1/operator/workspaces Web Session

List user workspaces

Description

Returns every workspace the signed-in user belongs to. Auth is a browser session plus CSRF (`:operator_api`); machine Bearer tokens (`agk_` / access tokens) are refused with 401 "An authenticated operator session is required."

Auth

Web Session
Responses
200

Workspaces the session user can access

Returns: WorkspaceList
Response Body
Field Type Required Description
workspaces array<object> Yes Workspace records
workspaces[].id string Yes Workspace UUID
workspaces[].name string Yes Workspace name
workspaces[].status string (active, paused, archived) Yes Workspace status (read-only on this API)
workspaces[].plan string (starter, growth, scale) Yes Billing plan (read-only on this API)
workspaces[].settings object Yes Workspace settings map
workspaces[].inserted_at datetime (ISO 8601) Yes Created at
workspaces[].updated_at datetime (ISO 8601) Yes Updated at
workspaces[].summary string No Short description
workspaces[].slug string Yes URL slug
Example
{
  "workspaces": [
    {
      "id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
      "inserted_at": "2026-01-15T10:00:00Z",
      "name": "Acme Corp",
      "plan": "growth",
      "settings": {
        "data_controls": {
          "allow_self_serve_exports": true,
          "auto_purge_enabled": false,
          "eval_retention_days": 180,
          "export_formats": [
            "json"
          ],
          "include_audit_log_exports": true,
          "trace_retention_days": 90
        },
        "observability": {
          "redacted_keys": [
            "authorization",
            "cookie"
          ],
          "redaction_enabled": true
        }
      },
      "slug": "acme-corp",
      "status": "active",
      "summary": "Payments and fulfillment agents",
      "updated_at": "2026-03-27T09:00:00Z"
    }
  ]
}
401

No operator browser session
GET
/api/v1/operator/workspaces/:id Web Session

Get workspace details

Description

Returns one workspace the signed-in user has an active membership in. The path UUID does not have to be the session's current workspace. Disabled or invited memberships do not grant read access (404).

Auth

Web Session
Parameters
Name In Type Required Description
id path string Yes Workspace UUID. Any workspace with an active membership is readable.
Responses
200

Workspace details

Returns: Workspace
Response Body
Field Type Required Description
id string Yes Workspace UUID
name string Yes Workspace name
status string (active, paused, archived) Yes Workspace status (read-only on this API)
plan string (starter, growth, scale) Yes Billing plan (read-only on this API)
settings object Yes Workspace settings map
inserted_at datetime (ISO 8601) Yes Created at
updated_at datetime (ISO 8601) Yes Updated at
summary string No Short description
slug string Yes URL slug
Example
{
  "id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
  "inserted_at": "2026-01-15T10:00:00Z",
  "name": "Acme Corp",
  "plan": "growth",
  "settings": {
    "data_controls": {
      "allow_self_serve_exports": true,
      "auto_purge_enabled": false,
      "eval_retention_days": 180,
      "export_formats": [
        "json"
      ],
      "include_audit_log_exports": true,
      "trace_retention_days": 90
    },
    "observability": {
      "redacted_keys": [
        "authorization",
        "cookie"
      ],
      "redaction_enabled": true
    }
  },
  "slug": "acme-corp",
  "status": "active",
  "summary": "Payments and fulfillment agents",
  "updated_at": "2026-03-27T09:00:00Z"
}
401

No operator browser session
404

Workspace not found or no active membership
PUT
/api/v1/operator/workspaces/:id Web Session

Update workspace

Description

Updates the session's current workspace. `:id` must equal `current_scope.workspace.id`; any other UUID is 404 even if the caller is an owner or admin of that other workspace. Owner/admin only (`403` `admin_required` for members, `read_only_role` for auditors). Writable fields are `name`, `slug`, `summary`, and `settings`. `plan` and `status` are dropped — operators cannot change billing plan or pause/archive via this API. Shipped `settings` keys include `observability.redaction_enabled` / `observability.redacted_keys` and `data_controls` (`trace_retention_days`, `eval_retention_days`, `auto_purge_enabled`, `allow_self_serve_exports`, `include_audit_log_exports`, `export_formats`). `allow_self_serve_exports` is stored only; it does not let a member call the operator export/deletion/purge routes (those still require owner/admin).

Auth

Web Session
Request Body
Field Type Required Description
workspace object Yes Workspace attributes to update
workspace.name string No Workspace name (2–120 characters)
workspace.status string No Ignored. Status is platform-admin only (active | paused | archived).
workspace.plan string No Ignored. Plan is billing-owned and is never written here.
workspace.settings object No Replacement settings map (not deep-merged). Shipped keys: observability.redaction_enabled, observability.redacted_keys, data_controls.trace_retention_days, data_controls.eval_retention_days, data_controls.auto_purge_enabled, data_controls.allow_self_serve_exports (stored flag only; does not authorize member exports), data_controls.include_audit_log_exports, data_controls.export_formats.
workspace.summary string No Short workspace description
workspace.slug string No URL slug (`^[a-z0-9-]+$`); unique across the platform
Parameters
Name In Type Required Description
id path string Yes Must be the session's current workspace UUID. Other workspace IDs 404.
Responses
200

Workspace updated

Returns: Workspace
Response Body
Field Type Required Description
id string Yes Workspace UUID
name string Yes Workspace name
status string (active, paused, archived) Yes Workspace status (read-only on this API)
plan string (starter, growth, scale) Yes Billing plan (read-only on this API)
settings object Yes Workspace settings map
inserted_at datetime (ISO 8601) Yes Created at
updated_at datetime (ISO 8601) Yes Updated at
summary string No Short description
slug string Yes URL slug
Example
{
  "id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
  "inserted_at": "2026-01-15T10:00:00Z",
  "name": "Acme Corp",
  "plan": "growth",
  "settings": {
    "data_controls": {
      "allow_self_serve_exports": true,
      "auto_purge_enabled": false,
      "eval_retention_days": 180,
      "export_formats": [
        "json"
      ],
      "include_audit_log_exports": true,
      "trace_retention_days": 90
    },
    "observability": {
      "redacted_keys": [
        "authorization",
        "cookie"
      ],
      "redaction_enabled": true
    }
  },
  "slug": "acme-corp",
  "status": "active",
  "summary": "Payments and fulfillment agents",
  "updated_at": "2026-03-27T09:00:00Z"
}
401

No operator browser session
403

Owner or admin membership required, or the workspace is archived/read-only
404

Not the session's current workspace, or workspace not found
422

Validation error (name length, slug format/uniqueness)