Workspaces - Crewship

A workspace is the top-level tenant in Crewship. Every crew, agent, credential, skill, and pipeline belongs to exactly one workspace, and a user joins a workspace with a role (OWNER, ADMIN, MANAGER, MEMBER, VIEWER). Reach for these endpoints whenever you need to read or change a workspace itself or anything scoped under it — its members and their capabilities, invitations, pipelines and their runs/versions/schedules/webhooks, and the workspace skills registry. The standalone workspace-metadata calls (list/create/get/update) sit at the top; everything else is nested under /api/v1/workspaces/{workspaceId}/....

Workspace-scoped endpoints are nested under /api/v1/workspaces/{workspaceId}/... and require:

A valid JWT session cookie or a CLI token (crewship_cli_…) in the Authorization header.
The authenticated user to be a member of the workspace (enforced by the wsCtx middleware, which also injects workspace_id and role into the request context).

Errors follow RFC 7807 Problem Details — responses include type, title, status, detail, and instance.

Endpoints

Method	Endpoint	Purpose
`GET`	`/api/v1/workspaces`	Every workspace the caller belongs to
`POST`	`/api/v1/workspaces`	Provision a workspace, caller becomes `OWNER`
`GET`	`/api/v1/workspaces/{workspaceId}`	Fetch a single workspace
`PATCH`	`/api/v1/workspaces/{workspaceId}`	Partial update of workspace fields
`DELETE`	`/api/v1/workspaces/{workspaceId}`	Soft-delete the workspace + cascade (`OWNER` only)
`POST`	`/api/v1/workspaces/{workspaceId}/logo`	Upload or replace the workspace logo (`ADMIN+`)
`DELETE`	`/api/v1/workspaces/{workspaceId}/logo`	Remove the workspace logo (`ADMIN+`)
`GET`	`/api/v1/workspaces/{workspaceId}/logo`	Fetch the uploaded logo (any signed-in user)
`GET`	`/api/v1/workspaces/{workspaceId}/members`	All members of the workspace
`POST`	`/api/v1/workspaces/{workspaceId}/members`	Add an existing user by user ID
`POST`	`/api/v1/workspaces/{workspaceId}/members/provision`	Create or add a member by email
`DELETE`	`/api/v1/workspaces/{workspaceId}/members/{memberId}`	Remove a member (not the `OWNER`)
`PATCH`	`/api/v1/workspaces/{workspaceId}/members/{memberId}`	Change a member’s role (`MANAGER+`, ladder-guarded)
`GET`	`/api/v1/workspaces/{workspaceId}/members/{memberId}/capabilities`	Resolved capability set for one member
`PATCH`	`/api/v1/workspaces/{workspaceId}/members/{memberId}/capabilities`	Mutate one member’s capability set
`GET`	`/api/v1/workspaces/{workspaceId}/members/capabilities`	Capabilities for every member in one call
`GET`	`/api/v1/workspaces/{workspaceId}/invitations`	Pending invitations
`POST`	`/api/v1/workspaces/{workspaceId}/invitations`	Issue a token-gated invitation
`GET`	`/api/v1/workspaces/{workspaceId}/pipelines`	Workspace-visible pipelines
`GET`	`/api/v1/workspaces/{workspaceId}/pipelines/{slug}`	One pipeline with full `definition`
`DELETE`	`/api/v1/workspaces/{workspaceId}/pipelines/{slug}`	Soft-delete a pipeline
`POST`	`/api/v1/workspaces/{workspaceId}/pipelines/save`	Create or update a pipeline
`POST`	`/api/v1/workspaces/{workspaceId}/pipelines/fixture_test`	Test one step with explicit sample data; no external actions
`POST`	`/api/v1/workspaces/{workspaceId}/pipelines/{slug}/dry_run`	WouldExecute report + manifest, no agent runs
`POST`	`/api/v1/workspaces/{workspaceId}/pipelines/{slug}/run`	Invoke a saved pipeline
`GET`	`/api/v1/workspaces/{workspaceId}/pipelines/{slug}/runs`	Journal-backed run entries
`GET`	`/api/v1/workspaces/{workspaceId}/pipelines/{slug}/run-records`	Column-typed run projection
`GET`	`/api/v1/workspaces/{workspaceId}/pipelines/runs/active`	In-flight runs (this replica)
`GET`	`/api/v1/workspaces/{workspaceId}/pipeline-runs`	Cross-pipeline run feed
`GET`	`/api/v1/workspaces/{workspaceId}/pipeline-runs/{runId}`	Persisted state of one run
`GET`	`/api/v1/workspaces/{workspaceId}/pipeline-runs/{runId}/files`	Files that changed on the crew during a run (mtime-windowed)
`POST`	`/api/v1/workspaces/{workspaceId}/pipelines/runs/{runId}/cancel`	Cancel an in-flight run
`GET`	`/api/v1/workspaces/{workspaceId}/pipelines/{slug}/versions`	Pipeline version history
`GET`	`/api/v1/workspaces/{workspaceId}/pipelines/{slug}/versions/{n}`	One version with full DSL
`POST`	`/api/v1/workspaces/{workspaceId}/pipelines/{slug}/rollback`	Roll head back to a version
`GET`	`/api/v1/workspaces/{workspaceId}/pipelines/{slug}/export`	Export a portable bundle
`POST`	`/api/v1/workspaces/{workspaceId}/pipelines/import`	Create a pipeline from a bundle
`GET`	`/api/v1/workspaces/{workspaceId}/pipelines/waitpoints`	Pending approval waitpoints
`POST`	`/api/v1/workspaces/{workspaceId}/pipelines/waitpoints/{token}/approve`	Approve / reject a waitpoint
`POST`	`/api/v1/waitpoint-tokens/{token}`	Public token callback — complete a waitpoint with no JWT
`GET`	`/api/v1/workspaces/{workspaceId}/pipeline-schedules`	Cron schedules
`POST`	`/api/v1/workspaces/{workspaceId}/pipeline-schedules`	Create a schedule
`PATCH`	`/api/v1/workspaces/{workspaceId}/pipeline-schedules/{scheduleId}`	Update a schedule
`DELETE`	`/api/v1/workspaces/{workspaceId}/pipeline-schedules/{scheduleId}`	Soft-delete a schedule
`GET`	`/api/v1/workspaces/{workspaceId}/pipeline-webhooks`	Webhooks
`POST`	`/api/v1/workspaces/{workspaceId}/pipeline-webhooks`	Create a webhook
`DELETE`	`/api/v1/workspaces/{workspaceId}/pipeline-webhooks/{webhookId}`	Soft-delete a webhook
`POST`	`/api/v1/workspaces/{workspaceId}/skills/import`	Import one `SKILL.md`
`POST`	`/api/v1/workspaces/{workspaceId}/skills/bulk-import`	Bulk-import skills from a git repo
`POST`	`/api/v1/workspaces/{workspaceId}/skills/generate`	Generate a skill via LLM
`DELETE`	`/api/v1/workspaces/{workspaceId}/skills/{skillId}`	Delete a skill

Workspace metadata

Read and manage the workspace record itself — list the ones you belong to, create new ones, and update name/slug/language.

List workspaces

GET /api/v1/workspaces

Returns every workspace the authenticated user belongs to, ordered by created_at DESC. Soft-deleted workspaces (deleted_at IS NOT NULL) are excluded. Auth: Any authenticated user. Response: 200 OK

[
  {
    "id": "ws_cm1abc123",
    "name": "Acme Robotics",
    "slug": "acme-robotics",
    "logo_url": null,
    "preferred_language": "English",
    "created_at": "2026-04-12T09:18:22Z",
    "updated_at": "2026-05-09T14:02:11Z",
    "currentUserRole": "OWNER",
    "currentUserCapabilities": ["*"],
    "allow_privileged_credentials": false,
    "run_retention_days": null,
    "pages_theme": { "accent": "#0f766e" },
    "_count": { "crews": 4, "agents": 12, "members": 7 },
    "_count_crews": 4,
    "_count_agents": 12,
    "_count_members": 7
  }
]

Field	Type	Description
`id`	string	Workspace ID (CUID)
`name`	string	Display name (2-100 chars)
`slug`	string	URL-safe identifier (2-50 chars, globally unique)
`logo_url`	string?	URL to workspace logo
`preferred_language`	string?	Canonical language name (e.g. `"Czech"`, `"English"`) — see language list
`currentUserRole`	string	Caller’s role in this workspace (`OWNER` / `ADMIN` / `MANAGER` / `MEMBER` / `VIEWER`)
`currentUserCapabilities`	string[]	Resolved capabilities for the caller.
`allow_privileged_credentials`	boolean	Whether privileged crew sidecars may load workspace credentials.
`run_retention_days`	integer?	Workspace pipeline-run retention override; `null` uses the instance default. Present on Update responses.
`credential_audit_retention_days`	integer?	Days of `credential_audit` history to keep. `null` uses the 90-day default; `0` means keep forever. Present on Update responses.
`audit_log_retention_days`	integer?	Days of `audit_logs` history to keep. `null` and `0` both mean keep forever — that is the default, because `audit_logs` is the compliance trail. Present on Update responses.
`approvals_retention_days`	integer?	Days of decided `approvals_queue` history to keep. `null` uses the 90-day default; `0` means keep forever, same as the audit pair above. Present on Update responses.
`pages_theme`	object	The shared Page colours, `{ "accent": "#RRGGBB", … }` over the keys `accent`, `background`, `surface`, `text`, `muted`, `border`. `{}` when unset — the Page SDK then uses its defaults. Always present.
`_count`	object	Canonical nested usage counts: `{ crews, agents, members }`. Always present (zeros included). Prefer this over the flat keys below.
`_count_crews`	integer	Deprecated flat alias for `_count.crews` (omitted when `0`; retained one release for back-compat)
`_count_agents`	integer	Deprecated flat alias for `_count.agents` (omitted when `0`)
`_count_members`	integer	Deprecated flat alias for `_count.members` (omitted when `0`)
`created_at` / `updated_at`	string	RFC 3339 timestamp

Create workspace

POST /api/v1/workspaces

Provisions a new workspace and adds the calling user as OWNER in a single transaction. Auth: Any authenticated user. Request body:

