Workspace endpoints list every workspace reached through an active membership, show a selected accessible workspace, and update only the session's current workspace. Operator updates cover profile and settings fields; billing-owned plan and platform-owned status are ignored.
Show and update have different scope
GET /workspaces/:id may read any workspace where the user has an active membership. PUT accepts only scope.workspace.id, so a different accessible UUID returns 404 rather than changing session context.
Ownership boundaries protect fields
Operators may edit name, slug, summary, and permitted settings. plan belongs to billing and status belongs to platform administration; supplying either does not make this endpoint authoritative for it.
Before you begin
A signed-in browser session with a selected workspace backed by an active membership is required; an archived workspace remains readable but rejects mutations. Every /api/v1/operator endpoint rejects API credentials and bearer tokens, regardless of their scopes.
Any active membership can list and show accessible workspaces. Only an owner or admin can update the current workspace.
Switch the session to the workspace you intend to edit; membership in another workspace is enough to show it, but not to update it while it is non-current.
How it works
Choose the canonical workspace
List workspaces and compare id, slug, plan, and status. Use the application switcher to make the target current before opening scoped members, invitations, or management routes.
Update carefully
Validate a new slug against lowercase letters, numbers, and hyphens and expect platform-wide uniqueness checks. A supplied settings value replaces the settings map rather than deep-merging it, so preserve keys you still need; then re-read the workspace.
Examples
These examples are illustrative. Replace the sample values with your own.
Keep credentials in environment variables or a secret manager, never in client-side code.
List accessible workspaces
This read is useful before selecting an ID for a current-workspace operation.
javascript
const response = await fetch("/api/v1/operator/workspaces", {
credentials: "same-origin",
headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);
What to expect
200 OK. The response is wrapped in a workspaces array; each row includes id, name, slug, summary, plan, status, settings, and timestamps.
Troubleshooting
Update returns 404 for an accessible workspace
PUT is intentionally narrower than GET: the ID must be the session's current workspace. Switch through /app before trying the update again.
A write returns workspace_archived
Archived workspaces remain readable for history but every operator mutation is blocked. Reactivation is not part of this API.
Endpoint reference
Ready to integrate? Open an endpoint for its required permissions, request fields,
response format, and status codes. The examples above explain the workflow;
these details define each individual request.
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 (CSRF is not required for this read); machine Bearer tokens (`agk_` /
access tokens) are refused with 401
"An authenticated operator session is required."
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.
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 (default 90), data_controls.eval_retention_days (default 180), data_controls.location_retention_days (default 90), data_controls.work_order_evidence_retention_days (default 400), data_controls.auto_purge_enabled (trace/eval only), data_controls.allow_self_serve_exports (stored flag only; does not authorize member exports), data_controls.include_audit_log_exports, data_controls.export_formats. Nonpositive values or values that are not whole numbers of days (including positive fractions) use each default; positive whole values above 36500 days clamp to 36500. The workspace LiveView form rejects over-cap values instead of clamping them. Fleet retention runs separately on rollups regardless of auto_purge_enabled.
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.