Field	Type	Required	Description
`name`	string	yes	Display name (2-100 chars)
`slug`	string	yes	URL-safe identifier (2-50 chars, must be globally unique)
`preferred_language`	string	no	Either a canonical name (`"Czech"`) or ISO code (`"cs"`, `"pt-BR"`); validated against `validLanguages`. Empty string is allowed and stored as NULL.

{
  "name": "Acme Robotics",
  "slug": "acme-robotics",
  "preferred_language": "en"
}

Response: 201 Created — same shape as the List response item (without currentUserRole / counts).

Status	Condition
`400`	Missing/invalid `name`, `slug`, or `preferred_language`
`401`	Not authenticated
`409`	`slug` already taken

Get workspace

GET /api/v1/workspaces/{workspaceId}

Response: 200 OK — single workspace object (same fields as List) with currentUserRole populated from the JWT.

Status	Condition
`404`	Workspace not found or soft-deleted

Update workspace

PATCH /api/v1/workspaces/{workspaceId}

Partial update — only provided fields are changed. Setting preferred_language to an empty string clears it (NULL). Auth: OWNER or ADMIN (canRole "manage"). Request body: All fields optional.

Field	Type	Description
`name`	string	2-100 chars
`slug`	string	2-50 chars; must remain unique across all workspaces
`preferred_language`	string	Canonical name or ISO code; empty string clears the field
`allow_privileged_credentials`	boolean	Explicitly allow credentials in privileged crew sidecars.
`run_retention_days`	integer	Positive retention override in days.
`credential_audit_retention_days`	integer	Days to keep `credential_audit`. `0` is legal and means keep forever. Negative is rejected.
`audit_log_retention_days`	integer	Days to keep `audit_logs`. `0` is legal and means keep forever. Negative is rejected.
`approvals_retention_days`	integer	Days of decided `approvals_queue` history to keep. `0` is legal and means keep forever. Negative is rejected, and so is anything above `106751` (~292 years) — that is where `days * 24h` overflows an `int64`-nanosecond `time.Duration` and wraps negative, which would move the sweep’s cutoff into the future and delete every terminal row regardless of age.
`pages_theme`	object	The shared colours every custom Page application reads through its `--crewship-page-` design tokens (the Settings → General → Pages appearance* card; CLI: `crewship workspace update --pages-theme`). A JSON object whose keys are a subset of `accent`, `background`, `surface`, `text`, `muted`, `border` and whose values are `#RRGGBB`. It replaces the stored object; omitted keys inherit the SDK defaults and `{}` resets everything. Anything else — another key, a named colour, a string instead of an object, more than 1 KiB — is a 400 naming the rule. Appearance only: no CSS, URLs or execution settings travel here. A change reaches open Pages without rebuilding them.

0 behaves differently on run_retention_days than on the other three: run_retention_days rejects it, while credential_audit_retention_days, audit_log_retention_days and approvals_retention_days all accept it as an explicit “keep forever”. For those three, null means “use the product default” and 0 means never-delete — a distinction that matters because they share one command (workspace update), so 0 has to mean the same thing on all of them or an operator moving between flags gets a silent surprise. approvals_queue earns the same sentinel as the audit pair despite not being a compliance table: AfterDecide’s journal entry captures only approval_id/kind/comment, not reason or the full payload, so approvals_queue is the only place those survive at all, and an operator wanting to keep them indefinitely needs a real way to say so. See Migrations — 20260810170000 and Migrations — 20260901134904.

Response: 200 OK — updated workspace object.

Status	Condition
`400`	Invalid field values
`403`	Caller is not `OWNER`/`ADMIN`
`409`	New `slug` already taken

Workspace logo

POST   /api/v1/workspaces/{workspaceId}/logo     (multipart/form-data, field "file")
DELETE /api/v1/workspaces/{workspaceId}/logo
GET    /api/v1/workspaces/{workspaceId}/logo

The logo the workspace is drawn with in the workspace switcher, Admin lists and the Backups and Security scope; without one it shows its initial. The same rules as a profile picture: PNG, JPEG or WebP, at most 2MB and 4096 px a side. Setting or removing it is ADMIN+ and writes an audit entry (workspace.logo.update / workspace.logo.remove); both answer the workspace object, whose logo_url points at the GET route with a ?v= cache buster (or is null after a removal). The GET route needs a signed-in user but not membership, because instance administrators see every workspace.

Status	Condition
`400`	Not a PNG, JPEG or WebP image, over 2MB, or over 4096 px a side
`403`	Caller is not `OWNER`/`ADMIN`
`404`	`GET`: no logo uploaded
`503`	The server has no storage path configured

CLI: crewship workspace logo set <file> / crewship workspace logo remove.

Delete workspace

DELETE /api/v1/workspaces/{workspaceId}

Soft-deletes the workspace and cascade-soft-deletes its crews and agents (deleted_at is set; membership join rows are removed). Deleted crews stop serving dispatches immediately; their runtime containers are reaped by the orchestrator’s idle-TTL lifecycle, the same path a single crew deletion relies on. On success the server broadcasts realtime events on the workspace channel — a crew.deleted per removed crew and a final workspace.deleted ({ id, slug }) — so connected clients redirect/refresh without a manual reload. Auth: OWNER only. The route sits behind canRole "manage" (ADMIN+) at the router, and the handler additionally requires the caller to be the workspace OWNER. Request body:

Field	Type	Description
`confirm_slug`	string	Must exactly equal the workspace’s `slug`. Type-the-slug confirmation guarding against accidental deletion.

Response: 200 OK — { "success": true }.

Status	Condition
`400`	`confirm_slug` does not match the workspace slug, or invalid body
`403`	Caller is not the workspace `OWNER`
`404`	Workspace not found (or already deleted)
`409`	This is the caller’s only workspace — refused so the owner is not orphaned

Drive it from the CLI with crewship workspace delete.

Members

List the people in a workspace, add an existing user directly, provision a member by email, or remove one.

List members

GET /api/v1/workspaces/{workspaceId}/members

Returns all members of the workspace ordered by created_at ASC, joined to users for display fields. Response: 200 OK

[
  {
    "id": "wm_cm9xyz",
    "workspace_id": "ws_cm1abc123",
    "user_id": "user_jdoe42",
    "role": "OWNER",
    "created_at": "2026-04-12T09:18:22Z",
    "updated_at": "2026-04-12T09:18:22Z",
    "user": {
      "id": "user_jdoe42",
      "email": "jdoe@acme.example",
      "full_name": "Jane Doe",
      "avatar_url": "https://acme.example/avatars/jdoe.png"
    }
  }
]

Add member

POST /api/v1/workspaces/{workspaceId}/members

Adds an existing user to the workspace by user ID.

This takes a user_id and only a user_id. When all you have is an email address — whether or not it already has an account — use Create invitation: resolving an address to a user id here would hand every OWNER/ADMIN the account-existence oracle that signup no longer answers.

Auth: OWNER or ADMIN (canRole "manage"). Request body:

Field	Type	Required	Default	Description
`user_id`	string	yes	—	Target user’s CUID
`role`	string	no	`MEMBER`	One of `ADMIN`, `MANAGER`, `MEMBER`, `VIEWER` (`OWNER` cannot be assigned via API). Assigning `ADMIN` requires the caller to be `OWNER`.

{
  "user_id": "user_jdoe42",
  "role": "MANAGER"
}

Response: 201 Created — the new member row.

Status	Condition
`400`	Missing `user_id`, invalid `role`
`402`	Reserved for future license limits; currently unlimited
`403`	Caller not `OWNER`/`ADMIN`, or tried to assign `ADMIN` without being `OWNER`
`404`	`user_id` does not match any user
`409`	User is already a member

License limit (402 Payment Required)

Current releases allow unlimited members and do not return this license error. Resource licensing may change in future releases. If future enforcement caps the member count, adding a member that would exceed it returns 402 Payment Required with the limit detail in the JSON error body. The check runs before the request body is read, so a capped workspace rejects every add regardless of payload. The same limit applies to Create invitation.

Provision member

POST /api/v1/workspaces/{workspaceId}/members/provision

Creates an account when the email is new, adds it to the workspace, and returns a one-time setup URL. Existing users are not given a setup URL; they must already control their account. The URL expires after seven days. The instance URL must be configured or discoverable by the server. Auth: OWNER or ADMIN (canRole "manage"). Request body: email (required), role (optional; defaults to MEMBER; one of ADMIN, MANAGER, MEMBER, VIEWER), and full_name (optional). Response: 201 Created

{
  "user_id": "user_jdoe42",
  "email": "jdoe@acme.example",
  "role": "MEMBER",
  "created_user": true,
  "setup_url": "https://crewship.example/reset-password?token=…",
  "expires_at": "2026-05-16T09:18:22Z"
}

setup_url is an empty string for an existing account. A malformed email or role returns 400; a caller below ADMIN returns 403; an existing membership returns 409; and a missing public instance URL returns 503.

Remove member

DELETE /api/v1/workspaces/{workspaceId}/members/{memberId}

Removes a workspace member. You cannot remove the workspace OWNER.

Auth: OWNER or ADMIN (canRole "manage"). Response: 200 OK

{ "success": true }

Removal is not just the membership row. Two other things happen, in this order:

Pages the member owns in this workspace are transferred to a crew first, per docs/specs/pages.md §7.1 rule 1b: the crew owning the most panels on the page, else a crew the departing member belongs to. If any page resolves to neither, the whole removal is refused with 409 and nothing changes — reassign those pages by hand and retry.
Every crew membership the user holds in this workspace is deleted, in the same transaction as the workspace_members row: both or neither. Crew membership grants on its own (crew-owned pages, crew credentials, and a per-crew role override folded into the effective role), so it cannot outlive the workspace membership it was predicated on.

Re-adding someone does not restore their crews. POST .../members creates a workspace membership and nothing else, so a returning member must be added back to each crew by hand, including any per-crew role override they held. This is deliberate: an override that survived a departure would silently re-elevate a user re-added at a lower role.

Crews in other workspaces are untouched — the purge is scoped through crews.workspace_id.

Status	Condition
`403`	Caller not `OWNER`/`ADMIN`, or target member is the `OWNER`
`404`	`memberId` not found in this workspace
`409`	The member owns a page that resolves to no crew (see above)

Change member role

PATCH /api/v1/workspaces/{workspaceId}/members/{memberId}

Changes a member’s workspace role. Gated at MANAGER+ (canRole "create"), then subject to the role ladder enforced in the handler. Auth: MANAGER or above, plus the ladder:

You may only grant a role strictly below your own (roleRank[new] >= roleRank[caller] is rejected). An OWNER can therefore grant up to ADMIN, an ADMIN up to MANAGER, and so on. This means ownership is not transferable through this endpoint.
You may not modify a member ranked above your own.
The last OWNER cannot be demoted.

Request body:

Field	Type	Description
`role`	string	Target role: one of `OWNER`, `ADMIN`, `MANAGER`, `MEMBER`, `VIEWER`.

Response: 200 OK

{ "status": "updated", "member_id": "mem_abc123", "role": "MANAGER" }

Status	Condition
`400`	Unknown role, or invalid body
`403`	Caller below `MANAGER`; target ranked above the caller; or granted role ≥ caller’s own
`404`	`memberId` not found in this workspace
`409`	Demoting the last `OWNER`

Drive it from the CLI with crewship workspace member role.

Member capabilities

Capabilities are per-member string grants layered on top of a member’s RBAC role. They let a workspace admin hand an individual user a specific higher-tier action — “let this MEMBER create routines” — without promoting them to MANAGER. The role still sets the baseline; capabilities only ever widen it. The closed set of ten capabilities (allCapabilities in internal/api/capabilities.go):

Capability	Gates
`chat`	Baseline — talk to agents. Always implied; every member has it even when the stored set omits it, and it cannot be revoked (remove the member instead).
`routine.create`	Create pipeline schedules (cron-driven routines)
`routine.run`	Invoke an existing routine, and see it in the slash palette. Distinct from `routine.create`: authoring a routine writes a definition somebody still has to approve, while running one executes inside the author crew’s container with its credentials, now.
`skill.create`	Generate / import skills
`credential.create`	Create credential rows (fresh secret material in the vault). Does not extend to provider accounts, which stay OWNER/ADMIN-only.
`credential.rotate`	Rotate an existing credential’s value
`credentials:reveal`	Disclose a stored secret’s plaintext to a human through reveal. Spelled with a colon, as the security document names it. Necessary but not sufficient: the workspace switch, an interactive fresh sign-in, scope, classification and the audit write still gate every disclosure.
`issue.create`	File issues
`page.create`	Author a Page (`POST /api/v1/pages`); a MANAGER+ action by default, this lets a specific MEMBER do it. In no preset.
`memory.write`	Write to agent / crew / workspace memory via `/remember`

Presets are named bundles for the common combinations:

Preset	Capabilities
`chat`	`chat`
`power`	`chat`, `routine.create`, `routine.run`, `issue.create`, `memory.write`
`admin`	`chat`, `routine.create`, `routine.run`, `skill.create`, `credential.create`, `credential.rotate`, `credentials:reveal`, `issue.create`, `memory.write` (everything but `page.create`)

A member with no explicit set falls back to a role-derived default (OWNER/ADMIN → the v109 admin set (no routine.run) plus credentials:reveal, MANAGER → chat + routine.create + issue.create + memory.write, others → chat). An explicit set is always authoritative, so revoking credentials:reveal from an ADMIN sticks. That fallback is not the preset of the same name. It reproduces what the v109 migration wrote into the capability column, so a row the migration filled and a row still NULL resolve identically — and that migration ran before routine.run existed, so the fallback does not include it while the power and admin presets do. Nothing rests on the difference: every role at MANAGER+ clears the run gate on role alone. The capability lists returned by these endpoints are always sorted alphabetically. All three endpoints require the caller to be ADMIN or OWNER.

Path-param note: on the per-member capability endpoints the {memberId} segment is the member’s user ID (it is matched against workspace_members.user_id), not the workspace_members.id row ID used by Remove member. The user_id field in the response echoes the value you passed in.

Get member capabilities

GET /api/v1/workspaces/{workspaceId}/members/{memberId}/capabilities

Returns the resolved capability set and role for a single member. Listing a member’s capabilities reveals the workspace’s permission topology, so the endpoint is admin-gated. Auth: ADMIN or OWNER. Response: 200 OK

{
  "user_id": "user_jdoe42",
  "role": "MEMBER",
  "capabilities": ["chat", "issue.create", "routine.create"]
}

Status	Condition
`403`	Caller below `ADMIN`
`404`	`memberId` not found in this workspace

Update member capabilities

PATCH /api/v1/workspaces/{workspaceId}/members/{memberId}/capabilities

Mutates a member’s capability set. The body must contain exactly one of four mutation shapes:

Field	Type	Effect
`set`	string[]	Replace the entire set with these capabilities
`grant`	string[]	Add these to the current set
`revoke`	string[]	Remove these from the current set
`preset`	string	Apply a named bundle — `"chat"`, `"power"`, or `"admin"`

Empty arrays are rejected (a 400, not treated as a no-op) — to reset a member to chat-only, send {"set": ["chat"]} explicitly. chat is always implied: it is silently kept on set, and revoking it is rejected.

{ "preset": "power" }

{ "grant": ["routine.create", "issue.create"] }

Auth: ADMIN or OWNER. Guards:

A caller cannot mutate their own capability row (defence against a downgrade-then-restore stunt) — 403.
OWNER capability rows are immutable — any attempt returns 403.
The request body is capped at 16 KB — a larger body returns 413.

Response: 200 OK — the post-mutation state (same shape as Get):

{
  "user_id": "user_jdoe42",
  "role": "MEMBER",
  "capabilities": ["chat", "issue.create", "memory.write", "routine.create"]
}

Status	Condition
`400`	Zero or more than one mutation shape, empty array, unknown capability / preset, attempt to revoke `chat`, invalid JSON
`401`	Not authenticated
`403`	Caller below `ADMIN`, caller mutating own row, or target is an `OWNER`
`404`	`memberId` not found (including a row deleted concurrently mid-update)
`413`	Request body exceeds 16 KB

List all member capabilities (bulk)

GET /api/v1/workspaces/{workspaceId}/members/capabilities

Returns the resolved capabilities for every member of the workspace in one round-trip — this drives Settings → Members without an N+1 fan-out across the per-member endpoint. The roster fetches it once on load, whether or not any row is expanded, because each collapsed row summarises that member’s grants. Rows are ordered by membership created_at ASC so the roster renders stably between page loads. Auth: ADMIN or OWNER. Response: 200 OK

{
  "members": [
    {
      "user_id": "user_jdoe42",
      "role": "OWNER",
      "capabilities": ["chat", "credential.create", "credential.rotate", "credentials:reveal", "issue.create", "memory.write", "routine.create", "skill.create"]
    },
    {
      "user_id": "user_asmith7",
      "role": "MEMBER",
      "capabilities": ["chat", "issue.create"]
    }
  ]
}

Status	Condition
`403`	Caller below `ADMIN`

Invitations

Invitations issue a token-gated link that the recipient redeems via the auth flow. They expire after 7 days.

List invitations

GET /api/v1/workspaces/{workspaceId}/invitations

Returns pending (un-accepted) invitations ordered by created_at DESC, joined to users for the inviter. Response: 200 OK

[
  {
    "id": "inv_cm0aaa1",
    "workspace_id": "ws_cm1abc123",
    "email": "newhire@acme.example",
    "role": "MEMBER",
    "invited_by": "user_jdoe42",
    "token": "EXAMPLE-NOT-A-REAL-32-BYTE-HEX-TOKEN",
    "expires_at": "2026-05-26T09:18:22Z",
    "accepted_at": null,
    "created_at": "2026-05-19T09:18:22Z",
    "inviter": {
      "id": "user_jdoe42",
      "email": "jdoe@acme.example",
      "full_name": "Jane Doe"
    }
  }
]

Create invitation

POST /api/v1/workspaces/{workspaceId}/invitations

Auth: OWNER or ADMIN (canRole "manage"). Assigning the ADMIN role requires the caller to be OWNER. Request body:

Field	Type	Required	Default	Description
`email`	string	yes	—	Recipient email
`role`	string	no	`MEMBER`	One of `ADMIN`, `MANAGER`, `MEMBER`, `VIEWER`

Response: 201 Created — invitation object with the freshly minted hex token (this is the only time the token is returned). Invitations are redeemed at signup: when the invited address creates an account via POST /api/v1/auth/signup, every live invitation for that address is consumed inside the same transaction and the new user lands in each inviting workspace at the invited role. An invited person gets no default workspace of their own; only a signup with nothing to redeem (no live invitation to a workspace that still exists) gets one. An invitation for an address that already has an account is left pending — signup is a no-op there, and redeeming it would place someone who never consented. This is also why POST .../members takes a user_id and not an email: resolving an arbitrary address would be an account-existence oracle.

Status	Condition
`400`	Missing/invalid email or role
`402`	Reserved for future license limits; currently unlimited
`403`	Caller not `OWNER`/`ADMIN`, or tried to invite as `ADMIN` without being `OWNER`
`409`	Email belongs to an existing member, or there’s already a non-expired invitation for this email

Pipelines

Pipelines (also called routines in the UI) are versioned, workspace-scoped DSL programs that orchestrate agent runs, sub-pipeline calls, parallel forks, and approval waitpoints. See the Pipelines guide and the DSL reference for authoring details.

List pipelines

GET /api/v1/workspaces/{workspaceId}/pipelines

Returns workspace-visible, non-ephemeral pipelines. Each row is enriched with author_agent_name (best-effort lookup) and the most recent 3 issue identifiers bound via missions.routine_id so the UI can render an “ENG-5, ENG-9 +1” chip without a second fetch. Query parameters:

Parameter	Type	Default	Description
`include_ephemeral`	`1`	off	Include auto-generated delegation-wrap pipelines
`include_hidden`	`1`	off	Include rows with `workspace_visible=0`
`author_crew_id`	string	—	Filter to one author crew
`order`	`popularity` / `recent` / `name`	`popularity`	Sort order

Response: 200 OK

[
  {
    "step_count": 4,
    "head_version": 3,
    "last_recorded_run_id": "prun_01J...",
    "last_run_outcome": "SUCCEEDED",
    "id": "pipe_cmRoutine42",
    "slug": "weekly-changelog",
    "name": "Weekly changelog",
    "description": "Summarise merged PRs into the public changelog",
    "dsl_version": "v1",
    "definition_hash": "f3c1...",
    "ephemeral": false,
    "workspace_visible": true,
    "invocation_count": 17,
    "last_invoked_at": "2026-05-18T08:00:00Z",
    "last_invocation_status": "completed",
    "status": "active",
    "icon": "calendar",
    "color": "violet",
    "author_crew_id": "crew_eng",
    "author_agent_id": "agent_eva",
    "author_agent_name": "Eva",
    "author_user_id": "",
    "authored_via": "agent",
    "linked_issue_count": 3,
    "linked_issues": ["ENG-5", "ENG-9", "ENG-12"],
    "created_at": "2026-04-30T11:00:00Z",
    "updated_at": "2026-05-18T08:00:01Z"
  }
]

The definition field is omitted from the List response and only returned by Get pipeline. step_count is the number of steps in the stored definition (omitted when the definition no longer parses). head_version is the published version the routine currently runs. last_recorded_run_id, last_run_outcome, last_invoked_at and last_invocation_status (lowercase: completed, failed, waiting, …) come from the most recent pipeline_runs row on both List and Get, and are omitted while the routine has never run. status is the governance state (active, proposed or disabled); icon and color are the presentation choices and are omitted until one is chosen.

Get pipeline

GET /api/v1/workspaces/{workspaceId}/pipelines/{slug}

Returns the same shape as List but with the full definition (raw DSL JSON) inlined.

Status	Condition
`404`	Pipeline not found in this workspace

Delete pipeline

DELETE /api/v1/workspaces/{workspaceId}/pipelines/{slug}

Soft-deletes the pipeline (deleted_at set). Versions, run history, and bound schedules/webhooks are retained.

Auth: OWNER or ADMIN (canRole "delete"). Response: 204 No Content

Status	Condition
`403`	Caller below `ADMIN`
`404`	Pipeline not found

List routine drafts

GET /api/v1/workspaces/{workspaceId}/pipelines/drafts

Auth: workspace MANAGER+. Response: 200 OK, an array of up to 100 {slug, revision, updated_at} entries, newest edit first. Draft documents are read separately. 403 means insufficient role; 500 means the draft list could not be read.

Read a routine draft

GET /api/v1/workspaces/{workspaceId}/pipelines/{slug}/draft

Auth: workspace MANAGER+. Response: 200 OK, a RoutineDraft envelope containing id, workspace_id, slug, revision, base_pipeline_id, base_revision, document, updated_by, created_at and updated_at. With no saved draft, revision zero describes the current published recipe and its base revision. With no published recipe either, the document is {} and the base ID is empty. Missing drafts are therefore not 404. 403 means insufficient role; 500 means the read failed.

Save a routine draft

POST /api/v1/workspaces/{workspaceId}/pipelines/drafts

Auth: workspace MANAGER+; the authenticated user supplies updated_by. Request body: the draft envelope returned by the read operation, with edits inside document. Preserve id, revision, base_pipeline_id and base_revision. The document contains the ordinary save fields, including slug, name, description and an object definition; its slug must match the envelope. Incomplete definitions can be saved. Temporary publication tokens and legacy validation/governance bypass fields are discarded. Response: 200 OK, the exact newly stored RoutineDraft with its incremented revision. An unpublished draft can move to a free slug without changing its ID; a draft editing a published recipe cannot. Saving does not publish or activate a trigger. 400 means malformed input; 403 means insufficient role; 409 means the revision/base changed or the target slug is occupied; 500 means the write failed. Keep the returned envelope for the next edit or publication.

Discard a routine draft

DELETE /api/v1/workspaces/{workspaceId}/pipelines/{slug}/draft

Auth: workspace MANAGER+. Request body: {"id":"draft-id","revision":2}. Both identify the exact saved draft; a discarded and recreated draft has a different ID. Response: 204 No Content. Only that draft revision is deleted. 400 means invalid JSON; 403 means insufficient role; 409 means the ID/revision no longer matches; 500 means deletion failed. The published recipe remains available.

Publish a routine draft

POST /api/v1/workspaces/{workspaceId}/pipelines/{slug}/publish

Auth: workspace MANAGER+; normal publication capability review still applies. Request body: {"id":"draft-id","revision":2,"save_token":"...","approve_risk":false}. First obtain save_token from POST /api/v1/workspaces/{workspaceId}/pipelines/test_run for the exact saved definition and author crew. approve_risk: true explicitly confirms capability changes when publication reports that review is needed. Response: 201 Created, the saved recipe (RoutinePublishResponse) with its version and optional trigger result. Publishing atomically verifies and consumes the exact draft, checks its published base, and saves the recipe and trigger. Enabled recurring schedules that follow the head must have compatible inputs; disabled and version-pinned schedules do not block publication. 400 means malformed input; 403 means insufficient role; 409 means stale revision/base, capability review required, or incompatible schedule inputs; 422 means an invalid definition, trigger or publication proof; 500 means storage failed. Conflicts preserve both the draft and published recipe. A schedule conflict includes schedule_conflict: {schedule_id, name, reason}; a capability-review conflict includes risk_reasons.

Save pipeline

POST /api/v1/workspaces/{workspaceId}/pipelines/save

Creates or updates a pipeline for the calling user. authored_via is always set to "user_api" and author_user_id is extracted from the JWT (callers cannot forge identity). Auth: MANAGER+ (canRole "create"). Request body:

Field	Type	Required	Description
`slug`	string	yes	URL-safe pipeline slug
`name`	string	no	Display name (falls back to `slug`)
`description`	string	no	—
`definition`	object	yes	DSL JSON document
`author_crew_id`	string	no	Pin a crew context for runtime resolution; without it, runs fall back to the first crew the saving user belongs to
`author_agent_id`	string	no	The agent the routine acts as — every `crewship` step dispatches under this identity. Must be an agent of `author_crew_id` (`400` otherwise). Required when the definition contains a `crewship` step using `issue.comment`, which cannot be attributed to “nobody”; `authored_via` still records `user_api`
`last_test_run_at`	string	conditional	RFC 3339 timestamp (within the last 5 minutes) clearing the validation gate; required unless `skip_test_gate` is used
`last_test_run_passed`	boolean	conditional	Must be `true` if relying on body-trust
`skip_test_gate`	boolean	no	OWNER/ADMIN-only escape hatch — bypass the 5-minute validation gate entirely
`save_token`	string	no	HMAC proof minted by `test_run` for this exact definition and caller; the path the UI and CLI take to clear the validation gate. An invalid or expired token is `422`
`skip_governance_gate`	boolean	no	OWNER/ADMIN-only — save a risky definition as `active` instead of parking it `proposed` for review
`change_summary`	string	no	One-line provenance note stored on the version row (shown by `routine versions` and the Versions view)
`trigger`	object	no	Create a trigger in the same transaction as the routine and its version — see Pipelines § Atomic trigger authoring. `trigger.inputs` is the preset an enabled plan following head must satisfy
`activation`	string	no	`"draft"` creates the `trigger` disabled and raises one approval item; only meaningful with `trigger`

Response: 201 Created — full pipeline object including definition, plus trigger when the body requested one.

Status	Condition
`400`	Missing `slug` or `definition`, invalid JSON, or `author_agent_id` that is not an agent of `author_crew_id`
`401`	Not authenticated
`403`	Role below `MANAGER`, or `skip_test_gate` / `skip_governance_gate` requested without OWNER/ADMIN
`409`	Slug already exists in this workspace, or an enabled plan that follows head carries inputs the new definition rejects (`schedule_conflict`, below)
`422`	DSL parse / validate / cycle-detect failure, a `crewship` step needing an acting agent on a routine with no `author_agent_id`, an invalid `trigger` block, or validation gate not satisfied

A 409 from the schedule-preset gate carries the plan that blocks the save so a client can open it rather than parse prose:

{
  "error": "publication blocked by schedule Nightly: Input region is required by the new recipe",
  "hint": "Update this plan's inputs in the same save (send a `trigger` block), repair the plan first if the new inputs already fit, or disable the plan, publish, then repair its inputs before re-enabling it.",
  "schedule_conflict": { "schedule_id": "psched_...", "name": "Nightly", "reason": "Input region is required by the new recipe" }
}

error is always publication blocked by schedule <name>: <reason>. reason is Input <name> is required by the new recipe for a missing required input, input "<name>": <what is wrong> for a value of the wrong type or outside its choices, or Stored inputs are unreadable. Two kinds of enabled plan are judged: plans that target this routine and follow head (no version pin), against their inputs; and plans that use this routine as their wake probe, pinned or not, against their wake_inputs. Disabled plans, and pinned plans targeting the routine, never block a save. A re-save whose definition is byte-identical to the stored one is never judged either, so a rename or description edit cannot start failing over a preset that was already imperfect. The same envelope comes back from Import, Rollback and the sidecar’s save_routine door. The definition is left unchanged on 409.

Test an unpublished definition

POST /api/v1/workspaces/{workspaceId}/pipelines/test_run

Auth: authenticated workspace MANAGER+. Request body: definition (object, required), author_crew_id (optional string belonging to this workspace), and sample_inputs (optional object). The endpoint checks the definition and applicable resource gates, then produces a static execution plan. It does not execute agents, scripts or HTTP steps. Response: 200 OK, a RunResult. A successful DRY_RUN_OK result includes save_token when the server’s signing key is configured. Send that token to /publish or /save within five minutes, with the same definition bytes. The token is bound to this workspace, authenticated user and definition hash; a successful response without a token is insufficient for normal publication. 400 means malformed input, 403 includes foreign crew references, 422 means an invalid definition, and 503 means the runner is not wired. Resource gates can also refuse the test with their specific missing-resource response. The separate sidecar endpoint /api/v1/internal/pipelines/test_run authenticates with X-Internal-Token. For actual external work, use Run.

Dry-run a saved pipeline

POST /api/v1/workspaces/{workspaceId}/pipelines/{slug}/dry_run

Returns the structured WouldExecute report for the supplied inputs plus the routine’s declared manifest — no agent invocations, no journal entries. The dry-run is an honest static plan, not a proof the run will succeed. Request body: Same shape as Run. All fields optional. Response: 200 OK — a RunResult (with would_execute) plus a sibling manifest object:

{
  "status": "DRY_RUN_OK",
  "would_execute": [ /* per-step plan */ ],
  "manifest": {
    "integrations": ["github", "slack"],
    "egress": ["api.example.com", "discord.com"],
    "credentials": [{ "type": "stripe" }],
    "agents": ["jordan"],
    "routines": [],
    "datastores": [{ "type": "postgres", "name": "main" }],
    "tools": [{ "type": "ansible", "name": "deploy.yml" }],
    "has_http": true,
    "has_code": false
  }
}

manifest is the routine’s full declared blast radius. It is best-effort: a stored definition that no longer parses leaves manifest null and still returns the report.

Run pipeline

POST /api/v1/workspaces/{workspaceId}/pipelines/{slug}/run

Invokes a saved pipeline. Returns synchronously with the full RunResult; for live progress, subscribe to the workspace WebSocket channel and filter pipeline.* journal entries by run_id. Request body:

Field	Type	Default	Description
`inputs`	object	`{}`	Input map — defaults from the pipeline’s input spec are applied for missing keys
`pinned_version`	integer	—	Run an archived version; the routine must still pass current governance and dependency gates.
`expected_definition_hash`	string	—	SHA-256 hash of the reviewed definition. For HEAD, a changed hash returns `409`; an accepted immediate start pins that archived version before dispatch. With `pinned_version`, checks the selected archive. Not supported for delayed, debounced or one-time starts. Mutable step overrides are skipped for this reviewed start.
`tier_override`	string	—	One of `trivial` / `fast` / `moderate` / `smart` — replaces every `agent_run` step’s complexity for this run only. Unknown values are silently ignored.
`triggered_via`	string	`manual`	Closed enum: `manual`, `schedule`, `webhook`, `call_pipeline`, `issue`
`triggered_by_id`	string	—	Free-form attribution id (e.g. an issue identifier when `triggered_via=issue`)

Headers:

Header	Description
`Idempotency-Key`	Dedupes redeliveries within 24h — a second request with the same key returns the original run with `status="DEDUPED"`. Falls through silently when the idempotency store isn’t wired.

Runs started on this route are recorded as user-driven: invoking_user_id is the authenticated caller and invoking_crew_id / invoking_agent_id are empty. The route does not read any X-Crewship-Invoking-* header — a JWT or CLI-token caller has no verified crew or agent identity, and a header would only let a member attribute the run (and the “From” crew on any approval card it raises) to a crew of their choosing. Agent-invoked runs are attributed through the sidecar’s run_routine tool, whose identity fields are checked server-side against the internal token’s crew binding and the agents table. Response: 200 OK — RunResult.

Status	Condition
`404`	Pipeline not found
`409`	The recipe changed since preview; refresh it before starting.
`422`	A required credential, integration or resource is confirmed missing.
`429`	A run with the same `concurrency_key` is already in flight (sets `Retry-After: 5`)
`503`	Runner not wired, or the credential store is unavailable so a required-credential check cannot be decided — both fail closed rather than dispatch without the check.

`RunResult` shape

{
  "run_id": "run_cm9abc",
  "pipeline_id": "pipe_cmRoutine42",
  "status": "COMPLETED",
  "mode": "run",
  "output": "Drafted changelog for sprint 42",
  "step_outputs": {
    "draft": "...",
    "review": "..."
  },
  "cost_usd": 0.0241,
  "duration_ms": 18432,
  "deduped": false
}

Step failures. The status codes above are decided before dispatch. Once the run is executing, a failing step does not change the HTTP status: it fails the run, and the RunResult comes back 200 with status: "FAILED", failed_at_step and error_message. In particular, an HTTP step whose credential_ref cannot be resolved — the credential is missing, empty, or the credential store errors — fails that step before the request is sent; the step error names only the declared credential type (internal/pipeline/runner_http.go).

List pipeline runs (journal-backed)

GET /api/v1/workspaces/{workspaceId}/pipelines/{slug}/runs

Returns pipeline.run.* journal entries for the named pipeline, newest first. Query parameters:

Parameter	Type	Default	Description
`limit`	integer	50	Hard cap 500
`include_steps`	`1`	off	Widen to `pipeline.` (also include `pipeline.step.` entries for the waterfall view)

Each row carries id, ts, entry_type, severity, summary, pipeline_id, run_id, and the raw payload.

List pipeline run records (projection table)

GET /api/v1/workspaces/{workspaceId}/pipelines/{slug}/run-records

Column-typed scan over pipeline_runs (migration v83). Faster than /runs because it skips the journal LIKE-pattern + json_extract path. Returns 503 with a legacy: "/runs" hint when the run store isn’t wired. Query parameters:

Parameter	Type	Default	Description
`limit`	integer	50	Hard cap 500
`status`	string	—	Filter to a single `RunStatus` (`queued`, `running`, `completed`, `failed`, `cancelled`; plus `dry_run` / `interrupted`). There is no `paused` run status here — a run waiting on an approval keeps its `running` status in this table.

Response: 200 OK — array of run records. Each record:

{
  "id": "run_cm9abc",
  "pipeline_id": "pipe_cmRoutine42",
  "pipeline_slug": "weekly-changelog",
  "status": "completed",
  "mode": "run",
  "started_at": "2026-05-18T08:00:00.123456Z",
  "ended_at": "2026-05-18T08:00:18.555432Z",
  "current_step_id": "",
  "output": "Drafted changelog for sprint 42",
  "cost_usd": 0.0241,
  "duration_ms": 18432,
  "error_message": "",
  "failed_at_step": "",
  "error_fingerprint": "",
  "triggered_via": "manual",
  "triggered_by_id": "",
  "idempotency_key": ""
}

error_message is sanitised in this view (single-line, ≤200 chars). The full error stays in journal_entries.

List active runs (in-memory registry)

GET /api/v1/workspaces/{workspaceId}/pipelines/runs/active

Returns the in-flight run set scoped to this workspace from the in-memory RunRegistry. Used by the dashboard’s “running now” badge and cancel buttons. Single-instance scope — in a multi-replica deployment, each replica only sees its own runs until a shared registry lands. Returns an empty list when the registry is not wired. Response: 200 OK

[
  {
    "run_id": "run_cm9abc",
    "workspace_id": "ws_cm1abc123",
    "pipeline_id": "pipe_cmRoutine42",
    "pipeline_slug": "weekly-changelog",
    "concurrency_key": "weekly-changelog:main",
    "started_at": "2026-05-19T08:00:00.123456Z",
    "cancel_requested": false
  }
]

List workspace runs (cross-pipeline feed)

GET /api/v1/workspaces/{workspaceId}/pipeline-runs

Workspace-scoped run feed for the /activity page. Returns recent runs across every pipeline with enrichment (pipeline_name, issue_identifier when triggered_via=issue). Sorted by started_at DESC. step_outputs is deliberately not included in this feed — it can carry many KB of agent transcript/tool-result JSON per row, and this endpoint is polled every few seconds by the dashboard. Fetch Get pipeline run for a specific run id to get its step outputs. Query parameters:

Parameter	Type	Default	Description
`limit`	integer	50	Hard cap 200
`status`	string	—	Filter; `active` is a dashboard shortcut for `running + queued + paused`
`since`	string (RFC 3339)	—	`created_at` lower bound for cursor pagination

Response: 200 OK

{
  "rows": [
    {
      "id": "run_cm9abc",
      "pipeline_id": "pipe_cmRoutine42",
      "pipeline_slug": "weekly-changelog",
      "pipeline_name": "Weekly changelog",
      "status": "running",
      "mode": "run",
      "started_at": "2026-05-19T08:00:00.123456Z",
      "ended_at": "",
      "current_step_id": "review",
      "cost_usd": 0.012,
      "duration_ms": 4321,
      "triggered_via": "schedule",
      "triggered_by_id": "sched_cmWeekly",
      "invoking_crew_id": "",
      "invoking_agent_id": "",
      "invoking_user_id": "",
      "error_message": "",
      "failed_at_step": "",
      "issue_identifier": ""
    }
  ],
  "count": 1
}

Get pipeline run

GET /api/v1/workspaces/{workspaceId}/pipeline-runs/{runId}

Returns the persisted state of a single run from pipeline_runs, joined to pipelines and missions for human-readable enrichment. step_outputs_json is parsed server-side into an object so the UI does not have to JSON.parse twice. Response: 200 OK — single row. Includes id, workspace_id, pipeline_id, pipeline_slug, pipeline_name, status, mode, current_step_id, step_outputs (parsed), output, started_at, ended_at, error_message, failed_at_step, cost_usd, duration_ms, triggered_via, triggered_by_id, idempotency_key, inputs (parsed), and issue_identifier. Unlike the workspace-runs feed, this view does not carry the invoking_crew_id / invoking_agent_id / invoking_user_id attribution fields.

Status	Condition
`404`	Run not found in this workspace

Run-window file changes

GET /api/v1/workspaces/{workspaceId}/pipeline-runs/{runId}/files

Lists the files that changed on a run’s crew inside the run window — the deliverable for document-processing routines. Read-time, non-invasive: the run is resolved to its crew (invoking_crew_id, falling back to the pipeline’s author_crew_id), the crew’s host files are listed over the same IPC path the agent/crew file endpoints use (agent /output + /crew/shared), and only files whose modification time falls inside the run’s [started_at, ended_at] window are returned. A still-running run uses “now” as the upper bound. Auth: read capability (any non-empty role). The resolved crew is re-validated against the workspace before its files are read (tenant guard). Response: 200 OK

{
  "crew_id": "crew_x",
  "files": [
    { "path": "crew_x/writer/report.pdf", "name": "report.pdf", "size": 1234, "mod_time": "2026-07-01T10:30:00Z" }
  ]
}

A run with no resolvable/in-workspace crew returns { "crew_id": "", "files": [] }. Download a listed file via crew files download / crewship crew files get <crew_id> <path>.

Status	Condition
`404`	Run not found in this workspace

This is a correlation, not proof of authorship, and deliberately does not modify the pipeline executor. Because it keys on modification time within the window, the list can also include files written by a concurrent chat session on the same crew, files from another run whose window overlapped, or files authored earlier and merely re-saved (an mtime bump with no content change). Read it as “what changed on the crew while this ran”. See the routine result CLI docs.

Cancel pipeline run

POST /api/v1/workspaces/{workspaceId}/pipelines/runs/{runId}/cancel

Pre-empts an in-flight run by triggering its context. The run loop checks ctx.Err() between steps and propagates cancellation into the agent runner, which kills the underlying CLI process. Idempotent: cancelling an already-cancelled run is a no-op (200 with the same response). Cancelling a finished run returns 404 because the in-memory registry only tracks live runs. A run parked on an approval or event (WAITING) is cancelled in the run store too: the row becomes CANCELLED, its pending waitpoints are cancelled, and the response carries "parked": true. The cancel and any resume of that run (approve, signal, event, restart) exclude each other, so exactly one of them wins. If resumes keep taking the run, the endpoint answers 409 without changing anything; retrying the cancel is safe. Auth: OWNER or ADMIN (canRole "manage") — cancelling another user’s run is a manage-tier action. Response: 200 OK

{
  "run_id": "run_cm9abc",
  "cancel_requested": true,
  "cancel_requested_at": "2026-05-19T08:01:33.123Z"
}

Status	Condition
`403`	Caller below `ADMIN`
`404`	Run not found in this workspace (already finished, or never started here)
`409`	A resume kept taking the parked run; nothing changed, retry the cancel
`500`	The run store could not be read or written
`503`	Run registry not wired

Versions

Every save snapshots the pipeline, so you can inspect its history, fetch a specific revision, or roll the head pointer back.

List versions

GET /api/v1/workspaces/{workspaceId}/pipelines/{slug}/versions

Returns the version history (newest first) for a pipeline. Query parameters: limit (default 100). Response: 200 OK

[
  {
    "version": 4,
    "definition_hash": "f3c1...",
    "author_type": "user",
    "author_id": "user_jdoe42",
    "parent_version": 3,
    "change_summary": "Add review step before publish",
    "created_at": "2026-05-18T08:00:01.123Z"
  }
]

Get one version

GET /api/v1/workspaces/{workspaceId}/pipelines/{slug}/versions/{n}

Returns a specific version including the full DSL definition.

Status	Condition
`400`	`n` is not a positive integer
`404`	Pipeline or version not found

Rollback to a version

POST /api/v1/workspaces/{workspaceId}/pipelines/{slug}/rollback

Rolls the pipeline’s head pointer + definition_json back to the named version. History is preserved — rollback does not delete newer versions. Auth: OWNER or ADMIN (canRole "manage"). Request body:

{ "version": 3 }

Response: 200 OK — full pipeline object with the restored definition.

Status	Condition
`400`	`version` missing or < 1
`403`	Caller below `ADMIN`
`404`	Pipeline or version not found
`409`	An enabled plan following head carries inputs the restored version rejects — `schedule_conflict` + `hint` as on Save; head is left where it was

Import / export

Move a pipeline between workspaces as a portable bundle — export from one, import into another.

Export pipeline bundle

GET /api/v1/workspaces/{workspaceId}/pipelines/{slug}/export

Returns a portable crewship-pipeline-bundle/v1 document. Author identity, runtime stats, and any installation-specific data are deliberately stripped — the receiving workspace fills them in at import time. Query parameters:

Parameter	Type	Description
`include_history`	`1`	Include up to 500 prior versions in the bundle

Response: 200 OK

{
  "format": "crewship-pipeline-bundle/v1",
  "pipeline": {
    "name": "Weekly changelog",
    "description": "Summarise merged PRs into the public changelog",
    "slug": "weekly-changelog",
    "dsl_version": "v1",
    "definition": { /* DSL */ }
  },
  "metadata": {
    "exported_at": "2026-05-19T09:00:00Z",
    "source_workspace_id": "ws_cm1abc123",
    "definition_hash": "f3c1...",
    "head_version": 17
  },
  "history": [ /* present only when include_history=1 */ ]
}

The bundle’s metadata.head_version field is misnamed in the current build — it actually carries invocation_count. Treat it as opaque metadata.

Import pipeline bundle

POST /api/v1/workspaces/{workspaceId}/pipelines/import

Creates a pipeline from a previously exported bundle. The receiving workspace becomes the author context; the original bundle’s source workspace id is preserved on the pipeline row as imported_from_url for audit. Imports skip the save validation gate by design — a marketplace bundle is presumed to have been validated in its source workspace. Auth: MANAGER+ (canRole "create") — importing creates a new pipeline row, same privilege as Save. Request body: the bundle JSON plus an explicit author_crew_id:

{
  "format": "crewship-pipeline-bundle/v1",
  "pipeline": { /* as exported */ },
  "metadata":  { /* as exported */ },
  "author_crew_id": "crew_eng"
}

Response: 201 Created — full pipeline object.

Status	Condition
`400`	Invalid bundle JSON, unsupported `format`, missing `pipeline.name`/`pipeline.definition`, missing `author_crew_id`
`403`	Caller below `MANAGER`
`409`	Slug already exists in this workspace, or an enabled plan following head carries inputs the imported definition rejects (`schedule_conflict` + `hint` as on Save)
`422`	DSL parse / validate failure (receiving workspace doesn’t have every referenced agent slug)

Approval waitpoints

When a pipeline hits a step_wait of kind approval, the run parks and a waitpoint row is created. The UI’s /inbox lists pending waitpoints; approving or rejecting wakes the parked run.

Typed human decisions

An approval wait can declare decision_form with fields (routine input specifications) and actions (id, label, approved). The server freezes this form when it creates the waitpoint. Later recipe edits cannot change the question or validation for a pending decision. Standing trust does not auto-answer a form. The authenticated approve endpoint accepts the flat request {"approved":true,"action_id":"go","data":{"count":0,"enabled":false}}. The action must exist and its approved value must match. The server validates required fields and types without converting strings into numbers or booleans. Rejection relaxes required fields. 400 means an invalid answer, 403 means an unauthorized actor, and 409 means the decision was already answered or expired. The accepted JSON answer is the wait step output for downstream steps. Typed decisions require an authenticated workspace member with MANAGER+; the public token callback returns 403 even for a well-formed form answer. Their pending-list rows carry decision_form and omit callback_url. Legacy binary approvals retain the public callback and their historical output. Identity comes from authentication, never from an answer’s data fields.

List pending waitpoints

GET /api/v1/workspaces/{workspaceId}/pipelines/waitpoints

Returns up to 200 pending waitpoints across the workspace, newest first. Response: 200 OK

[
  {
    "token": "wp_8f3c1...",
    "pipeline_run_id": "run_cm9abc",
    "step_id": "review-approval",
    "kind": "approval",
    "prompt": "Approve the drafted changelog before publishing.",
    "invoking_crew_id": "crew_eng",
    "timeout_at": "2026-05-19T10:00:00Z",
    "created_at": "2026-05-19T08:00:18Z"
  }
]

Approve / reject waitpoint

POST /api/v1/workspaces/{workspaceId}/pipelines/waitpoints/{token}/approve

Completes a pending approval. Decider identity is taken from the request’s auth context, never from the body. Who can decide. A waitpoint is a question for a person. The resolve door accepts a decision from a workspace member with MANAGER+ (session or CLI token — the inbox, the routine page, crewship routine waitpoints approve) and from the holder of the token itself on the public callback. It refuses an agent — a crew-bound X-Internal-Token, a sidecar tool, a peer agent posting “GO” — and a request with no principal at all, with 403 and "reason": "waitpoint_decider_not_allowed". The waitpoint is left pending and the attempt is recorded in the audit log under the action waitpoint.decision_refused (crewship audit --action waitpoint.decision_refused), naming the actor and the run. No agent-facing route reaches this door today (internal tokens get 401 from the authed route before it), but the door checks the actor’s kind regardless, so wiring one later cannot become a way for an agent to satisfy a waitpoint. The inbox card carries the same audience as who_can_act: ["role:MANAGER"]. Request body:

{
  "approved": true,
  "comment": "LGTM, ship it"
}

Field	Type	Required	Description
`approved`	boolean	effectively yes	Always send it explicitly (the CLI and UI always do). If the field is omitted entirely, it defaults to `false` — a body-less `POST` to this URL denies the waitpoint rather than approving it, despite the endpoint being named `.../approve` (`internal/api/pipelines_exec.go`, `Approved bool` — the Go zero value). See Defaults differ from the public callback, below, before relying on omission either way.
`comment`	string	no	Stored with the decision. Included in typed decision output; it does not replace legacy wait output.

An approved legacy wait returns the literal waited:approval:approved as its step output. An approved typed wait returns serialized DecisionAnswer JSON with action_id, data, and optional comment; downstream steps can parse that JSON. Rejected decisions follow the wait step’s failure behavior. Response: 200 OK

{ "ok": true, "approved": true }

Status	Condition
`400`	Missing `token` or invalid body
`403`	The decider is not a person: an agent’s internal token, or no principal at all. The waitpoint is untouched and the attempt is on the audit log as `waitpoint.decision_refused`.
`409`	Waitpoint already decided or expired
`503`	Waitpoint store not wired, or the wired implementation does not support completion

Defaults differ from the public callback — intentionally

This authed endpoint and the public token callback below both accept an optional approved field, but they resolve a missing field in opposite directions:

Here (authed, .../approve): omitted → false (deny). This is the JWT-authenticated, human/MANAGER+-driven path (requireRole(... "update")). A caller with a valid session making a considered decision is expected to state it; if a request is malformed enough to drop the field, failing closed means the gated run stays parked rather than being silently released.
Public token callback (POST /api/v1/waitpoint-tokens/{token}): omitted → true (approve). This endpoint has no JWT — the token in the path is the only credential — and exists for external systems (CI jobs, vendor webhooks) whose completion signal is often just “the task finished, hit this URL” with no body at all (trigger.dev wait.forToken parity). Requiring a JSON body here would break that integration pattern.

Both defaults are deliberate for their own caller population, not a shared contract — do not assume the two endpoints behave the same way when a request omits approved, and do not rely on either default when authoring a new integration: send the field explicitly.

Complete a waitpoint by token (public callback)

POST /api/v1/waitpoint-tokens/{token}

The public sibling of the approve endpoint (trigger.dev wait.forToken parity). An external system holding a waitpoint token completes the wait via an HTTP callback — no workspace JWT required: the high-entropy token in the path is the auth surface, the same model as the public webhook dispatch endpoint. This lets a human-in-the-loop or external-task wait be resolved by a third party (approval service, CI job, vendor webhook) rather than only through the inbox. The token and its callback_url are surfaced on the pending-waitpoints listing (internal/api/router_pipelines.go:127-131). Auth: none — the path token is the credential. The completion is attributed to the sentinel decider external-callback (not a user id) so audit queries can distinguish callback completions from inbox approvals (internal/api/pipeline_waitpoint_callback.go). This is not an agent door. The token travels only to person-facing surfaces — the inbox card, the pending-waitpoints listing, the CLI — and is never handed to an agent, so the only way an agent could reach this route is a person choosing to give the token away. The resolve door behind it is the same one the authed endpoint uses and refuses an agent actor by kind. Request body: optional. A bare POST with no body means “the external task finished, continue the run”.

Field	Type	Required	Description
`approved`	boolean	no	Defaults to `true`. Set `false` to deny the waitpoint (`internal/api/pipeline_waitpoint_callback.go:44-47`). Note: this default is the opposite of the authed approve/reject endpoint above, which defaults an omitted field to `false`. See Defaults differ from the public callback for the reasoning — send `approved` explicitly rather than relying on either default.
`payload`	any (JSON)	no	Stored on the waitpoint for the resumed step to read (`internal/api/pipeline_waitpoint_callback.go:48-51`).

{
  "approved": true,
  "payload": { "ticket": "OPS-4821", "result": "passed" }
}

Response: 200 OK

{ "ok": true, "approved": true }

On success the parked run is resumed via the same path as the authed approve handler (internal/api/pipeline_waitpoint_callback.go:74-84).

Status	Condition
`400`	Missing `token`, or an unparseable request body (`internal/api/pipeline_waitpoint_callback.go:26-42`)
`409`	Waitpoint already decided or expired (`internal/api/pipeline_waitpoint_callback.go:65-67`)
`500`	Completion failed for any other reason (`internal/api/pipeline_waitpoint_callback.go:69-71`)
`503`	Waitpoint store not wired, or the wired implementation does not support completion (`internal/api/pipeline_waitpoint_callback.go:22-24,56-59`)

Schedules

Schedules fire pipelines on a cron expression. The in-process scheduler ticks every minute and skips soft-deleted rows.

List schedules

GET /api/v1/workspaces/{workspaceId}/pipeline-schedules

Response: 200 OK

[
  {
    "id": "sched_cmWeekly",
    "workspace_id": "ws_cm1abc123",
    "name": "Weekly changelog",
    "target_pipeline_id": "pipe_cmRoutine42",
    "target_pipeline_slug": "weekly-changelog",
    "target_pipeline_version": null,
    "cron_expr": "0 9 * * MON",
    "timezone": "Europe/Prague",
    "inputs": { "since": "last_monday" },
    "enabled": true,
    "last_run_at": "2026-05-12T07:00:00Z",
    "last_status": "completed",
    "last_run_id": "run_cm9abc",
    "next_run_at": "2026-05-19T07:00:00Z",
    "created_at": "2026-04-12T09:00:00Z",
    "updated_at": "2026-05-12T07:00:00Z"
  }
]

Create schedule

POST /api/v1/workspaces/{workspaceId}/pipeline-schedules

Accepts either target_pipeline_slug (UI-friendly) or target_pipeline_id (CLI-friendly). Auth: MANAGER+ (canRole "create"), or a MEMBER holding the routine.create capability. Request body:

Field	Type	Required	Description
`name`	string	no	Falls back to the pipeline slug
`target_pipeline_slug`	string	one-of	—
`target_pipeline_id`	string	one-of	—
`target_pipeline_version`	integer	no	Pin every fire to this immutable routine version; default (`null`) = always head. A fire whose pinned version no longer exists fails (recorded `FAILED` + a `failed_run` inbox alert) — it never silently falls back to head.
`cron_expr`	string	yes	5-field cron
`timezone`	string	no	IANA name (e.g. `"Europe/Prague"`); default UTC
`inputs`	object	no	Static inputs passed on every fire
`enabled`	boolean	no	Default `true`
`wake_pipeline_slug`	string	no	Wake gate: an agentless probe run before each fire; the main routine fires only when the probe’s final output is truthy.
`wake_pipeline_id`	string	no	Wake gate probe by id (alternative to the slug).
`wake_inputs`	object	no	Static inputs passed to the wake probe on each tick.
`wake_fail_closed`	boolean	no	Default `false` (fail open): a probe error / timeout / non-`COMPLETED` run still fires the main routine and records `last_wake_status: ERROR`. Set `true` (fail closed) to hold the run on any such non-affirmative probe outcome (recorded `HELD`, no main run) — for gates that must suppress an unattended run, not just save tokens. Ignored without a wake gate.

Response: 201 Created — schedule object.

Status	Condition
`400`	Missing `cron_expr`, invalid cron / timezone, pipeline not found in this workspace
`403`	Caller below `MANAGER` without `routine.create`
`503`	Schedule store not wired

Update schedule

PATCH /api/v1/workspaces/{workspaceId}/pipeline-schedules/{scheduleId}

Whole-row replace semantics — the caller sends the post-edit state, missing fields fall back to the existing row. This includes target_pipeline_version: an absent field keeps the existing version pin, an explicit "target_pipeline_version": null clears it (fires track head again). Likewise wake_fail_closed: absent keeps the existing policy, an explicit boolean sets it; clearing the wake gate resets the policy to fail-open. Auth: OWNER or ADMIN (canRole "manage"). Response: 200 OK — updated schedule.

Status	Condition
`400`	Invalid body / cron / timezone
`403`	Caller below `ADMIN`
`404`	Schedule not found in this workspace
`503`	Schedule store not wired

Delete schedule

DELETE /api/v1/workspaces/{workspaceId}/pipeline-schedules/{scheduleId}

Soft delete. In-flight scheduled runs finish; no new runs fire.

Auth: OWNER or ADMIN (canRole "delete"). Response: 204 No Content

Status	Condition
`403`	Caller below `ADMIN`
`404`	Schedule not found
`503`	Schedule store not wired

Webhooks

Webhooks let external systems trigger a pipeline by POSTing to a public URL. Each webhook has its own opaque token and optional HMAC signing secret. The public dispatch entrypoint (POST /api/v1/webhooks/{token}) is not under /workspaces/... — see the Webhooks API doc.

List webhooks

GET /api/v1/workspaces/{workspaceId}/pipeline-webhooks

Returns all non-deleted webhooks. The signing_secret value is never returned outside the create response. Response: 200 OK

[
  {
    "id": "wh_cmGithub",
    "workspace_id": "ws_cm1abc123",
    "name": "github-push",
    "target_pipeline_id": "pipe_cmRoutine42",
    "target_pipeline_slug": "weekly-changelog",
    "target_pipeline_version": null,
    "token": "whk_EXAMPLE_PLACEHOLDER",
    "signing_secret_set": true,
    "inputs_template": { "branch": "{{ inputs.event.ref }}" },
    "enabled": true,
    "rate_limit_per_min": 60,
    "last_fired_at": "2026-05-19T07:55:00Z",
    "last_status": "COMPLETED",
    "last_run_id": "run_cm9abc",
    "fire_count": 42,
    "created_at": "2026-04-12T09:00:00Z",
    "updated_at": "2026-05-19T07:55:00Z"
  }
]

Create webhook

POST /api/v1/workspaces/{workspaceId}/pipeline-webhooks

Auth: MANAGER+ (canRole "create") — a webhook mints a public dispatch URL, so creation is gated at MANAGER+. Request body:

Field	Type	Required	Description
`name`	string	no	Falls back to the pipeline slug
`target_pipeline_slug`	string	one-of	—
`target_pipeline_id`	string	one-of	—
`target_pipeline_version`	integer	no	Pin every dispatch to this immutable routine version; default (`null`) = always head. A dispatch whose pinned version no longer exists answers `409` — never a silent head run.
`signing_secret`	string	no	Used for HMAC-SHA256 verification of the `X-Crewship-Signature` header. If omitted, the server auto-generates a 32-byte hex secret — HMAC verification is mandatory on every webhook, so `signing_secret_set` is always `true`.
`inputs_template`	object	no	Merged on top of the default `{event, raw, headers}` envelope when the webhook fires (the three reserved keys cannot be overridden)
`enabled`	boolean	no	Default `true`
`rate_limit_per_min`	integer	no	Per-token rate limit; `0` (or unset) floors to 600/min server-side, not unlimited

Response: 201 Created — webhook object including signing_secret (this is the only time it is returned, whether supplied or auto-generated; subsequent reads return only signing_secret_set: true).

Status	Condition
`400`	Missing/invalid pipeline reference
`403`	Caller below `MANAGER`
`503`	Webhook store not wired

Delete webhook

DELETE /api/v1/workspaces/{workspaceId}/pipeline-webhooks/{webhookId}

Soft delete.

Auth: OWNER or ADMIN (canRole "delete"). Response: 204 No Content

Status	Condition
`403`	Caller below `ADMIN`
`404`	Webhook not found in this workspace
`503`	Webhook store not wired

Skills

These endpoints manage the workspace-scoped write surface for the skills registry. Browsing skills (GET /api/v1/skills) is not workspace-scoped and lives in the Skills API doc.

Import skill (URL or paste)

POST /api/v1/workspaces/{workspaceId}/skills/import

Imports a single SKILL.md either by URL (SSRF-validated, HTTPS-only, no loopback / private addresses) or by pasted content. Re-imports of the same slug update in place. Auth: MANAGER+ (canRole "create"). Request body:

Field	Type	Required	Description
`url`	string	one-of	HTTPS URL to a raw `SKILL.md`
`content`	string	one-of	Inline `SKILL.md` (YAML frontmatter + markdown body)
`allow_unsafe_license`	boolean	no	Bypass the SPDX allowlist; the journal entry is upgraded to `WARN` severity

Response: 201 Created

{
  "skill_id": "sk_a1b2c3d4e5f6",
  "name": "github-pr-review",
  "slug": "github-pr-review",
  "created": true
}

The import response carries only these four fields (created is true for a fresh row, false for an in-place update of an existing slug). Scan status and display name are persisted on the skill row but not echoed here — fetch the skill via GET /api/v1/skills/{skillId} to read them.

Status	Condition
`400`	Missing/both of `url` + `content`, SSRF block (private/loopback/non-HTTPS), parse failure, license rejection
`403`	Caller below `MANAGER`

Bulk import from git repo

POST /api/v1/workspaces/{workspaceId}/skills/bulk-import

Walks a public git repository for SKILL.md files and upserts each through the same license-gated path as single-import. Per-skill rejections are reported in the response’s skipped list rather than failing the whole batch.

Local-path bulk import (the importer’s Paths field beyond the optional in-repo subdirectory filter) is intentionally not exposed — it would turn the endpoint into an arbitrary host-FS read primitive.

Auth: MANAGER+ (canRole "create"). Request body:

Field	Type	Required	Description
`git_url`	string	yes	HTTPS git URL (no embedded credentials, no loopback)
`git_ref`	string	no	Branch / tag / commit; default = repo HEAD
`paths`	string[]	no	Subdirectory filter inside the repo
`vendor`	string	no	Override the `vendor` field on every imported skill
`allow_unsafe_license`	boolean	no	Bypass SPDX allowlist
`dry_run`	boolean	no	Walk + validate but don’t write to the DB

Response: 200 OK

{
  "source": "git:https://github.com/acme/skills.git@main",
  "total_found": 12,
  "total_imported": 9,
  "imported": [
    { "skill_id": "sk_...", "slug": "lint-typescript", "created": true }
  ],
  "skipped": [
    { "path": "skills/old/SKILL.md", "slug": "old-thing", "reason": "license MIT-no-attribution not allowed" }
  ],
  "truncated": false
}

Status	Condition
`400`	Missing `git_url`, invalid workspace
`403`	Caller below `MANAGER`
`502`	Walker failure (git clone failed, missing `git` binary, etc.); validation errors are echoed verbatim while raw clone-process stderr is replaced with a generic message

Generate skill (LLM)

POST /api/v1/workspaces/{workspaceId}/skills/generate

Calls Anthropic with a condensed skill-creator system prompt, validates the output against the parser, and writes it back as a fresh row with source='GENERATED'. The generated content can then be edited via the regular import flow. Requires an ACTIVE Anthropic credential of type API_KEY (a real sk-ant-... — OAuth bearers from the Claude Code login flow are rejected because they only work against claude.ai, not the Messages API). Auth: MANAGER+ (canRole "create"). Request body:

Field	Type	Required	Description
`slug`	string	yes	Desired skill slug (slugified server-side)
`prompt`	string	yes	User’s intent / brief
`model`	string	no	Default `claude-sonnet-4-6`

Response: 201 Created

{
  "skill_id": "sk_a1b2c3d4e5f6",
  "slug": "extract-pdf-tables",
  "content": "---\nname: extract-pdf-tables\n...---\n## When to use\n...",
  "scan_status": "CLEAN",
  "scan_reason": "",
  "description_quality": ""
}

Status	Condition
`400`	Missing `slug` or `prompt`, invalid JSON
`403`	Caller below `MANAGER`
`409`	Generated slug collides with an existing row
`412`	No active `ANTHROPIC` / `API_KEY` credential for this workspace
`502`	Upstream LLM call failed, or generated content didn’t parse as a valid `SKILL.md`

Delete skill

DELETE /api/v1/workspaces/{workspaceId}/skills/{skillId}

Removes a skill from the registry. Cascades to agent_skills via FK. BUNDLED skills are refused — the binary re-seeds them on every startup, so a delete is a no-op churn and creates a malicious-operator window.

Auth: OWNER or ADMIN (canRole "manage"). The skills registry is shared global state; destructive operations get the higher tier. Response: 200 OK

{ "deleted": true, "skill_id": "sk_a1b2c3d4e5f6" }

Status	Condition
`400`	Missing `skill_id` path value
`403`	Caller below `ADMIN`, or skill is `BUNDLED`
`404`	Skill not found

`preferred_language` values

preferred_language accepts either the canonical English name or an ISO code. The resolver normalises both to the canonical name before storage. Supported values: Afrikaans (af), Arabic (ar), Bulgarian (bg), Bengali (bn), Catalan (ca), Czech (cs), Danish (da), German (de), Greek (el), English (en), Spanish (es), Estonian (et), Persian (fa), Finnish (fi), French (fr), Hebrew (he), Hindi (hi), Croatian (hr), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Lithuanian (lt), Latvian (lv), Malay (ms), Norwegian (nb), Dutch (nl), Polish (pl), Portuguese (pt), Portuguese (Brazil) (pt-BR), Romanian (ro), Russian (ru), Slovak (sk), Slovenian (sl), Serbian (sr), Swedish (sv), Swahili (sw), Tamil (ta), Thai (th), Turkish (tr), Ukrainian (uk), Urdu (ur), Vietnamese (vi), Chinese (zh), Chinese (Traditional) (zh-TW). The list lives in internal/api/workspaces.go and must stay in sync with lib/languages.ts on the frontend.

Get member resource access

GET /api/v1/workspaces/{workspaceId}/members/{memberId}/access

Read a complete resource access policy in a consistent membership/grants snapshot. workspaceId is the canonical workspace ID; memberId is the membership row ID, not the user ID. Auth: Authenticated current trusted OWNER/ADMIN of this workspace. Scoped CLI tokens additionally require workspace:admin or its wildcard. Existing restricted-session restrictions also apply to mixed memberships. Request: No body. Path parameters: workspaceId, memberId. No additional query parameters are required. Response: 200 OK, Cache-Control: no-store:

{
  "membership_id": "member_123",
  "mode": "restricted",
  "revision": 3,
  "rights": [{"kind": "agent", "id": "agent_123", "operation": "chat"}]
}

rights is an explicit array, including when empty. Agent operations are discover, chat, run, delegate; project operations are list, read, write, delete. Grants do not open application routes whose restricted runtime integration is incomplete.

Status	Condition
`200`	Policy returned
`401`	Authentication required
`403`	Workspace membership or token scope denied
`404`	Member/policy unavailable, operator denied, or workspace path mismatch
`500`	Database error

Replace member resource access

PUT /api/v1/workspaces/{workspaceId}/members/{memberId}/access

Atomically replace a member’s resource ceiling. Roles, capabilities and conversation audience remain additional checks. Auth: Authenticated current trusted OWNER/ADMIN of the target workspace; scoped CLI tokens require workspace:admin or its wildcard. The server derives the operator from authentication, never the request body. Request: JSON body, maximum 64 KiB. All four fields are required:

{
  "membership_id": "member_123",
  "mode": "restricted",
  "revision": 3,
  "rights": []
}

membership_id must match the path’s membership row. revision must match the current version read from GET. mode is trusted or restricted; rights contains at most 256 distinct {kind,id,operation} objects belonging to this workspace. Null/omitted rights and unknown fields are rejected. Empty restricted rights revoke all resource grants. Trusted mode requires empty rights and restores ordinary workspace access. OWNER/ADMIN targets cannot be restricted. Response: 200 OK, Cache-Control: no-store, the same complete policy shape as GET with the new revision. Revisions are opaque versions and may advance by more than one. No live shared process is forcibly terminated by this endpoint; new authorization checks enforce the updated policy. Unintegrated restricted execution routes remain denied.

Status	Condition
`200`	Replacement committed
`400`	Malformed/oversized JSON, missing fields, invalid mode or mismatched membership ID
`401`	Authentication required
`403`	Route role, workspace membership or token scope denied
`404`	Unavailable member, operator denied, invalid/foreign/duplicate resource grant, or protected target
`409`	Membership ID/revision changed; read the current policy and review the edit again
`500`	Database error

​Endpoints

​Workspace metadata

​List workspaces

​Create workspace

​Get workspace

​Update workspace

​Workspace logo

​Delete workspace

​Members

​List members

​Add member

​Provision member

​Remove member

​Change member role

​Member capabilities

​Get member capabilities

​Update member capabilities

​List all member capabilities (bulk)

​Invitations

​List invitations

​Create invitation

​Pipelines

​List pipelines

​Get pipeline

​Delete pipeline

​List routine drafts

​Read a routine draft

​Save a routine draft

​Discard a routine draft

​Publish a routine draft

​Save pipeline

​Test an unpublished definition

​Dry-run a saved pipeline

​Run pipeline

​RunResult shape

​List pipeline runs (journal-backed)

​List pipeline run records (projection table)

​List active runs (in-memory registry)

​List workspace runs (cross-pipeline feed)

​Get pipeline run

​Run-window file changes

​Cancel pipeline run

​Versions

​List versions

​Get one version

​Rollback to a version

​Import / export

​Export pipeline bundle

​Import pipeline bundle

​Approval waitpoints

​Typed human decisions

​List pending waitpoints

​Approve / reject waitpoint

​Defaults differ from the public callback — intentionally

​Complete a waitpoint by token (public callback)

​Schedules

​List schedules

​Create schedule

​Update schedule

​Delete schedule

​Webhooks

​List webhooks

​Create webhook

​Delete webhook

​Skills

​Import skill (URL or paste)

​Bulk import from git repo

​Generate skill (LLM)

​Delete skill

​preferred_language values

​See also

​Test a routine step with sample data

​Get member resource access

​Replace member resource access

Endpoints

Workspace metadata

List workspaces

Create workspace

Get workspace

Update workspace

Workspace logo

Delete workspace

Members

List members

Add member

Provision member

Remove member

Change member role

Member capabilities

Get member capabilities

Update member capabilities

List all member capabilities (bulk)

Invitations

List invitations

Create invitation

Pipelines

List pipelines

Get pipeline

Delete pipeline

List routine drafts

Read a routine draft

Save a routine draft

Discard a routine draft

Publish a routine draft

Save pipeline

Test an unpublished definition

Dry-run a saved pipeline

Run pipeline

`RunResult` shape

List pipeline runs (journal-backed)

List pipeline run records (projection table)

List active runs (in-memory registry)

List workspace runs (cross-pipeline feed)

Get pipeline run

Run-window file changes

Cancel pipeline run

Versions

List versions

Get one version

Rollback to a version

Import / export

Export pipeline bundle

Import pipeline bundle

Approval waitpoints

Typed human decisions

List pending waitpoints

Approve / reject waitpoint

Defaults differ from the public callback — intentionally

Complete a waitpoint by token (public callback)

Schedules

List schedules

Create schedule

Update schedule

Delete schedule

Webhooks

List webhooks

Create webhook

Delete webhook

Skills

Import skill (URL or paste)

Bulk import from git repo

Generate skill (LLM)

Delete skill

`preferred_language` values

See also

Test a routine step with sample data

Get member resource access

Replace member resource access