# Admin Source: https://docs.crewship.ai/api-reference/admin Workspace administration endpoints for stats, user management, Keeper audit logs, and the license system. # Admin API The operational surface for OWNER and ADMIN roles: workspace stats, user management, GDPR subject-access and erasure, memory administration, the Keeper security audit log, and a set of cross-cutting system and metrics endpoints. Most endpoints require the OWNER role; the GDPR and memory-admin endpoints require ADMIN or OWNER (manage permission). The Keeper Phase 2 evaluators and three system endpoints have their own auth model, noted inline. > [!NOTE] > > Unless a section says otherwise, every endpoint on this page requires the **OWNER** role. The GDPR, memory-admin, and Keeper-requests endpoints accept **ADMIN or OWNER** (manage permission). ## Endpoints | Method | Endpoint | Purpose | | - | - | - | | `GET` | [/api/v1/admin/stats](#get-api-v1-admin-stats) | Aggregate stats for the current workspace | | `GET` | [/api/v1/admin/users](#get-api-v1-admin-users) | List people with roles, activity and lockout state | | `GET` | [/api/v1/admin/users/\{userId}/sessions](#get-api-v1-admin-users-userid-sessions) | A person's signed-in devices and live CLI tokens | | `POST` | [/api/v1/admin/users/\{userId}/sessions/\{sessionId}/revoke](#post-api-v1-admin-users-userid-sessions-sessionid-revoke) | Sign a person out of one device | | `POST` | [/api/v1/admin/users/\{userId}/sessions/revoke-all](#post-api-v1-admin-users-userid-sessions-revoke-all) | Sign a person out of every device | | `POST` | [/api/v1/admin/users/\{userId}/unlock](#post-api-v1-admin-users-userid-unlock) | Lift a sign-in lockout | | `GET` | [/api/v1/admin/users/\{userId}/data](#get-api-v1-admin-users-userid-data) | GDPR Art. 15 — export every row referencing a user | | `DELETE` | [/api/v1/admin/users/\{userId}/data](#delete-api-v1-admin-users-userid-data) | GDPR Art. 17 — cascade purge a user's data | | `GET` | [/api/v1/admin/workspaces](#get-api-v1-admin-workspaces) | Workspaces with counts, runs, spend and settings | | `POST` | [/api/v1/admin/instance/people](#post-api-v1-admin-instance-people) | Create an account with access and a setup link | | `PUT` | [/api/v1/admin/instance/workspaces/\{workspaceId}/members/\{userId}](#put-api-v1-admin-instance-workspaces-workspaceid-members-userid) | Give access to any workspace, or change the role | | `DELETE` | [/api/v1/admin/instance/workspaces/\{workspaceId}/members/\{userId}](#delete-api-v1-admin-instance-workspaces-workspaceid-members-userid) | Take a person out of a workspace | | `POST` | [/api/v1/admin/instance/workspaces](#post-api-v1-admin-instance-workspaces) | Create a workspace owned by someone else | | `PATCH` | [/api/v1/admin/instance/workspaces/\{workspaceId}](#patch-api-v1-admin-instance-workspaces-workspaceid) | Rename any workspace, or mark it team or personal | | `POST` | [/api/v1/admin/instance/workspaces/\{workspaceId}/transfer-ownership](#post-api-v1-admin-instance-workspaces-workspaceid-transfer-ownership) | Hand a workspace to another member | | `DELETE` | [/api/v1/admin/instance/workspaces/\{workspaceId}](#delete-api-v1-admin-instance-workspaces-workspaceid) | Delete any workspace | | `POST` | [/api/v1/admin/instance/people/\{userId}/suspend](#post-api-v1-admin-instance-people-userid-suspend) | Block an account and end its sessions | | `POST` | [/api/v1/admin/instance/people/\{userId}/reactivate](#post-api-v1-admin-instance-people-userid-reactivate) | Lift a suspension | | `POST` | [/api/v1/admin/instance/people/\{userId}/setup-link](#post-api-v1-admin-instance-people-userid-setup-link) | Issue a new setup link | | `DELETE` | [/api/v1/admin/instance/people/\{userId}/setup-link](#delete-api-v1-admin-instance-people-userid-setup-link) | Void a pending setup link | | `PUT` | [/api/v1/admin/instance/admins/\{userId}](#put-api-v1-admin-instance-admins-userid) | Name an instance administrator | | `DELETE` | [/api/v1/admin/instance/admins/\{userId}](#delete-api-v1-admin-instance-admins-userid) | Remove a named instance administrator | | `GET` | [/api/v1/admin/instance/audit](#get-api-v1-admin-instance-audit) | Instance-level actions, newest first | | `GET` | [/api/v1/admin/instance/audit/verify](#get-api-v1-admin-instance-audit-verify) | Verify the whole instance audit chain | | `GET` | [/api/v1/admin/instance/keeper/governance](#get-api-v1-admin-instance-keeper-governance) | Every workspace's Keeper watchdog settings and the instance defaults | | `PUT` | [/api/v1/admin/instance/keeper/governance](#put-api-v1-admin-instance-keeper-governance) | Set the watchdog for one, several or all existing workspaces | | `GET` | [/api/v1/admin/instance/keeper/governance/defaults](#get-api-v1-admin-instance-keeper-governance-defaults) | The template a new workspace's Keeper starts with | | `PUT` | [/api/v1/admin/instance/keeper/governance/defaults](#put-api-v1-admin-instance-keeper-governance-defaults) | Change that template; no existing workspace changes | | `GET` | [/api/v1/admin/instance/keeper/requests](#get-api-v1-admin-instance-keeper-requests) | Keeper decisions across workspaces | | `GET` | [/api/v1/admin/instance/keeper/health](#get-api-v1-admin-instance-keeper-health) | Every workspace's Keeper decision window | | `GET` | [/api/v1/admin/instance/workbook-editor](#get-api-v1-admin-instance-workbook-editor) | The embedded workbook editor's mode and proxy self-check | | `GET` | [/api/v1/admin/instance/artifact-storage](#get-api-v1-admin-instance-artifact-storage) | The aggregate artifact storage limits and instance counters | | `PUT` | [/api/v1/admin/instance/artifact-storage](#put-api-v1-admin-instance-artifact-storage) | Set the workspace and instance artifact storage limits | | `POST` | [/api/v1/admin/instance/artifact-storage/recompute](#post-api-v1-admin-instance-artifact-storage-recompute) | Rebuild the usage counters from the stored artifacts and report the drift | | `GET` | [/api/v1/admin/instance/retention](#get-api-v1-admin-instance-retention) | How long every workspace keeps each kind of data | | `PUT` | [/api/v1/admin/instance/retention](#put-api-v1-admin-instance-retention) | Set retention windows for one, several or every existing workspace | | `GET` | [/api/v1/admin/instance/retention/defaults](#get-api-v1-admin-instance-retention-defaults) | The retention windows a new workspace starts with | | `PUT` | [/api/v1/admin/instance/retention/defaults](#put-api-v1-admin-instance-retention-defaults) | Change the retention windows a new workspace starts with | | `GET` | [/api/v1/admin/instance/backups/bundles](#get-api-v1-admin-instance-backups-bundles) | Every catalogued bundle with its proof level, pin and gaps | | `POST` | [/api/v1/admin/instance/backups/bundles/pin](#post-api-v1-admin-instance-backups-bundles-pin) | Pin a bundle so no retention rule deletes it | | `POST` | [/api/v1/admin/instance/backups/bundles/unpin](#post-api-v1-admin-instance-backups-bundles-unpin) | Remove a bundle's pin | | `GET` | [/api/v1/admin/instance/backups/bundles/inspect](#get-api-v1-admin-instance-backups-bundles-inspect) | A catalogued bundle's manifest, instance bundles included | | `GET` | [/api/v1/admin/instance/backups/bundles/verify](#get-api-v1-admin-instance-backups-bundles-verify) | Check a catalogued bundle's payload checksum (proof level 1) | | `GET` | [/api/v1/admin/instance/backups/bundles/download](#get-api-v1-admin-instance-backups-bundles-download) | Download a catalogued bundle, instance bundles included | | `GET` | [/api/v1/admin/instance/backups/restores](#get-api-v1-admin-instance-backups-restores) | Every restore, dry run and drill with its report | | `GET` | [/api/v1/admin/instance/backups/plans](#get-api-v1-admin-instance-backups-plans) | Every backup plan | | `POST` | [/api/v1/admin/instance/backups/plans](#post-api-v1-admin-instance-backups-plans) | Create a backup plan | | `POST` | [/api/v1/admin/instance/backups/plans/preview-contents](#post-api-v1-admin-instance-backups-plans-preview-contents) | What a plan's bundles would carry | | `GET` | [/api/v1/admin/instance/backups/plans/\{id}](#get-api-v1-admin-instance-backups-plans-id) | One backup plan | | `PUT` | [/api/v1/admin/instance/backups/plans/\{id}](#put-api-v1-admin-instance-backups-plans-id) | Change a backup plan | | `DELETE` | [/api/v1/admin/instance/backups/plans/\{id}](#delete-api-v1-admin-instance-backups-plans-id) | Delete a backup plan | | `GET` | [/api/v1/admin/instance/backups/plans/\{id}/next](#get-api-v1-admin-instance-backups-plans-id-next) | A plan's next run times | | `GET` | [/api/v1/admin/instance/backups/plans/\{id}/calendar](#get-api-v1-admin-instance-backups-plans-id-calendar) | A plan's runs and planned times per day | | `GET` | [/api/v1/admin/instance/backups/runs](#get-api-v1-admin-instance-backups-runs) | Backup run history with phases | | `POST` | [/api/v1/admin/instance/backups/run](#post-api-v1-admin-instance-backups-run) | Start a backup now: a plan, the whole instance or selected workspaces (asynchronous) | | `GET` | [/api/v1/admin/instance/backups/overview](#get-api-v1-admin-instance-backups-overview) | Whether a restore would work, gaps, nights and space | | `GET` | [/api/v1/admin/instance/backups/run/\{runId}](#get-api-v1-admin-instance-backups-run-runid) | One run: status, phases and the bundle it wrote | | `GET` | [/api/v1/admin/instance/backups/vault-keys](#get-api-v1-admin-instance-backups-vault-keys) | Vault key versions and how many sealed values use each | | `PUT` | [/api/v1/admin/instance/backups/settings/recovery-kit](#put-api-v1-admin-instance-backups-settings-recovery-kit) | Put the vault keys in new instance bundles, or stop | | `POST` | [/api/v1/admin/instance/backups/bundles/check](#post-api-v1-admin-instance-backups-bundles-check) | Check a bundle's contents against its manifest (proof level 2) | | `POST` | [/api/v1/admin/instance/backups/restore/checks](#post-api-v1-admin-instance-backups-restore-checks) | Space, format, runtime, unsafe settings and conflicts before a restore | | `POST` | [/api/v1/admin/instance/backups/environments/land](#post-api-v1-admin-instance-backups-environments-land) | Load the crew environments an offline recover staged | | `POST` | [/api/v1/admin/instance/backups/bundles/upload](#post-api-v1-admin-instance-backups-bundles-upload) | Upload an encrypted recovery archive | | `POST` | [/api/v1/admin/instance/backups/services/land](#post-api-v1-admin-instance-backups-services-land) | Import the quota-service disks an offline recover staged | | `POST` | [/api/v1/admin/instance/backups/drills](#post-api-v1-admin-instance-backups-drills) | Record a test restore (proof level 3) | | `GET` | [/api/v1/admin/instance/backups/drills](#get-api-v1-admin-instance-backups-drills) | Every recorded test restore | | `GET` | [/api/v1/admin/instance/backups/settings](#get-api-v1-admin-instance-backups-settings) | Backup limits, heartbeat, alerts, destinations and instance admins | | `PUT` | [/api/v1/admin/instance/backups/settings](#put-api-v1-admin-instance-backups-settings) | Change backup settings (partial) | | `POST` | [/api/v1/admin/instance/backups/settings/test-alert](#post-api-v1-admin-instance-backups-settings-test-alert) | Send a test backup alert to a notification channel | | `GET` | [/api/v1/admin/instance/backups/recipients](#get-api-v1-admin-instance-backups-recipients) | Backup keys (age public keys) and the plans that use them | | `POST` | [/api/v1/admin/instance/backups/recipients](#post-api-v1-admin-instance-backups-recipients) | Add a backup key | | `DELETE` | [/api/v1/admin/instance/backups/recipients/\{id}](#delete-api-v1-admin-instance-backups-recipients-id) | Remove a backup key no plan uses | | `GET` | [/api/v1/admin/instance/backups/destinations](#get-api-v1-admin-instance-backups-destinations) | Off-site destinations and their verified copies | | `POST` | [/api/v1/admin/instance/backups/destinations](#post-api-v1-admin-instance-backups-destinations) | Add an S3-compatible destination (connection tested first) | | `POST` | [/api/v1/admin/instance/backups/destinations/\{id}/test](#post-api-v1-admin-instance-backups-destinations-id-test) | Test a destination's connection again | | `DELETE` | [/api/v1/admin/instance/backups/destinations/\{id}](#delete-api-v1-admin-instance-backups-destinations-id) | Remove a destination no plan copies to | | `GET` | [/api/v1/admin/instance/backups/incidents](#get-api-v1-admin-instance-backups-incidents) | Backup incidents, one per plan and kind | | `GET` | [/api/v1/admin/instance/backups/recovery-sheet](#get-api-v1-admin-instance-backups-recovery-sheet) | The recovery sheet (Markdown) | | `GET` | [/api/v1/admin/instance/backups/copies](#get-api-v1-admin-instance-backups-copies) | The bundles an off-site destination holds, and which are already here | | `POST` | [/api/v1/admin/instance/backups/copies/fetch](#post-api-v1-admin-instance-backups-copies-fetch) | Fetch a bundle back from off-site (a job) | | `GET` | [/api/v1/admin/instance/backups/copies/fetch/\{id}](#get-api-v1-admin-instance-backups-copies-fetch-id) | Follow an off-site fetch | | `GET` | [/api/v1/admin/instance/holds](#get-api-v1-admin-instance-holds) | Automations an instance restore left held | | `POST` | [/api/v1/admin/instance/holds/resume](#post-api-v1-admin-instance-holds-resume) | Resume a held automation | | `POST` | [/api/v1/admin/prune-legacy-resources](#post-api-v1-admin-prune-legacy-resources) | Remove orphaned pre-C1 Docker resources | | `GET` | [/api/v1/admin/legacy-resources](#get-api-v1-admin-legacy-resources) | Detect orphaned pre-C1 Docker resources | | `GET` | [/api/v1/admin/health](#get-api-v1-admin-health) | Read uptime, database, disk, and logging health | | `GET` | [/api/v1/admin/log-level](#get-api-v1-admin-log-level) | Read live and baseline log levels | | `PUT` | [/api/v1/admin/log-level](#put-api-v1-admin-log-level) | Change the live log level temporarily or persistently | | `GET` | [/api/v1/admin/rate-limits](#get-api-v1-admin-rate-limits) | List runtime rate-limit settings | | `PUT` | [/api/v1/admin/rate-limits/](#put-api-v1-admin-rate-limits-key) | Override one rate limit | | `DELETE` | [/api/v1/admin/rate-limits/](#delete-api-v1-admin-rate-limits-key) | Reset one rate limit to its default | | `POST` | [/api/v1/admin/reap-orphan-containers](#post-api-v1-admin-reap-orphan-containers) | Detect, and optionally remove, stale-token crew containers | | `POST` | [/api/v1/admin/reencrypt](#post-api-v1-admin-reencrypt) | Re-encrypt stored envelopes to the current key version | | `GET` | [/api/v1/admin/security-posture](#get-api-v1-admin-security-posture) | Read instance security posture and warnings | | `GET` | [/api/v1/audit](#get-api-v1-audit) | Paginated, filterable workspace audit log | | `GET` | [/api/v1/admin/memory/stats](#get-api-v1-admin-memory-stats) | Memory subsystem totals + per-tier/per-agent rollups | | `GET` | [/api/v1/admin/memory/versions](#get-api-v1-admin-memory-versions) | Row-level drill-down into `memory_versions` | | `GET` | [/api/v1/admin/memory/versions/\{id}/content](#get-api-v1-admin-memory-versions-id-content) | Raw blob bytes for a single memory version | | `GET` | [/api/v1/admin/memory/config](#get-api-v1-admin-memory-config) | Read per-workspace memory configuration | | `PATCH` | [/api/v1/admin/memory/config](#patch-api-v1-admin-memory-config) | Partial-merge update of memory configuration | | `POST` | [/api/v1/admin/memory/user-model-sync](#post-api-v1-admin-memory-user-model-sync) | Run the operator-model sweep now, with the per-workspace summary | | `POST` | [/api/v1/admin/memory/peer-card-sync](#post-api-v1-admin-memory-peer-card-sync) | Run the peer-card sweep now, with the per-workspace summary | | `GET` | [/api/v1/admin/keeper/requests](#get-api-v1-admin-keeper-requests) | Keeper access-request audit log | | `GET` | [/api/v1/admin/keeper/requests/\{requestId}/events](#get-api-v1-admin-keeper-requests-requestid-events) | Append-only transition history for one request | | `GET` | [/api/v1/admin/journal/verify](#get-api-v1-admin-journal-verify) | Verify the audit journal hash-chain (tamper-evidence) | | `POST` | [/api/v1/internal/keeper/skill-review](#post-api-v1-internal-keeper-skill-review) | F4.1 — periodic skill audit | | `POST` | [/api/v1/internal/keeper/behavior](#post-api-v1-internal-keeper-behavior) | F4.2 — post-tool-call behavior monitor | | `POST` | [/api/v1/internal/keeper/memory-health](#post-api-v1-internal-keeper-memory-health) | F4.3 — periodic memory consolidation review | | `POST` | [/api/v1/internal/keeper/negative-learning](#post-api-v1-internal-keeper-negative-learning) | F4.4 — failure-event lesson capture | | `GET` | [/api/v1/system/setup-status](#get-api-v1-system-setup-status) | First-run bootstrap + signup gate | | `GET` | [/api/v1/system/telemetry](#get-api-v1-system-telemetry) | Read-only Sentry consent gate | | `GET` | [/api/v1/system/version](#get-api-v1-system-version) | Running binary's build identity + latest release | | `GET` | [/api/v1/metrics/timeseries](#get-api-v1-metrics-timeseries) | Bucketed time-series metrics for dashboard charts | ## Stats & users Read surfaces for workspace-level counts and membership. Both require the OWNER role. ## GET /api/v1/admin/stats Returns aggregate statistics for the current workspace. **Required role:** OWNER **Request:** no body. **Response:** JSON object shown below. | Status | Condition | | - | - | | `200` | Statistics returned. | | `403` | Caller is not OWNER. | ### Response ```json theme={null} { "workspaces": 1, "users": 12, "agents": 8, "running": 3 } ``` | Field | Type | Description | | - | - | - | | `workspaces` | `integer` | Always 1 (scoped to current workspace) | | `users` | `integer` | Number of workspace members | | `agents` | `integer` | Total agents (excluding soft-deleted) | | `running` | `integer` | Agents with a currently running agent run | > [!NOTE] > > Stats are scoped to the current workspace to prevent cross-workspace data leakage. The `workspaces` field always returns 1. ## GET /api/v1/admin/users Lists the people the caller administers, one row per person. A workspace `OWNER` or `ADMIN` gets the members of the current workspace. An **instance administrator** (see [People and workspaces across the instance](#people-and-workspaces-across-the-instance)) gets every account on the instance, including accounts that belong to no workspace. The `X-Admin-Scope` response header says which: `workspace` or `instance`. **Required role:** ADMIN or OWNER (`manage` permission). **Request:** no body. **Response:** JSON array shown below. | Status | Condition | | - | - | | `200` | People returned. | | `401` | Missing authentication or workspace context. | | `403` | Caller is not ADMIN or OWNER. | | `500` | A query failed. | ### Response ```json theme={null} [ { "id": "user-uuid", "email": "alice@example.com", "full_name": "Alice Chen", "avatar_url": "https://...", "created_at": "2025-01-01T00:00:00Z", "workspace": { "id": "ws-uuid", "name": "Engineering", "slug": "engineering" }, "role": "ADMIN", "memberships": [ { "member_id": "wm-cuid", "workspace_id": "ws-uuid", "name": "Engineering", "slug": "engineering", "role": "ADMIN", "joined_at": "2025-01-01T00:00:00Z" } ], "last_active_at": "2026-09-29T08:12:44Z", "active_sessions": 2, "cli_tokens": 1, "locked_until": null, "failed_login_count": 0, "email_verified": true } ] ``` | Field | Type | Description | | - | - | - | | `id` | `string` | User ID | | `email` | `string` | User email address | | `full_name` | `string?` | Display name (nullable) | | `avatar_url` | `string?` | Avatar URL (nullable) | | `created_at` | `string` | When the account was created | | `workspace` | `object?` | The membership in the caller's workspace, else the first one; null for an account in no workspace | | `role` | `string?` | Role in that workspace (OWNER, ADMIN, MANAGER, MEMBER, VIEWER) | | `memberships` | `array` | Every membership the caller may see: only the current workspace's for a workspace admin, all of them for the instance owner. `member_id` is the id the workspace member routes take. | | `last_active_at` | `string?` | Latest use of a session that is not signed out | | `active_sessions` | `int` | Signed-in devices (not revoked, not expired) | | `cli_tokens` | `int` | Live CLI tokens (not revoked, not expired) | | `locked_until` | `string?` | Set while a sign-in lockout is in force; null otherwise, including after a lock has run out | | `failed_login_count` | `int` | Consecutive failed sign-ins | | `email_verified` | `bool` | Whether the address has been verified | ## `GET /api/v1/admin/users/{userId}/sessions` A person's signed-in devices, with device and IP address, and their live CLI tokens (name, scopes, last use — never the secret). `current` marks the session the caller is using. **Required role:** ADMIN or OWNER (`manage` permission). The person must be a member of the caller's workspace unless the caller is the instance owner; anyone else is `404`, the same answer as an id that does not exist. An ADMIN cannot act on an OWNER of the workspace. **Request:** no body; `userId` is the path parameter. **Response:** ```json theme={null} { "sessions": [ { "id": "sess-cuid", "created_at": "2026-09-28T07:00:00Z", "last_used_at": "2026-09-29T08:12:44Z", "expires_at": "2026-10-28T07:00:00Z", "user_agent": "Chrome on macOS", "ip": "10.0.0.7", "current": false } ], "cli_tokens": [ { "id": "tok-cuid", "name": "laptop", "scopes": ["agents:read"], "created_at": "2026-09-01T10:00:00Z", "last_used_at": "2026-09-27T16:00:00Z", "expires_at": null } ] } ``` | Status | Condition | | - | - | | `200` | Sessions and tokens returned. | | `400` | Missing `userId`. | | `401` | Missing authentication. | | `403` | Caller is not ADMIN or OWNER, or an ADMIN targets an OWNER. | | `404` | No such person among those the caller administers. | | `500` | A query failed. | ## `POST /api/v1/admin/users/{userId}/sessions/{sessionId}/revoke` Signs a person out of one device. The session is marked revoked with reason `admin_revoke`, and an audit entry `user.session_revoked` is written. Other devices and CLI tokens are untouched. **Required role:** ADMIN or OWNER, with the same reach rules as the sessions list above. **Request:** no body; `userId` and `sessionId` are path parameters. **Response:** `204 No Content`. | Status | Condition | | - | - | | `204` | Signed out. | | `400` | Missing `userId` or `sessionId`. | | `401` | Missing authentication. | | `403` | Caller is not ADMIN or OWNER, or an ADMIN targets an OWNER. | | `404` | No such person, or the session is not theirs. | | `500` | The revoke failed. | ## `POST /api/v1/admin/users/{userId}/sessions/revoke-all` Signs a person out of every device. Sessions are marked revoked with reason `admin_invalidate` — the reason the host-side `crewship admin invalidate-sessions` writes — and an audit entry `user.sessions_revoked` is written. The password stays as it is; CLI tokens are separate credentials and stay valid. **Required role:** ADMIN or OWNER, with the same reach rules as above. **Request:** no body; `userId` is the path parameter. **Response:** ```json theme={null} { "revoked": 2 } ``` | Status | Condition | | - | - | | `200` | Signed out; `revoked` counts the sessions ended. | | `400` | Missing `userId`. | | `401` | Missing authentication. | | `403` | Caller is not ADMIN or OWNER, or an ADMIN targets an OWNER. | | `404` | No such person among those the caller administers. | | `500` | The revoke failed. | ## `POST /api/v1/admin/users/{userId}/unlock` Lifts a sign-in lockout: clears `locked_until` and resets the failed-attempt counter, so the person can sign in straight away. Writes an audit entry `user.unlocked`. Unlocking an account that is not locked succeeds and changes nothing. **Required role:** ADMIN or OWNER, with the same reach rules as above. **Request:** no body; `userId` is the path parameter. **Response:** `204 No Content`. | Status | Condition | | - | - | | `204` | Unlocked. | | `400` | Missing `userId`. | | `401` | Missing authentication. | | `403` | Caller is not ADMIN or OWNER, or an ADMIN targets an OWNER. | | `404` | No such person among those the caller administers. | | `500` | The update failed. | ## People and workspaces across the instance The routes under `/api/v1/admin/instance/` act on the whole server: every account and every workspace, whether or not the caller belongs to it. They take no `workspace_id`. **Who may call them: an instance administrator.** That is: 1. the account whose email is `CREWSHIP_OWNER_EMAIL` on the server, which cannot be removed or suspended over the API; 2. anyone named with `PUT /api/v1/admin/instance/admins/{userId}` (`users.instance_role`). The list is always explicit. On an install that names nobody and has no `CREWSHIP_OWNER_EMAIL`, the first time anyone's status is asked the server names the OWNERs of the oldest workspace — the people it treated as admins before — records that in `app_settings` and in the instance audit (`instance.admin_bootstrapped`), and never does it again. Removing every named admin later does not bring that rule back; the way in when nobody can administer is `crewship admin instance add-admin --local` on the host. The last active instance administrator cannot be removed or suspended (`409`): with no `CREWSHIP_OWNER_EMAIL`, someone named and unsuspended has to be left. A suspended account is never an instance administrator. Being ADMIN or OWNER of a workspace is not enough for these routes, nor for the instance-wide settings that also require it (log level, rate limits, re-encryption, legacy resource pruning, Keeper's judge and evaluator models, notification providers, instance settings and feature-flag definitions). A CLI token needs the `instance:admin` scope, or no scope restriction, to reach them. An instance administrator can mint an `instance:admin` token whatever their workspace role, including with no workspace at all. Every instance change and its audit entry are written in one transaction: if the audit entry cannot be written, the change is undone and the route answers `500`. An instance administrator also passes the ADMIN floor of every other `/api/v1/admin/` route, and need not belong to any workspace: on those routes they may name any live workspace in `workspace_id`, member or not (an unknown one is `404`), and the instance-wide reads — `GET /api/v1/admin/stats`, `/admin/health`, `/admin/log-level`, `/admin/rate-limits`, `/admin/security-posture`, `/admin/keeper/config`, `/admin/keeper/aux`, `/admin/keeper/judge/models`, `/admin/legacy-resources`, `/api/v1/system/keeper`, `/api/v1/system/aux-status` and `/api/v1/notification-providers` — also answer with no workspace at all, for the whole instance. A route about one workspace's data answers an instance administrator who names none with `400` ("choose a workspace"). The instance settings writes (log level, rate limits, Keeper judge, providers) need no workspace either. Everyone else keeps the workspace rules: `400` without a workspace, `403` outside theirs. `GET /api/v1/admin/stats` without a workspace counts the whole instance. Also, and `GET /api/v1/admin/users` and `GET /api/v1/admin/workspaces` answer for the whole instance (`X-Admin-Scope: instance`). Those two, and a person's sessions, unlock and sign-out routes, also answer an instance administrator who names no workspace, since they need not belong to one; anyone else still needs `workspace_id`. Those lists carry `instance_admin` and `instance_admin_source` (`env` or `role`), `suspended_at`, `suspended_reason` and `setup_link_expires_at` per person, and `owners` per workspace. `GET /api/auth/session` returns `is_instance_admin` for the signed-in user. Every write below adds a row to the instance audit (`instance.*` actions). It has no workspace of its own, so the record of a deleted workspace or erased account survives it. ## `POST /api/v1/admin/instance/people` Creates an account, puts it in any number of workspaces, and returns a setup link valid for 7 days. No email is sent: the administrator passes the link on, and the person chooses their own password. Roles may include `OWNER`. **Auth:** instance administrator. **Request:** ```json theme={null} { "email": "lucie@acme.example", "full_name": "Lucie Horáková", "memberships": [{ "workspace_id": "ws-cuid", "role": "MEMBER" }] } ``` **Response:** `201 Created` ```json theme={null} { "user_id": "uuid", "email": "lucie@acme.example", "memberships": [{ "workspace_id": "ws-cuid", "role": "MEMBER" }], "setup_url": "https://crewship.example/reset-password?token=…", "expires_at": "2026-10-06T10:00:00Z" } ``` | Status | Condition | | - | - | | `201` | Account created. | | `400` | Invalid JSON, email, role, or a workspace named twice. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | A named workspace does not exist. | | `409` | An account with this email exists; change its access instead. | | `500` | A write failed. | | `503` | The instance URL is unknown; set `CREWSHIP_PUBLIC_URL`. | ## `PUT /api/v1/admin/instance/workspaces/{workspaceId}/members/{userId}` Gives a person access to a workspace, or changes their role there. Unlike the workspace members route, the role ladder does not apply: an instance administrator may make someone `OWNER`. The last OWNER of a workspace cannot be moved down; hand the workspace over first. **Auth:** instance administrator. **Request:** `{ "role": "ADMIN" }`, one of `OWNER`, `ADMIN`, `MANAGER`, `MEMBER`, `VIEWER`. **Response:** `201 Created` when access was added, `200 OK` when a role changed: ```json theme={null} { "workspace_id": "ws-cuid", "user_id": "uuid", "role": "ADMIN", "created": true } ``` | Status | Condition | | - | - | | `200` | Role changed. | | `201` | Access added. | | `400` | Invalid JSON or role. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No such workspace or person. | | `409` | This would leave the workspace without an owner. | | `500` | A write failed. | ## `DELETE /api/v1/admin/instance/workspaces/{workspaceId}/members/{userId}` Takes a person out of a workspace, with their crew memberships there. Pages they own move first, as when a workspace admin removes them. The last OWNER stays. **Auth:** instance administrator. **Request:** no body. **Response:** `204 No Content`. | Status | Condition | | - | - | | `204` | Removed. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | The person is not a member of this workspace. | | `409` | The last owner, or pages that need a manual transfer first. | | `500` | A write failed. | ## `POST /api/v1/admin/instance/workspaces` Creates an empty workspace owned by the person named. The administrator is not added to it. **Auth:** instance administrator. **Request:** ```json theme={null} { "name": "Marketing", "slug": "marketing", "owner_user_id": "uuid", "preferred_language": "cs" } ``` **Response:** `201 Created` ```json theme={null} { "id": "ws-cuid", "name": "Marketing", "slug": "marketing", "owner_user_id": "uuid", "created_at": "2026-09-29T10:00:00Z" } ``` | Status | Condition | | - | - | | `201` | Created. | | `400` | Invalid JSON, name (2–100 characters), slug (2–50), language, or owner. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `409` | The slug is taken, or the owner is suspended. | | `500` | A write failed. | ## `PATCH /api/v1/admin/instance/workspaces/{workspaceId}` Renames any workspace on its owner's behalf, and says what it is for. The workspace's own settings are open only to its members; an instance administrator usually is not one, and is not added by this call. The slug stays, so links and the CLI keep working. `kind` is `team` (a workspace people share — the default) or `personal` (the empty "Name's Workspace" a sign-up without an invitation gets: that person's personal account). Admin › People & workspaces lists personal accounts under People, apart from the workspaces. Existing sign-up workspaces were marked `personal` when this field arrived, if they still had one member, their owner, and the name sign-up gave them. **Auth:** instance administrator. **Request:** `{ "name": "Demo", "kind": "team" }` — either field, or both. **Response:** ```json theme={null} { "id": "ws-cuid", "name": "Demo", "slug": "demo-user-s-workspace-1a2b3c4d", "kind": "team" } ``` A change is recorded in the instance audit as `instance.workspace_updated` with each field's old and new value; sending the current values changes nothing and records nothing. | Status | Condition | | - | - | | `200` | Updated, or already as asked. | | `400` | Invalid JSON, neither field, a name outside 2–100 characters, or an unknown `kind`. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No such workspace, or it is deleted. | | `500` | A write failed. | ## `POST /api/v1/admin/instance/workspaces/{workspaceId}/transfer-ownership` Makes a member the workspace's owner. Every previous owner becomes an ADMIN, so the workspace keeps exactly one. **Auth:** instance administrator. **Request:** `{ "user_id": "uuid" }`. The person must already be a member. **Response:** ```json theme={null} { "workspace_id": "ws-cuid", "owner_user_id": "uuid", "previous_owner_user_ids": ["uuid-2"] } ``` | Status | Condition | | - | - | | `200` | Ownership transferred. | | `400` | Missing `user_id`. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No such workspace. | | `409` | The person is not a member of the workspace. | | `500` | A write failed. | ## `DELETE /api/v1/admin/instance/workspaces/{workspaceId}` Deletes a workspace: its agents and crews are soft-deleted and its memberships removed, as with `DELETE /api/v1/workspaces/{workspaceId}`. The owner's "not your only workspace" rule does not apply. **Auth:** instance administrator. **Request:** `{ "confirm_slug": "marketing" }`, the workspace's slug. **Response:** `204 No Content`. | Status | Condition | | - | - | | `204` | Deleted. | | `400` | Invalid JSON, or `confirm_slug` does not match. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No such workspace, or it is already deleted. | | `500` | A write failed. | ## `POST /api/v1/admin/instance/people/{userId}/suspend` Blocks an account. Sign-in, token refresh and CLI tokens are refused, and every session and CLI token ends now. Workspace access is kept, so reactivation restores it. A suspended sign-in gets the same answer as a wrong password. **Auth:** instance administrator. **Request:** optional `{ "reason": "left the company" }`, kept for the audit. **Response:** ```json theme={null} { "user_id": "uuid", "suspended_at": "2026-09-29T10:00:00Z", "sessions_revoked": 3, "cli_tokens_revoked": 1 } ``` | Status | Condition | | - | - | | `200` | Suspended. | | `400` | Invalid JSON. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No such person. | | `409` | Your own account, the `CREWSHIP_OWNER_EMAIL` account, or the last active instance administrator. | | `500` | A write failed. | ## `POST /api/v1/admin/instance/people/{userId}/reactivate` Lifts a suspension. Sessions and tokens it ended stay ended. **Auth:** instance administrator. **Request:** no body. **Response:** `204 No Content`. | Status | Condition | | - | - | | `204` | Reactivated. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No such person. | | `500` | A write failed. | ## `POST /api/v1/admin/instance/people/{userId}/setup-link` Issues a new setup link and voids the previous one. The plaintext link is never stored, so reissuing is the only way to show it again. Only an account nobody controls gets one: no password, no linked sign-in provider and no verified email. Anyone else resets their own password. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "user_id": "uuid", "setup_url": "https://crewship.example/reset-password?token=…", "expires_at": "2026-10-06T10:00:00Z" } ``` | Status | Condition | | - | - | | `200` | A new link. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No such person. | | `409` | Somebody already signs in to this account. | | `500` | A write failed. | | `503` | The instance URL is unknown; set `CREWSHIP_PUBLIC_URL`. | ## `DELETE /api/v1/admin/instance/people/{userId}/setup-link` Voids the pending setup link, for example one sent to the wrong place. **Auth:** instance administrator. **Request:** no body. **Response:** `204 No Content`. | Status | Condition | | - | - | | `204` | Voided. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No such person, or no pending link. | | `500` | A write failed. | ## `PUT /api/v1/admin/instance/admins/{userId}` Names a person an instance administrator. **Auth:** instance administrator. **Request:** no body. **Response:** `204 No Content`. | Status | Condition | | - | - | | `204` | Named. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No such person. | | `409` | The account is suspended. | | `500` | A write failed. | ## `DELETE /api/v1/admin/instance/admins/{userId}` Removes a named instance administrator. Nobody removes themselves, so there is always another administrator who saw it happen. `CREWSHIP_OWNER_EMAIL` is changed in the server's environment, not here. **Auth:** instance administrator. **Request:** no body. **Response:** `204 No Content`. | Status | Condition | | - | - | | `204` | Removed. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No such person, or they are not a named administrator. | | `409` | Your own account, the `CREWSHIP_OWNER_EMAIL` account, or the last active instance administrator. | | `500` | A write failed. | ## `GET /api/v1/admin/instance/audit` Instance-level actions, newest first. `?limit=` (default 100, at most 500) and `?entity_id=` narrow it; `entity_id` matches the person or workspace acted on, and a workspace also matches the rows that name it as their target. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} [ { "id": "hex", "user_id": "uuid", "user_email": "admin@crewship.example", "action": "instance.member_added", "entity_type": "workspace_member", "entity_id": "uuid", "target_workspace_id": "ws-cuid", "metadata": "{\"role\":\"MEMBER\"}", "created_at": "2026-09-29T10:00:00.123Z" } ] ``` Actions: `instance.user_created`, `instance.member_added`, `instance.member_role_changed`, `instance.member_removed`, `instance.workspace_created`, `instance.workspace_ownership_transferred`, `instance.workspace_deleted`, `instance.user_suspended`, `instance.user_reactivated`, `instance.setup_link_issued`, `instance.setup_link_revoked`, `instance.admin_granted`, `instance.admin_revoked`, `instance.admin_bootstrapped`, `instance.keeper_governance_updated`, `instance.keeper_defaults_updated`. | Status | Condition | | - | - | | `200` | Rows returned. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A query failed. | ## `GET /api/v1/admin/instance/audit/verify` Walks the whole instance audit chain on demand, read-only and outside any write transaction. Audited writes check only the chain tail, so this is where history is verified (the backup drill runs the same check). **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "ok": false, "count": 412, "continuation_verified": true, "historical_status": "post_upgrade_invalid", "unchained_fallback": 1, "reason": "instance audit history contains an unverifiable entry" } ``` `ok` is true only when every row verifies. `continuation_verified` means the segment after the last defect (or OWNER reseal) verifies. `historical_status` is `legacy_unverified` (rows older than the chain), `historical_unverified` or `historical_invalid` (defects in rows that predate the keyring upgrade or the last reseal), or `post_upgrade_invalid` (a defect in a keyring-signed row or after the last reseal). `unchained_fallback` counts security actions recorded outside the chain while its tail was broken. | Status | Condition | | - | - | | `200` | Verified (whatever the verdict). | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | Verification keys or the read failed. | ## `GET /api/v1/admin/instance/keeper/governance` The Keeper watchdog settings of every workspace on the instance, including workspaces the caller is not a member of, and the defaults for new workspaces. Every workspace has its own settings: it takes a copy of the defaults when it is created, and a later change of the defaults does not reach it. `configured: false` marks a workspace with no row of its own, which runs on the built-in opt-out: watchdog off, DENY alerts from risk 7. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "defaults": { "configured": true, "enabled": true, "deny_notify_min_risk": 5, "behavior_sample_every": 10 }, "workspaces": [ { "workspace_id": "ws-cuid", "workspace_name": "Lab", "workspace_slug": "lab", "configured": true, "enabled": true, "security_contact_user_id": "", "deny_notify_min_risk": 5, "watch_spec": "", "watch_presets": ["exfiltration"], "require_second_approver": false, "gov_model_provider": "", "gov_model_id": "", "gov_model_credential_id": "", "auto_lease_seconds": 900, "behavior_sample_every": 10, "effective_second_approver": { "min_security_level": 4, "source": "tier" } } ] } ``` | Status | Condition | | - | - | | `200` | Every live workspace, by name. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `PUT /api/v1/admin/instance/keeper/governance` Sets the watchdog for one, several or all workspaces. `set` is a partial update with the same fields and bounds as the per-workspace `PUT /api/v1/admin/keeper/governance`: only the fields sent change. * `workspaces` names the targets by id or slug. `all: true` targets every existing workspace. Send one or the other. Neither changes what a new workspace starts with; that is `PUT /api/v1/admin/instance/keeper/governance/defaults`. * `dry_run: true` computes the changes and writes nothing. The console's confirmation dialog shows this response. Every response carries a `preview_id`, a fingerprint of every target's settings before and after. Send it back as `expect_preview` when confirming: if a workspace was created or a value changed since the preview, the save answers `409` and writes nothing. * The save is one transaction. When the merged settings are invalid in any workspace, the response is `400` naming that workspace, and nothing is written anywhere. * A workspace that already has the values is reported with empty `changes` and left alone. Each workspace that changes gets an `instance.keeper_governance_updated` entry in the instance audit, with the fields it changed from and to. * `security_contact_user_id` and `gov_model_credential_id` name something that belongs to one workspace, and are refused for more than one. * `gov_model_credential_id` must name an active credential. Once bound, it can be changed, rotated or answered through an escalation only by a workspace OWNER or ADMIN. `credential.rotate` and the MANAGER update right do not reach it; those calls answer `403`. An OAuth grant never replaces its value. **Auth:** instance administrator. **Request:** ```json theme={null} { "all": true, "dry_run": true, "set": { "enabled": true, "deny_notify_min_risk": 5 } } ``` Confirming that preview: ```json theme={null} { "all": true, "expect_preview": "3f9c0a1b2d4e5f6a7b8c9d0e", "set": { "enabled": true, "deny_notify_min_risk": 5 } } ``` **Response:** ```json theme={null} { "applied": false, "changed": 1, "preview_id": "3f9c0a1b2d4e5f6a7b8c9d0e", "workspaces": [ { "workspace_id": "ws-cuid", "workspace_name": "Lab", "workspace_slug": "lab", "changes": [ { "field": "deny_notify_min_risk", "before": 7, "after": 5 } ] }, { "workspace_id": "ws-cuid-2", "workspace_name": "Ops", "workspace_slug": "ops", "changes": [] } ] } ``` | Status | Condition | | - | - | | `200` | Saved, or previewed with `dry_run`. | | `400` | No target, both `all` and `workspaces`, nothing to change, a value out of bounds or incoherent in some workspace, or a per-workspace field sent for several. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | A workspace in `workspaces` does not exist. | | `409` | `expect_preview` no longer matches: the workspaces or their settings changed since the preview. Nothing was saved. | | `500` | A write failed. Nothing was saved. | ## `GET /api/v1/admin/instance/keeper/governance/defaults` The template a new workspace's Keeper watchdog starts with. A workspace copies it when it is created — through signup, the workspaces API or `POST /api/v1/admin/instance/workspaces` — and keeps that copy: changing the template later changes no existing workspace. `configured: false` means it was never saved and is the built-in opt-out. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "applied": false, "configured": true, "defaults": { "enabled": true, "deny_notify_min_risk": 5, "behavior_sample_every": 10, "auto_lease_seconds": 0 }, "changes": [], "preview_id": "" } ``` | Status | Condition | | - | - | | `200` | The template. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `PUT /api/v1/admin/instance/keeper/governance/defaults` Changes the template for new workspaces. `set` takes the same fields and bounds as the workspace PUT, except `security_contact_user_id` and `gov_model_credential_id`: a person and a vault credential belong to one workspace, so they are refused here. `dry_run: true` returns the changes and a `preview_id` and writes nothing; send the id back as `expect_preview` to save exactly that, or get `409` if the template changed in between. A save records `instance.keeper_defaults_updated` in the instance audit, in the same transaction. **Auth:** instance administrator. **Request:** ```json theme={null} { "expect_preview": "3f9c0a1b2d4e5f6a7b8c9d0e", "set": { "enabled": true, "behavior_sample_every": 10 } } ``` **Response:** as for `GET`, with `applied: true` and the `changes` made. | Status | Condition | | - | - | | `200` | Saved, or previewed with `dry_run`. | | `400` | Nothing to change, a value out of bounds, or a per-workspace field. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `409` | `expect_preview` no longer matches. Nothing was saved. | | `500` | A write failed. Nothing was saved. | ## `GET /api/v1/admin/instance/keeper/requests` Keeper decisions across workspaces, newest first: credential requests and the background reviews, each row with its workspace. A request whose agent is gone has no workspace to show under and is left out. Query parameters: * `workspace`: ids or slugs, comma-separated. Omitted or `all` means every workspace. * `request_type`: one or more kinds, comma-separated, e.g. `access,execute` for credential requests or `behavior`. * `decision`: `ALLOW`, `DENY`, `ESCALATE` or `PENDING`. * `limit`: default 200, at most 1000. `offset`: rows to skip. `total` is how many rows the whole filter matches, for paging. `counts` are the decisions under the workspace and kind filter, leaving `decision` out, so the decision chips keep their numbers while one is picked. `by_type` counts every kind under the workspace filter alone, and `by_workspace` every workspace regardless of the filter, for the panel beside the list. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "items": [ { "id": "kr-cuid", "workspace_id": "ws-cuid", "workspace_name": "Lab", "agent_id": "ag-cuid", "agent_name": "Researcher", "crew_id": "crew-cuid", "credential_id": "cred-cuid", "credential_name": "POSTGRES_PASSWORD", "intent": "read the orders table", "request_type": "access", "decision": "DENY", "reason": "Not bound to this crew.", "risk_score": 7, "created_at": "2026-09-30T10:00:00Z", "decided_at": "2026-09-30T10:00:02Z" } ], "total": 1, "counts": { "allow": 0, "deny": 1, "escalate": 0, "pending": 0 }, "by_type": { "access": 1, "behavior": 4 }, "by_workspace": [ { "workspace_id": "ws-cuid", "workspace_name": "Lab", "workspace_slug": "lab", "count": 12 } ] } ``` | Status | Condition | | - | - | | `200` | The page. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | A workspace in `workspace` does not exist. | | `500` | A read failed. | ## `GET /api/v1/admin/instance/keeper/health` The rolling decision window of every workspace, in the shape of `GET /api/v1/admin/keeper/health` plus the workspace's name and slug. An empty window is listed too: zero samples is its own answer, not a healthy one. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "workspaces": [ { "workspace_id": "ws-cuid", "workspace_name": "Lab", "workspace_slug": "lab", "samples": 42, "allow": 30, "deny": 8, "escalate": 4, "judge_failures": 0, "progressed_rate": 0.81, "judge_failure_rate": 0, "p95_latency_ms": 900, "min_samples": 20 } ] } ``` | Status | Condition | | - | - | | `200` | One window per workspace. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `GET /api/v1/admin/instance/workbook-editor` The embedded workbook editor's mode and, in same-host mode, the server's proxy self-check of every public Studio origin it knows: the configured one (`CREWSHIP_PAGE_STUDIO_ORIGIN`, `source: "configured"`), or the origins signed-in browsers used (`source: "learned"`). The public `/healthz` reports only the coarse `status` (`ok`, `pending`, `failed` or `disabled`); origins, redirect targets and error text are only here and in the server log. A learned origin carries `learned_from`, the ID of the user whose signed-in request taught it, and `admin_session`, set once an instance administrator's session used it. Only the configured origin and origins with `admin_session` count towards `status` and `/healthz`: any signed-in user can make the server learn an origin, so the others are listed for you to recognise. `last_seen` is the last signed-in request from the origin; one not seen for 24 hours is forgotten. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "mode": "same-host", "status": "disabled", "origins": [ { "origin": "https://crewship.example.com", "source": "learned", "learned_from": "usr_2f9c", "admin_session": true, "proxy_check": "failed", "disabled": true, "cause": "redirect", "problems": ["/_editor/b/x is redirected (HTTP 302 to \"https://sso.example.com/login\")"], "consecutive_passes": 1, "checked_at": "2026-10-23T08:00:00Z", "last_seen": "2026-10-23T08:04:00Z" } ] } ``` `mode` is `off`, `same-host` or `dedicated` (then `origin` names the dedicated editor origin). `cause` is one of `redirect`, `path_rewrite` and `marker_missing` (all disable the editor on that exact origin; with `marker_missing` the `X-Crewship-Route` response header is removed in front, so the check cannot tell where a path ends up), `not_routed` and `host_rewritten` (the editor stays enabled but does not work there). A disabled origin is enabled again after three consecutive passing checks; `consecutive_passes` counts them. | Status | Condition | | - | - | | `200` | The editor state; `{"mode":"off"}` while the editor is off. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | ## `GET /api/v1/admin/instance/page-limit` The maximum number of pages a workspace may hold, for instance administrators. The default is 100. Every page-creating path (pages, Designs, artifact projects, Documents, Workbooks, imports) checks this one setting. Archived pages count. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "max_pages_per_workspace": 100, "default": 100, "min": 10, "max": 10000 } ``` | Status | Meaning | | - | - | | `200` | The current limit and its bounds. | | `401` | Not signed in. | | `403` | Caller is not an instance administrator (a workspace owner, an agent token, a viewer or a non-member all get `403`). | | `500` | A read failed. | ## `PUT /api/v1/admin/instance/page-limit` Set the maximum number of pages per workspace. The change applies to every workspace and is recorded in the instance audit log (`instance.page_limit_set`, with the old and new value). Lowering the limit below what a workspace already holds deletes nothing: it only refuses new pages there until the count falls. **Auth:** instance administrator. **Request body:** JSON, unknown keys refused. ```json theme={null} { "max_pages_per_workspace": 250 } ``` The value is a whole number from 10 to 10000. **Response:** the same object as `GET`. A create that reaches the limit is refused with `422` and `code: "pages_limit"` (`kind: "cap"`, `detail.pages_existing`, `detail.pages_limit`); the `error` sentence states the limit. This is the same answer for pages, Designs and artifact projects. | Status | Meaning | | - | - | | `200` | Saved; the new limit. | | `400` | Invalid JSON, no value, a value that is not a whole number, or outside 10-10000. | | `401` | Not signed in. | | `403` | Caller is not an instance administrator. | | `500` | The save failed; nothing changed. | ## `GET /api/v1/admin/instance/artifact-storage` The aggregate artifact storage budget, for instance administrators: the per-workspace limit, the instance limit and the instance-wide counters. The defaults are 32 GiB per workspace and 64 GiB per instance. A full budget refuses writes with `413` `artifact_storage_quota`; history is never deleted automatically (`retention` is always `keep-all`). **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "workspace_limit_bytes": 34359738368, "instance_limit_bytes": 68719476736, "used_bytes": 1048576, "reserved_bytes": 0, "level": "none", "workspaces": 3, "retention": "keep-all" } ``` `reserved_bytes` is capacity held by uploads in flight; `level` is `none`, `near`, `critical` or `full` for the instance as a whole. | Status | Meaning | | - | - | | `200` | The limits and counters. | | `401` | Not signed in. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `PUT /api/v1/admin/instance/artifact-storage` Set the workspace limit, the instance limit, or both. A key you leave out keeps its value. The change applies to every workspace and is recorded in the instance audit log (`instance.artifact_storage_limits_set`). Lowering a limit below current usage deletes nothing: it only refuses further growth until usage falls. Defaults are unchanged until you call this. **Auth:** instance administrator. **Request body:** JSON, unknown keys refused. ```json theme={null} { "workspace_limit_bytes": 17179869184, "instance_limit_bytes": 51539607552 } ``` Each value is an integer number of bytes between 1 MiB (`1048576`) and 1 PiB, and the workspace limit cannot exceed the instance limit. **Response:** the same object as `GET`. | Status | Meaning | | - | - | | `200` | Saved; the new limits and counters. | | `400` | Invalid JSON, no limit given, a value out of range, or a workspace limit above the instance limit (set both together to raise or lower them). | | `401` | Not signed in. | | `403` | Caller is not an instance administrator. | | `500` | The save failed; nothing changed. | ## `POST /api/v1/admin/instance/artifact-storage/recompute` Rebuild the usage counters from the artifact source tables (versions, proposals, Design, Data, documents, Slides, GridCraft and Mooring) in one transaction, and report the drift. The counters are trigger-maintained; this repairs them after a restore, a manual edit or a bug. It is idempotent (a second run reports `changed: false`), writes only the derived counters, never deletes artifact data and never changes a limit. Each run that writes is recorded in the instance audit log (`instance.artifact_storage_recomputed`). **Auth:** instance administrator. **Request body:** optional JSON `{ "dry_run": true }` to report the drift without writing. **Response:** ```json theme={null} { "dry_run": false, "changed": true, "instance": { "used_bytes_before": 123, "used_bytes_after": 1048576, "reserved_bytes_before": 4096, "reserved_bytes_after": 0 }, "workspaces_checked": 3, "workspaces_drifted": 1, "workspaces": [ { "workspace_id": "ws_1", "used_bytes_before": 123, "used_bytes_after": 1048576, "reserved_bytes_before": 0, "reserved_bytes_after": 0 } ], "data_deleted": false } ``` `workspaces` lists only the workspaces whose counters disagreed. `reserved_bytes_after` counts the reservations that exist when the run holds the writer fence. | Status | Meaning | | - | - | | `200` | The drift report. | | `400` | Invalid JSON body. | | `401` | Not signed in. | | `403` | Caller is not an instance administrator. | | `500` | The recompute failed; no counter changed. | ## `GET /api/v1/admin/instance/retention` How long every workspace keeps each kind of data, including workspaces the caller is not a member of. Every window is a number of days, or `null` for forever. Inbox items, chats and Keeper decisions are forever until an administrator sets them. | Window | Default | Can be forever | What ages out | | - | - | - | - | | `routine_runs_days` | 90 | no | Finished routine runs. The last 10 runs of every routine, runs waiting on an approval and runs another run replays are always kept. | | `approvals_days` | 90 | yes | Decided approvals. Pending approvals and autonomy gates are never deleted. | | `audit_days` | forever | yes | Workspace audit entries. | | `credential_audit_days` | 90 | yes | Credential reads. The last use stays on the credential. | | `memory_versions_days` | 30 | no | Memory version history. The instance-wide pass also ages versions out after 30 days, keeping the latest few per file. | | `page_panel_data_days` | 7 | no | Page panel values, dropped on the panel's next push. The newest value always stays. | | `inbox_days` | forever | yes | Resolved inbox items, and read items that block nothing. Open items are never deleted. | | `chats_days` | forever | yes | Chats idle longer than the window that hold no open work (below). | | `keeper_decisions_days` | forever | yes | Decided Keeper requests with their ledger rows. Pending and escalated requests, and requests backing a live credential lease, are never deleted. | A chat holds open work, and is kept however old, while it has any delegation, an unresolved escalation, an unresolved reply item in the inbox, a pending approval that names it, an unfinished routine run, or an access grant issued inside the window that is not revoked. Query parameters: | Parameter | Description | | - | - | | `ws` | A workspace id or slug. Repeat it, or separate several with commas. Without it, every workspace. | **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "workspaces": [ { "workspace_id": "ws-cuid", "workspace_name": "Lab", "workspace_slug": "lab", "windows": { "routine_runs_days": 90, "approvals_days": 90, "audit_days": null, "credential_audit_days": 90, "memory_versions_days": 30, "page_panel_data_days": 7, "inbox_days": null, "chats_days": null, "keeper_decisions_days": 365 } } ], "defaults": { "routine_runs_days": 90, "approvals_days": 90, "audit_days": null, "credential_audit_days": 90, "memory_versions_days": 30, "page_panel_data_days": 7, "inbox_days": null, "chats_days": null, "keeper_decisions_days": 365 }, "defaults_configured": ["keeper_decisions_days"], "keys": [ { "key": "inbox_days", "label": "Inbox items", "default_days": null, "forever_allowed": true, "min_days": 1, "max_days": 3650, "detail": "Resolved items, and read items that block nothing, …" } ], "housekeeping": [ { "key": "journal_compaction", "label": "Journal compaction", "value": "30 days", "detail": "Low-value journal entries older than 30 days move to the journal archive, …" } ] } ``` `defaults` is what a workspace created now starts with; `defaults_configured` names the windows an administrator set with `PUT /api/v1/admin/instance/retention/defaults`, the rest are the product defaults. `keys` describes every window, in display order. `housekeeping` lists the limits the server applies on its own and nobody sets: journal compaction, the instance-wide memory version floor, the routine runs always kept, routine and agent webhook receipts, delivered work bodies, page project history, orphaned attachment files, unattributed credential reads and the pre-upgrade database snapshots. No window covers [Artifacts](/guides/artifacts/operations#retention). Artifact versions, Design canvases, Dashboard data and native Word and Sheet history are kept until the artifact itself is deleted, within the per-artifact storage limits. "Page project history" in `housekeeping` is the build history of Pages applications, not artifact versions. | Status | Condition | | - | - | | `200` | Every chosen workspace, by name. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | A workspace in `ws` does not exist. | | `500` | A read failed. | ## `PUT /api/v1/admin/instance/retention` Sets retention windows for one, several or every existing workspace. `windows` carries only the windows being changed; `null` is forever where the window allows it. * `workspace_ids` is required. A list names the targets by id or slug; `null` targets every workspace that exists now. Neither changes what a workspace created later starts with: that is `PUT /api/v1/admin/instance/retention/defaults`, a separate operation. * `dry_run: true` computes the changes and writes nothing. The preview lists every workspace and, in it, every window that changes, each with `rows_affected_next_sweep`: how many rows the next sweep deletes under the new window. The rows are counted, not deleted, and backups taken before still hold them. For page panel data the count is what each panel's next push drops. * Every response carries a `preview_id` fingerprinting the targets and every change. Send it back as `expect_preview` when confirming: if a workspace was created or a window changed since the preview, the save answers `409` and writes nothing. A save without `expect_preview`, or without any preview, is allowed; the console always previews first. * The save is one transaction. A workspace that already has the values is reported with empty `changes` and left alone. Each workspace that changes gets an `instance.retention_updated` entry in the instance audit, with each window's old and new value. * Saving a window deletes nothing by itself. The daily sweep does, at its next run. **Auth:** instance administrator. **Request:** ```json theme={null} { "workspace_ids": ["lab"], "dry_run": true, "windows": { "inbox_days": 90, "chats_days": null } } ``` **Response:** ```json theme={null} { "applied": false, "dry_run": true, "changed": 1, "rows_affected_next_sweep": 412, "preview_id": "3f9c0a1b2d4e5f6a7b8c9d0e", "workspaces": [ { "workspace_id": "ws-cuid", "workspace_name": "Lab", "workspace_slug": "lab", "changes": [ { "key": "inbox_days", "from": null, "to": 90, "rows_affected_next_sweep": 412 } ] } ] } ``` | Status | Condition | | - | - | | `200` | Saved, or previewed with `dry_run`. | | `400` | `workspace_ids` missing or empty, nothing to change, an unknown window, a value that is not a whole number from 1 to 3650, or `null` for a window that cannot be forever. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | A workspace in `workspace_ids` does not exist. | | `409` | `expect_preview` no longer matches. Nothing was saved. | | `500` | A write failed. Nothing was saved. | ## `GET /api/v1/admin/instance/retention/defaults` The retention windows a workspace created now starts with, every window. `configured` names the windows an administrator set; the others are the product defaults in the table under `GET /api/v1/admin/instance/retention`. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "defaults": { "routine_runs_days": 90, "approvals_days": 90, "audit_days": null, "credential_audit_days": 90, "memory_versions_days": 30, "page_panel_data_days": 7, "inbox_days": 90, "chats_days": null, "keeper_decisions_days": null }, "configured": ["inbox_days"] } ``` | Status | Condition | | - | - | | `200` | The defaults. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `PUT /api/v1/admin/instance/retention/defaults` Changes the retention windows a workspace created later starts with. Only the windows sent change; `null` is forever where the window allows it. No existing workspace changes and nothing is deleted, so the response has no row counts and says so with `affects_existing: false`. * `dry_run: true` returns the changes and writes nothing. * A window already at the value is not a change. When anything changes, the instance audit records `instance.retention_defaults_updated` with each window's old and new value. * `defaults` in the response is every window as a new workspace starts after the save (on a dry run, would). **Auth:** instance administrator. **Request:** ```json theme={null} { "windows": { "inbox_days": 90, "chats_days": null }, "dry_run": true } ``` **Response:** ```json theme={null} { "applied": false, "dry_run": true, "affects_existing": false, "changes": [ { "key": "inbox_days", "from": null, "to": 90 } ], "defaults": { "routine_runs_days": 90, "approvals_days": 90, "audit_days": null, "credential_audit_days": 90, "memory_versions_days": 30, "page_panel_data_days": 7, "inbox_days": 90, "chats_days": null, "keeper_decisions_days": null } } ``` | Status | Condition | | - | - | | `200` | Saved, previewed with `dry_run`, or nothing to change. | | `400` | Nothing sent, an unknown window, a value that is not a whole number from 1 to 3650, or `null` for a window that cannot be forever. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A write failed. Nothing was saved. | ## `GET /api/v1/admin/instance/backups/bundles` Every catalogued backup bundle on the server, across every workspace, newest first. Rows whose file is gone are pruned before the list is built. `?workspace=a,b` (slugs or ids) and `?scope=workspace|crew` narrow it. `proof_level` is `1` (written, payload checksum recorded), `2` (decrypted and every section checked against the manifest) or `3` (restored in isolation; `drill_result` says how that went: `ok`, `partial` or `failed`). `incomplete` lists what the bundle should hold and does not; `[]` means it recorded no gap, and `null` means the bundle was catalogued before gaps were recorded — not that it is complete. `kind` is `full` for every bundle made so far. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "bundles": [ { "id": "bk_…", "path": "/var/lib/crewship/backups/crewship-workspace-lab-20260930T020000Z.tar.zst", "file_name": "crewship-workspace-lab-20260930T020000Z.tar.zst", "scope": "workspace", "scope_level": "standard", "kind": "full", "slug": "lab", "workspace_id": "ws-cuid", "workspace_name": "Lab", "workspace_slug": "lab", "created_at": "2026-09-30T02:00:00Z", "created_by": "ops@example.com", "size_bytes": 1048576, "payload_sha256": "9f2c…", "encrypted": true, "format_version": 3, "plan_id": "", "run_id": "", "pinned": false, "proof_level": 1, "proof_checked_at": null, "drill_result": "", "drill_at": null, "drill_report": null, "incomplete": [ {"kind": "attachment_missing", "detail": "2 attached file(s) were not on disk when the backup ran; …", "count": 2, "workspace": "ws-cuid"} ] } ] } ``` | Status | Condition | | - | - | | `200` | The list. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | A workspace in `workspace` does not exist. | | `500` | A read failed. | ## `POST /api/v1/admin/instance/backups/bundles/pin` Pins a catalogued bundle: no retention rule deletes it — not the age rule, not the count floor. The change and its instance audit entry (`instance.backup_pinned`) commit together. **Auth:** instance administrator. **Request:** ```json theme={null} {"path": "/var/lib/crewship/backups/crewship-workspace-lab-20260930T020000Z.tar.zst"} ``` **Response:** ```json theme={null} {"path": "/var/lib/crewship/backups/crewship-workspace-lab-20260930T020000Z.tar.zst", "pinned": true} ``` | Status | Condition | | - | - | | `200` | Pinned (pinning a pinned bundle is not an error). | | `400` | No `path`, or the body is not JSON. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No catalogued bundle has that path. | | `500` | The write failed; nothing changed. | ## `POST /api/v1/admin/instance/backups/bundles/unpin` The reverse of pin: retention rules apply to the bundle again. The change and its instance audit entry (`instance.backup_unpinned`) commit together. **Auth:** instance administrator. **Request:** ```json theme={null} {"path": "/var/lib/crewship/backups/crewship-workspace-lab-20260930T020000Z.tar.zst"} ``` **Response:** ```json theme={null} {"path": "/var/lib/crewship/backups/crewship-workspace-lab-20260930T020000Z.tar.zst", "pinned": false} ``` | Status | Condition | | - | - | | `200` | Unpinned (unpinning an unpinned bundle is not an error). | | `400` | No `path`, or the body is not JSON. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No catalogued bundle has that path. | | `500` | The write failed; nothing changed. | ## `GET /api/v1/admin/instance/backups/bundles/inspect` The manifest of one catalogued bundle of any scope — an instance bundle included, which the per-workspace `GET /api/v1/admin/backups/inspect` cannot find because it belongs to no workspace. The manifest is plaintext: nothing is decrypted and no key is needed. `?path=` is the bundle's path as `GET …/backups/bundles` lists it; only a path in the catalog is ever opened. **Auth:** instance administrator. **Request:** no body. **Response:** the manifest, the same shape as the per-workspace inspect returns: ```json theme={null} {"format_version": 3, "scope": "instance", "created_at": "2026-09-30T02:00:00Z", "encryption": {"enabled": true, "algorithm": "age"}, "contents": {"instance": {"hold_ms": 412}}} ``` | Status | Condition | | - | - | | `200` | The manifest. | | `400` | No `path`. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No catalogued bundle has that path, or its file is no longer on disk. | | `422` | The file is there but its manifest cannot be read. | | `500` | The catalog could not be read. | CLI: `crewship backup inspect ` asks the per-workspace route first and this one when that answers 404 or 400. ## `GET /api/v1/admin/instance/backups/bundles/verify` Proof level 1 for one catalogued bundle of any scope: the sealed payload's SHA-256 against the manifest, without a key. The body is the per-workspace `GET /api/v1/admin/backups/verify`'s: `valid`, `size_bytes`, `manifest`, `error`, and — for an unencrypted bundle only — the row-count completeness fields. To check an encrypted bundle's contents, use `POST …/backups/bundles/check` with the key. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} {"valid": true, "size_bytes": 1048576, "manifest": {"format_version": 3, "scope": "instance"}, "error": "", "completeness_checked": false, "completeness_skip_reason": "bundle is encrypted; verify does not decrypt the payload", "table_row_count_mismatches": null, "scope_shortfalls": null} ``` | Status | Condition | | - | - | | `200` | Checked; `valid` says the outcome. | | `400` | No `path`. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No catalogued bundle has that path, or its file is no longer on disk. | | `500` | The bundle could not be read. | CLI: `crewship backup verify `, with the same fallback as inspect. ## `GET /api/v1/admin/instance/backups/bundles/download` The bytes of one catalogued bundle of any scope, as stored (encrypted, as every new bundle is), as `application/zstd` with `Content-Disposition: attachment`, `Cache-Control: no-store` and `Content-Length`. The download is recorded in the instance audit log (`instance.backup_downloaded`, with the bytes sent). Backup history's **Download** uses this route for an instance bundle. **Auth:** instance administrator. **Request:** no body. **Response:** the bundle file. | Status | Condition | | - | - | | `200` | The bundle's bytes. | | `400` | No `path`. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No catalogued bundle has that path, or its file is no longer on disk. | | `500` | The file could not be read. | CLI: `crewship backup download [--out file]`, with the same fallback as inspect. ## `GET /api/v1/admin/instance/backups/restores` Every restore, dry run and drill the server has run, newest first, with the full report the restore returned at the time. `kind` is `restore`, `dry_run` or `drill`. `result` is `ok`, `partial` — the restore landed, but its report names something skipped, missing or lowered (crew files not landed, credential tiers clamped, columns dropped, row counts short, attachment files missing or in conflict, or a gap the bundle itself recorded) — or `failed`, whose report carries the `error`. `?limit=N` returns at most N rows (default 100, at most 500\). **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "restores": [ { "id": "rr_…", "kind": "dry_run", "actor_user_id": "user-cuid", "actor_email": "ops@example.com", "bundle_path": "/var/lib/crewship/backups/crewship-workspace-lab-20260930T020000Z.tar.zst", "target": "lab", "result": "partial", "report": {"rows_inserted": 412, "attachments_missing": 2, "incomplete": [ … ]}, "created_at": "2026-09-30T08:12:44.123Z" } ] } ``` | Status | Condition | | - | - | | `200` | The list. | | `400` | `limit` is not 1–500. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `GET /api/v1/admin/instance/backups/plans` Every backup plan, by name. A plan says what goes in (`preset`, `scope`, `workspace_ids`, `contents`, `env_mode`), when (`cadence`, `time_of_day`, `weekday`, `monthday`, `cron_expr` in `timezone`; `env_cadence` picks the runs that also take complete environments), for how long (`keep_min`, the newest copies no rule ages out, and `keep_daily`, `keep_weekly`, `keep_monthly`), who can open its bundles (`recipient_ids`) and how long a run waits for busy workspaces (`busy_wait_minutes`, looking again every `busy_retry_minutes`). `counts_as_protection` is false for custom plans. Plans run on the server's backup scheduler, never through an agent. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "data": [ { "id": "bp_…", "name": "Nightly", "preset": "workspace", "scope": "workspaces", "workspace_ids": ["ws-cuid"], "contents": [], "env_mode": "files", "cadence": "daily", "time_of_day": "03:00", "weekday": null, "monthday": null, "cron_expr": null, "timezone": "Europe/Prague", "env_cadence": "weekly", "keep_min": 3, "keep_daily": 7, "keep_weekly": 4, "keep_monthly": 12, "destinations": ["local"], "recipient_ids": ["age1…"], "busy_wait_minutes": 120, "busy_retry_minutes": 15, "hold_cap_minutes": 20, "stale_alert_hours": 36, "enabled": true, "next_run_at": "2026-10-01T01:00:00Z", "last_run_at": null, "counts_as_protection": true, "created_at": "2026-09-30T10:00:00Z", "updated_at": "2026-09-30T10:00:00Z" } ] } ``` | Status | Condition | | - | - | | `200` | The list. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `POST /api/v1/admin/instance/backups/plans` Creates a plan. The body is a plan without `id`, `next_run_at` and `last_run_at`; every field it leaves out takes the preset's default. `complete` covers the whole instance with data daily at 03:00 and complete environments weekly; `workspace` covers the listed workspaces (none listed: every workspace) with every category; `custom` carries only `contents` plus what those need (see preview-contents). `workspace_ids` takes ids or slugs. `timezone` must be an IANA zone, `cron_expr` a five-field cron expression (parsed like routine schedules), `keep_min` at least 1, and `recipient_ids` must name at least one age public key or recipient: every backup is encrypted. Written to the instance audit log in the same transaction. **Auth:** instance administrator. **Request:** ```json theme={null} {"preset": "custom", "name": "Memory every 6 h", "contents": ["memory"], "cadence": "custom", "cron_expr": "0 */6 * * *", "timezone": "Europe/Prague", "recipient_ids": ["age1…"]} ``` **Response:** the stored plan, as in the list. | Status | Condition | | - | - | | `201` | Created. | | `400` | Invalid JSON, an unknown workspace or category, a bad timezone, cron or time, `keep_min` below 1, or no recipients. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `413` | The request body is over 1 MiB (`"code": "body_too_large"`); a declared length over 16 MiB returns Problem Details without `code`. | | `500` | The write failed; nothing changed. | ## `POST /api/v1/admin/instance/backups/plans/preview-contents` What a plan's bundles would carry. `included` is what the plan chooses (a preset other than custom: every category; complete environments follow `env_mode`), `required` what is kept because an included category cannot be restored without it, with the categories that need it, and `excluded` the rest. The console shows the same rule while a plan is edited. **Auth:** instance administrator. **Request:** ```json theme={null} {"preset": "custom", "contents": ["memory"], "env_mode": "files"} ``` **Response:** ```json theme={null} { "included": ["memory"], "required": [{"key": "agents", "because": ["memory"]}], "excluded": ["chats", "att", "routines", "journal", "creds", "pages", "files", "env"] } ``` | Status | Condition | | - | - | | `200` | The resolution. | | `400` | Invalid JSON, an unknown preset, category or `env_mode`. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | ## `GET /api/v1/admin/instance/backups/plans/{id}` One plan, as in the list. **Auth:** instance administrator. **Request:** no body. **Response:** the plan. | Status | Condition | | - | - | | `200` | The plan. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No plan with that id. | | `500` | A read failed. | ## `PUT /api/v1/admin/instance/backups/plans/{id}` Changes a plan. Fields the body leaves out keep their stored value; the same rules as create apply, and `next_run_at` is recomputed from now. Written to the instance audit log, with the plan before the change, in the same transaction. **Auth:** instance administrator. **Request:** ```json theme={null} {"cadence": "weekly", "weekday": 0, "env_mode": "complete"} ``` **Response:** the stored plan. | Status | Condition | | - | - | | `200` | Updated. | | `400` | Invalid JSON or a value create would refuse. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No plan with that id. | | `413` | The request body is over 1 MiB (`"code": "body_too_large"`); a declared length over 16 MiB returns Problem Details without `code`. | | `500` | The write failed; nothing changed. | ## `DELETE /api/v1/admin/instance/backups/plans/{id}` Deletes a plan. Its bundles and its run history stay. Written to the instance audit log in the same transaction. **Auth:** instance administrator. **Request:** no body. **Response:** no body. | Status | Condition | | - | - | | `204` | Deleted. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No plan with that id. | | `500` | The write failed; nothing changed. | ## `GET /api/v1/admin/instance/backups/plans/{id}/next` The plan's next `n` run times (default 5, at most 50) after now, and whether each also takes complete environments. Empty for a switched-off plan. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} {"runs": [{"at": "2026-10-03T01:00:00Z", "environments": false}, {"at": "2026-10-04T01:00:00Z", "environments": true}]} ``` | Status | Condition | | - | - | | `200` | The run times. | | `400` | `n` is not 1–50. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No plan with that id. | | `500` | A read failed. | ## `GET /api/v1/admin/instance/backups/plans/{id}/calendar` Day by day from `from` to `to` (`YYYY-MM-DD` in the plan's timezone; by default the last 7 and the next 28 days, at most 400): the plan's runs as `done`, `skipped`, `catchup` or `failed`, and its due times after now as `planned`. Runs of one due time over several workspaces fold into one entry with the worst status. `kind` is `data` or `environments`; environments entries of past runs read `skipped` until complete environments are captured. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} {"days": [{"date": "2026-10-04", "entries": [{"at": "2026-10-04T01:00:00Z", "kind": "data", "status": "planned"}, {"at": "2026-10-04T01:00:00Z", "kind": "environments", "status": "planned"}]}]} ``` | Status | Condition | | - | - | | `200` | The calendar. | | `400` | A date is not `YYYY-MM-DD`, `to` is before `from`, or the span is over 400 days. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No plan with that id. | | `500` | A read failed. | ## `GET /api/v1/admin/instance/backups/runs` Backup runs, newest first, each with its persisted phases (`wait` while busy workspaces were waited out, then `copy`, `pack`, `encrypt`, `check` — the checksum of the written bundle — and `off-site`, `skipped` with "not configured" until off-site copies exist). `status` is `running`, `done`, `incomplete` (a bundle was written and its manifest names what it lacks, in `incomplete`), `failed`, `interrupted` (the server stopped during the run; it was retried once, and `retried_at` says when the retry finished) or `skipped` (busy past the plan's window, or scheduled backups were held: while an instance restore's `routines` or `all` hold is set, scheduled and catch-up runs are recorded as skipped with the reason until an admin resumes it; manual runs still start). `trigger` is `schedule`, `manual` or `catchup`. `hold_ms` is how long writes were held for the consistent copy of an instance run (`null` for workspace runs, which hold no instance-wide window). The bundle's `proof_level`, `pinned`, `drill_*`, `format_version` and `restorable` come from the catalog. Narrow with `plan`, `scope` (`instance` or `workspaces`), `ws` (workspace ids or slugs, comma-separated) and `limit` (default 100, at most 500). **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "data": [ { "id": "br_…", "plan_id": "bp_…", "plan_name": "Nightly", "trigger": "schedule", "note": null, "scope": "workspaces", "workspace_id": "ws-cuid", "workspace_name": "Lab", "kind": "full", "status": "incomplete", "retried_at": null, "phases": [{"name": "copy", "started_at": "2026-10-01T01:00:02Z", "ended_at": "2026-10-01T01:06:40Z", "status": "done", "detail": null}], "bundle_path": "/var/lib/crewship/backups/crewship-workspace-lab-20261001T010002Z.tar.zst", "size_bytes": 38000000, "error": null, "incomplete": [{"kind": "attachment_missing", "count": 3, "workspace_id": "ws-cuid", "detail": "…"}], "started_at": "2026-10-01T01:00:00Z", "ended_at": "2026-10-01T01:21:00Z", "proof_level": 1, "drill_result": null, "drill_at": null, "drill_note": null, "pinned": false, "recipients": ["age1q7x…m3k"], "format_version": 3, "restorable": "direct", "legacy": false, "phase": "", "environments": false, "due_at": "2026-10-01T01:00:00Z", "retry_of": null, "categories": [], "catalog_id": "bk_…", "hold_ms": null } ] } ``` | Status | Condition | | - | - | | `200` | The runs. | | `400` | `scope` is not `instance` or `workspaces`, or `limit` is not 1–500. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | A workspace in `ws` does not exist. | | `500` | A read failed. | ## `POST /api/v1/admin/instance/backups/run` Starts a backup now and answers at once. Every run — scheduled, catch-up or manual, instance or workspace — is a row of the server's backup service (never an agent), so a client that disconnects, or the CLI's 30-second timeout, cannot cancel it; follow it with [`GET …/backups/run/{runId}`](#get-api-v1-admin-instance-backups-run-runid). * With `plan_id`, runs that plan now (one run per workspace for a workspaces plan). * Without it, `scope` says what to back up. `instance` writes one instance bundle: the whole database, every file store and every crew container, copied in one quiet window — running work is drained first, then every write to protected data is held for the copy only (at most the plan's `hold_cap_minutes`, 20 by default) and released before packing and encryption. `workspaces` writes one bundle per workspace in `workspace_ids` (ids or slugs; default every workspace), with `preset`, `contents` and `env_mode` choosing what goes in. Without `preset`, an instance run is `complete` and a workspaces run `workspace`. Every backup is encrypted. Give `recipient_ids` (age `age1…` public keys or recipient ids; `recipients` is accepted as another name) or `passphrase`, not both. Without either, the recipients of the enabled plan covering the scope are used; with `plan_id`, keys given in the request replace the plan's for this run. A passphrase is held in the server's memory until the run starts and is never stored or logged: a run whose server restarts before it starts fails and says so. When the vault keys' recovery kit is on, instance bundles carry them. `note` is shown with the run. Written to the instance audit log (the passphrase only as `passphrase: true`). **Auth:** instance administrator. **Request:** ```json theme={null} {"scope": "instance", "recipient_ids": ["age1q7x…m3k"], "note": "before upgrade"} ``` **Response** — `id` and `run_id` name the first run, `run_ids` every run queued: ```json theme={null} {"id": "br_…", "run_id": "br_…", "run_ids": ["br_…"], "status": "running"} ``` | Status | Condition | | - | - | | `202` | Queued. | | `400` | Invalid JSON, `scope` is not `instance` or `workspaces`, both recipients and a passphrase, a recipient that is not an age key or known recipient id, no workspace to back up, or nothing to encrypt to. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No plan with that id, or an unknown workspace. | | `500` | The run could not be queued. | ## `GET /api/v1/admin/instance/backups/overview` Whether a restore would work, for `scope=instance` (the default) or `scope=workspaces` narrowed by `ws` (ids or slugs; `none` selects nothing). `status.verdict` is the weakest proof among the latest full bundles of the selection — `verified` (a test restore went through), `partial` (a test restore or the bundle found gaps), `failed`, `contents_checked`, `checksum_only` or `none`; custom bundles never count, and an instance selection counts only instance bundles. The status rows say what is protected, how often, where, for how long and when it was really restored; `offsite_verified` stays false until an off-site copy has been uploaded and checked. `needs_attention` lists concrete problems: the latest bundle's gaps per workspace, workspaces never or not recently backed up, workspaces on no plan, and failed, skipped or late runs. For `scope=instance` it also says when the latest instance bundle cannot unlock credentials on a new server (`id` `vault`): the key versions its sealed values use that its recovery kit does not carry — all of them when the kit was off — read from the bundle's own manifest. When the next run would be refused for lack of disk space it lists `id` `space` first (severity `bad`, action `storage`), whose detail gives the figures and what to do. `nights` is always fourteen entries ending today in the plan's timezone. `space.staging_need_bytes` is the largest recent bundle × 1.1 and `space.restore_need_bytes` the largest bundle × 3 (payloads compress about 3:1 and a restore stages the decrypted payload). `space.min_free_percent` is the space floor in force (`CREWSHIP_BACKUP_MIN_FREE_PERCENT`, default 10) and `space.refusal` why the next run would not start, or `null`. `workspaces` is present for `scope=workspaces`. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "status": { "label": "Nightly", "verdict": "checksum_only", "summary": null, "protects": {"value": "1 of 1 workspaces on a plan", "detail": null, "detail_tone": null}, "how_often": {"value": "daily 03:00", "detail": "Europe/Prague · next 1 Oct 03:00", "detail_tone": null}, "where": {"value": "This server (/var/lib/crewship/backups)", "detail": "no off-site copy", "detail_tone": "warn"}, "how_long": {"value": "keep 3 checked, 7 daily, 4 weekly, 12 monthly", "detail": "the newest copies are never aged out", "detail_tone": null}, "really_restored": {"value": "Never test-restored", "detail": "a checksum is not a restore", "detail_tone": "warn"}, "offsite_verified": false }, "needs_attention": [{"id": "run:br_…", "severity": "warn", "title": "Backup of Lab skipped on 29 Sep 03:00", "detail": "skipped: still busy after 120 minutes (2 agent(s) working)", "action": {"kind": "history", "label": "View run", "workspace_id": "ws-cuid", "run_id": "br_…"}}], "nights": [{"date": "2026-09-30", "status": "ok", "proof": 1, "detail": null}], "space": {"backups_bytes": 38000000, "free_bytes": 120000000000, "total_bytes": 500000000000, "staging_need_bytes": 41800000, "restore_need_bytes": 114000000, "min_free_percent": 10, "refusal": null}, "workspaces": [{"workspace_id": "ws-cuid", "name": "Lab", "last_backup_at": "2026-09-30T01:00:00Z", "status": "ok", "plan": "Nightly", "proof": 1}], "instance_summary": "2 workspaces, 3 users, instance settings" } ``` | Status | Condition | | - | - | | `200` | The overview. | | `400` | `scope` is not `instance` or `workspaces`. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | A workspace in `ws` does not exist. | | `500` | A read failed. | ## `GET /api/v1/admin/instance/backups/run/{runId}` One run, in the same shape as an item of [`GET …/backups/runs`](#get-api-v1-admin-instance-backups-runs): `status` (`running` until it ends), the phases, the bundle it wrote (`bundle_path`, `size_bytes`, `proof_level`), how long writes were held (`hold_ms`) and every gap (`incomplete`). Runs are durable: they survive a restart, and a run the server stopped during is marked `interrupted` and retried once. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "id": "br_…", "plan_id": null, "plan_name": null, "trigger": "manual", "note": "before upgrade", "scope": "instance", "workspace_id": null, "workspace_name": null, "kind": "full", "status": "done", "phases": [{"name": "copy", "started_at": "2026-09-30T03:00:01Z", "ended_at": "2026-09-30T03:00:49Z", "status": "done", "detail": null}], "bundle_path": "/var/lib/crewship/backups/crewship-instance-all-20260930T030000Z.tar.zst", "size_bytes": 81234567, "error": null, "incomplete": [], "started_at": "2026-09-30T03:00:00Z", "ended_at": "2026-09-30T03:04:12Z", "proof_level": 1, "pinned": false, "recipients": ["age1q7x…m3k"], "legacy": false, "hold_ms": 48210 } ``` | Status | Condition | | - | - | | `200` | The run. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No run with that id. | | `500` | A read failed. | ## `GET /api/v1/admin/instance/backups/vault-keys` The vault key versions a restore needs: every version the database's sealed values (credentials, webhook secrets, integration keys) reference or this server has configured, the environment variable each is read from, how many sealed values use it, whether it mints new ones (`active`) and whether this server has a key for it (`present`, following the same `ENCRYPTION_KEY` fallback decryption applies). `recovery_kit.enabled` says whether new instance bundles carry the keys; `available` whether every referenced version could be carried. Counts only: no key material leaves the server. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "versions": [ {"version": "v1", "env": "ENCRYPTION_KEY", "active": false, "envelopes": 12, "present": true}, {"version": "v2", "env": "ENCRYPTION_KEY_V2", "active": true, "envelopes": 40, "present": true} ], "recovery_kit": {"available": true, "enabled": false} } ``` | Status | Condition | | - | - | | `200` | The versions. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `PUT /api/v1/admin/instance/backups/settings/recovery-kit` Turns the recovery kit on or off for new instance bundles. On, every key version the database references rides inside the encrypted payload of each instance bundle (never a workspace or crew bundle), so `crewship recover` can hand them to the restored server. Whoever holds a private key a bundle is encrypted to can then read every secret in it. The change and its instance audit entry (`instance.backup_recovery_kit_enabled` / `_disabled`) commit together. **Auth:** instance administrator. **Request:** ```json theme={null} {"enabled": true} ``` **Response:** ```json theme={null} {"enabled": true} ``` | Status | Condition | | - | - | | `200` | Saved. | | `400` | No `enabled`, or the body is not JSON. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | The write failed; nothing changed. | ## `POST /api/v1/admin/instance/backups/bundles/check` Proof level 2 — contents checked. Decrypts a catalogued bundle with the key given (`identity`: the text of an age identity file, or `passphrase`), reads every section to the end, and compares table row counts and file digests with the manifest. Nothing is restored, and the key is used for this request only: never stored, never logged. On success the bundle's proof level rises to 2; a failed check lowers a bundle recorded at 2 back to 1. `absent` repeats what the bundle itself recorded as missing (attachment files, memory blobs, crew containers). Recorded in the instance audit log (`instance.backup_contents_checked`). **Auth:** instance administrator. **Request:** ```json theme={null} {"path": "/var/lib/crewship/backups/crewship-instance-all-20260930T030000Z.tar.zst", "identity": "AGE-SECRET-KEY-1…"} ``` **Response:** ```json theme={null} { "ok": true, "proof_level": 2, "detail": "every section read (412 entries); 231 table(s) and 398 file(s) match the manifest", "problems": [], "absent": [], "entries": 412, "tables": 231, "files": 398 } ``` | Status | Condition | | - | - | | `200` | The check ran; `ok` says whether it passed. | | `400` | No `path`, no key for an encrypted bundle, both keys, or an identity that is not an age secret key. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No catalogued bundle has that path, or its file is gone. | | `422` | The key does not open the bundle. | | `500` | The check could not run. | ## `POST /api/v1/admin/instance/backups/restore/checks` The checks a restore runs before anything changes. `space`: room on the data directory (an instance bundle records exactly what it lands). `format`: the bundle's format version, and whether this server reads it directly or through a converter. `runtime`: whether Docker answers; a crew built on another architecture gets a warning that its environment is rebuilt from the crew image. `runtime.images_checked` / `runtime.images_older`: how many of the archive's crews pinned a runtime image digest this server could compare with the image it holds now, and how many of those were built on a different one (each also a runtime warning); `0` checked says nothing either way, e.g. the archive predates digest pinning or the image is not pulled here. `unsafe`: host settings in the crews' devcontainer configuration that a restore does not switch back on by itself — Docker socket mounts, privileged mode, host path binds; read only when a key is given, otherwise a runtime warning says they were not checked. `conflicts`: what the `target` (`empty_server`, `isolated`, `replace`, `new_workspace`, `crew`, `in_place`) already holds, decided by the same rule the restore applies, so a target that passes here is never refused by the restore: an instance bundle restores only to `empty_server` (`crewship recover`) or `isolated` (`crewship backup drill`), and those two take nothing else; `replace` needs a workspace bundle that is not custom (a partial bundle would delete what it does not carry); `new_workspace` needs a workspace bundle and `crew` a crew bundle, each with the new name in `as_workspace` / `as_crew` — a valid slug that no workspace on this server holds, deleted workspaces included (the slug stays reserved). The restore itself answers `409` for a taken name. `in_place` restores a workspace or crew bundle under its own names (no replace, no new name); an instance bundle is refused. `environments`: one runtime check per complete container environment the bundle carries — `action` is `restore`, `rebuild` (built for another architecture than this server's Docker, or `missing_blobs` of its layers are neither in the bundle nor in the store beside it: the data comes back, the environment is rebuilt from the crew image) or `skip` (no Docker); `runtime.detail` then names the Docker version and platform, each rebuild is also a runtime warning, the layers' bytes count toward `space`, and with a key `unsafe` also lists the recorded host settings of each environment. Always an array. **Auth:** instance administrator. **Request:** ```json theme={null} {"path": "/var/lib/crewship/backups/crewship-workspace-lab-20260930T020000Z.tar.zst", "target": "new_workspace", "as_workspace": "lab-restored", "identity": "AGE-SECRET-KEY-1…"} ``` **Response:** ```json theme={null} { "space": {"ok": true, "need_bytes": 245000000, "free_bytes": 81000000000}, "format": {"ok": true, "version": 3, "converter": false}, "runtime": {"ok": true, "detail": "Docker is available on this server (linux/amd64)", "warnings": []}, "unsafe": ["Docker socket mount on ops"], "conflicts": {"ok": true, "detail": "replaces workspace lab on this server; its current data is overwritten"}, "environments": [ {"crew": "ops", "action": "restore", "platform": "linux/amd64", "host_platform": "linux/amd64", "missing_blobs": 0, "need_bytes": 1450000000, "detail": "linux/amd64, 1.4 GiB of image layers"} ] } ``` | Status | Condition | | - | - | | `200` | The checks. | | `400` | Unknown `target`, no `path`, both keys, or a bad identity. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No catalogued bundle has that path, or its file is gone. | | `422` | The bundle cannot be read, or the key does not open it. | | `500` | A check could not run. | ## `POST /api/v1/admin/instance/backups/environments/land` Loads the complete container environments `crewship recover` staged under `/restore-staging/environments/` (each workspace's records, and the image layers copied beside them), once the recovered server runs with Docker. Each image is reassembled and loaded; a Crewship crew's image gets its crew image tag back when the server has none, so Crewship recreates the crew from the captured environment with the runtime settings it manages. A container Crewship does not manage is recreated with its sanitized configuration and its mounts' content, then started. Settings recorded as not carried over for safety stay off. Every environment is reported with `result` `restored`, `rebuilt` (another architecture or missing layers) or `skipped` (no Docker, or an error) and its `reason`; `staged` is false when nothing was staged. `dry_run` checks only. The work runs on its own 30 minute deadline, so a client that gives up does not stop it halfway. A landing (not a dry run) is written to `landed.json` beside the staged files and recorded in the instance audit log (`instance.environments_landed`). **Auth:** instance administrator. **Request** (optional body): ```json theme={null} {"dry_run": false} ``` **Response:** ```json theme={null} { "dir": "/var/lib/crewship/restore-staging/environments", "staged": true, "dry_run": false, "environments": [ {"workspace": "ws_lab", "crew": "ops", "result": "restored", "image": "crewship-env/ops:20260930t030000-1a2b3c", "unsafe": ["Docker socket mount on ops"], "notes": ["processes start fresh: what was only in memory is not restored"]}, {"workspace": "ws_lab", "crew": "researcher", "result": "rebuilt", "reason": "built for linux/arm64 and this server is linux/amd64: its data comes back, its environment is rebuilt from the crew image", "unsafe": []} ] } ``` | Status | Condition | | - | - | | `200` | The landing report. | | `400` | The body is not valid JSON. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | The staged files could not be read. | ## `POST /api/v1/admin/instance/backups/bundles/upload` **Auth:** instance administrator, with or without workspace membership. **Request:** encrypted `.tar.zst` archive bytes, `Content-Type: application/octet-stream` or `application/zstd`, up to 64 GiB. No private key, destination path or workspace parameter is accepted. One upload per server process is admitted at a time. **Response** (`201`): ```json theme={null} {"path":"/backups/uploaded-sha256.tar.zst","scope":"instance","size_bytes":513000000,"format_version":4,"proof_level":1,"duplicate":false,"conversion_required":false} ``` Proof level 1 confirms the encrypted payload checksum, not decryptability or successful recovery. Duplicate bytes preserve the catalog's existing proof. Publication, catalog and audit either commit together or the owned file is removed. Interrupted uploads remove staging; staging left by a crash or restart is removed on the next start. The upload is not bound by the server's request read timeout, but one that sends nothing for 2 minutes ends as interrupted. No restore is started. | Status | Condition | | - | - | | `201` | Validated encrypted archive catalogued and audited. | | `400` | Interrupted upload, or no bytes received for 2 minutes. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `409` | Another upload is in progress. | | `413` | Archive exceeds 64 GiB. | | `415` | Unsupported content type. | | `422` | Invalid, unencrypted, corrupted or unsupported archive. | | `507` | Insufficient free space. | | `500` | File, catalog or audit failure. | ## `POST /api/v1/admin/instance/backups/services/land` Imports the verified quota-service disk images that offline `crewship recover` staged under the configured data directory's `restore-staging/services`. The client cannot choose a host path, helper namespace or generation. The recovered database contains fresh generations and persistent maintenance; the server checks image checksums, exact declarations, intent revisions and fence ownership before import through its configured host quota helper. **Auth:** instance administrator, including one without workspace membership. **Request** (optional body): ```json theme={null} {"dry_run": false} ``` **Response:** ```json theme={null} {"images": 2, "dry_run": false} ``` A dry run verifies without importing or releasing maintenance. An actual landing holds producer leases and commits maintenance release and `instance.services_landed` audit together. Failure keeps services in maintenance, including when an image was already imported before the failure. After the producer lease expires, retry checks an already imported image with an exact offline export before accepting it. Work has a 30-minute deadline. | Status | Condition | | - | - | | `200` | All staged images verified (dry run) or imported and audited. | | `400` | Invalid JSON body. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `503` | Recovered data directory is not configured. | | `500` | Staging, binding, helper, producer lease or audit failure; maintenance stays. | ## `POST /api/v1/admin/instance/backups/drills` Records a test restore run offline by `crewship backup drill --post`. The bundle must be catalogued at `path`, and `sha256` must be its payload digest — a drill of a different file is refused. `result` is `ok`, `partial` or `failed`; `report` is the drill's full report (its checks and what failed). An `ok` or `partial` drill raises the bundle to proof level 3 — a partial one stays shown as partial — and every drill is written to the restore history as kind `drill`. Recorded in the instance audit log (`instance.backup_drill_recorded`). **Auth:** instance administrator. **Request:** ```json theme={null} { "path": "/var/lib/crewship/backups/crewship-instance-all-20260930T030000Z.tar.zst", "sha256": "9f2c…", "result": "partial", "report": {"result": "partial", "checks": [{"name": "credentials_unlock", "status": "skipped", "detail": "…"}]} } ``` **Response** (`201`): ```json theme={null} {"path": "/var/lib/crewship/backups/crewship-instance-all-20260930T030000Z.tar.zst", "proof_level": 3, "drill_result": "partial", "drill_at": "2026-09-30T09:12:00Z", "report_id": "rr_…"} ``` | Status | Condition | | - | - | | `201` | Recorded. | | `400` | `result` is not ok, partial or failed, or `report` is not JSON. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No catalogued bundle has that path. | | `409` | `sha256` does not match the catalogued bundle. | | `500` | The write failed. | ## `GET /api/v1/admin/instance/backups/drills` Every recorded drill, newest first, as an array. `source_scope` is `instance` or `workspaces`; `warnings` counts the checks that did not pass plus the gaps the restore recorded. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} [ { "id": "rr_…", "kind": "drill", "actor": "ops@example.com", "bundle_path": "/var/lib/crewship/backups/crewship-instance-all-20260930T030000Z.tar.zst", "source_scope": "instance", "source_name": "Whole instance", "source_date": "2026-09-30T03:00:00Z", "target": "isolated", "result": "ok", "warnings": 0, "created_at": "2026-09-30T09:12:00Z" } ] ``` | Status | Condition | | - | - | | `200` | The list. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `GET /api/v1/admin/instance/backups/settings` The instance-wide backup settings. `limits`: how many runs execute at once (the rest queue), the CPU cores the compressor may use, and MB/s caps on writing staging and bundle files and on off-site uploads (0 is no cap; each cap is one limiter shared by every run). `heartbeat_url` is pinged after every good run, and `heartbeat_last_*` says how the last ping went. `events` says which incident kinds reach the instance admins, `stale_alert_hours` after how long without a good backup a plan counts as stale. `drill_reminder` (`weekly`, `monthly` or `off`) raises an instance-wide `drill` incident when the newest test restore is older than 7 or 31 days. Incidents go to each instance admin's inbox and from there to that admin's own notification channels (the `system.health` category), and to every notification channel whose id is in `channels` — one message per incident state change (opened, each repeat, resolved). `available_channels` lists the channels that can be added (workspace-wide, switched on, admitting System health, on a provider switched on in Admin › Notifications) with `kind` `chat`, `push`, `incident`, `email` or `webhook` and the newest backup alert each was sent; `channel_status` says, per channel in `channels`, whether it is still available and how its newest alert went (`pending`, `sent` or `failed` with the error). `destinations` lists where copies can be kept: this server, each S3-compatible destination (`verified` once one upload there was checked), and Google Drive as not yet `available`. `instance_admins` counts who receives incidents. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "limits": {"concurrency": 1, "cpu_cores": 2, "disk_mbps": 80, "upload_mbps": 20}, "heartbeat_url": "https://hc.example.com/ping/5c3e…", "heartbeat_last_at": "2026-09-30T03:04:10Z", "heartbeat_last_ok": true, "heartbeat_last_error": null, "recovery_kit_enabled": false, "channels": [], "events": {"failed": true, "incomplete": true, "stale": true, "offsite": true, "drill": true}, "stale_alert_hours": 36, "drill_reminder": "monthly", "updated_at": "2026-09-30T08:00:00Z", "destinations": [ {"id": "local", "kind": "local", "label": "This server", "path": "/var/lib/crewship/backups", "used_bytes": 27917287424, "verified": true, "available": true}, {"id": "bdst_…", "kind": "s3", "label": "r2", "path": null, "used_bytes": 9126805504, "verified": true, "available": true}, {"id": "drive", "kind": "drive", "label": "Google Drive", "path": null, "used_bytes": null, "verified": false, "available": false} ], "instance_admins": 3, "local_path": "/var/lib/crewship/backups", "available_channels": [ {"id": "nch_1a2b3c4d5e6f7a8b", "name": "Slack · Platform", "kind": "chat", "provider": "slack", "workspace_id": "ws_…", "workspace_name": "Platform", "last_delivery": {"status": "sent", "error": null, "at": "2026-09-30T03:05:00Z", "incident_id": "bin_…"}} ], "channel_status": [] } ``` | Status | Condition | | - | - | | `200` | The settings. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `PUT /api/v1/admin/instance/backups/settings` Changes the settings. The body is a partial settings object: what it leaves out keeps its value; `destinations`, `instance_admins`, `local_path` and the heartbeat's last ping are ignored. `heartbeat_url` must be a public https URL; `null` or `""` clears it. A channel id added to `channels` must be one of `available_channels`; one already there stays even if it has since become unusable (its alerts then fail and say why). The change and its instance audit entry (`instance.backup_settings_updated`, before and after) commit together. Answers with the whole settings object. **Auth:** instance administrator. **Request:** ```json theme={null} {"limits": {"disk_mbps": 80, "upload_mbps": 20}, "events": {"failed": true, "incomplete": false, "stale": true, "offsite": true, "drill": true}} ``` **Response:** the whole settings object, in the shape `GET` answers. ```json theme={null} {"limits": {"concurrency": 1, "cpu_cores": 2, "disk_mbps": 80, "upload_mbps": 20}, "heartbeat_url": null, "recovery_kit_enabled": false, "channels": [], "events": {"failed": true, "incomplete": false, "stale": true, "offsite": true, "drill": true}, "stale_alert_hours": 36, "drill_reminder": "monthly", "destinations": [], "instance_admins": 3, "local_path": "/var/lib/crewship/backups"} ``` | Status | Condition | | - | - | | `200` | Saved. | | `400` | A limit out of range, a heartbeat URL that is not public https, an unknown drill reminder, a channel being added that is unknown or cannot carry backup alerts, or a body that is not JSON. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `413` | The request body is over 1 MiB (`"code": "body_too_large"`); a declared length over 16 MiB returns Problem Details without `code`. | | `500` | The write failed; nothing changed. | ## `POST /api/v1/admin/instance/backups/settings/test-alert` Sends a test alert ("Backup alert test", with a link to Backups › Overview) to one notification channel now, through the same delivery a real backup alert uses — the channel's sealed secret, the SSRF-safe transport and the provider kill switch — and says whether it arrived. The channel need not be in `channels` yet. A failed send is `200` with `ok: false` and the error. Test alerts are not written to the notification delivery log. **Auth:** instance administrator. **Request:** ```json theme={null} {"channel_id": "nch_1a2b3c4d5e6f7a8b"} ``` **Response:** ```json theme={null} {"ok": true, "channel_id": "nch_1a2b3c4d5e6f7a8b", "channel": "Slack · Platform", "error": null, "sent_at": "2026-09-30T09:12:00Z"} ``` | Status | Condition | | - | - | | `200` | Sent, or not delivered (`ok: false` with the error). | | `400` | No `channel_id`, a channel that cannot carry backup alerts (the reason is in the error), or a body that is not JSON. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No notification channel with that id (unknown, deleted or personal). | | `500` | A read failed. | ## `GET /api/v1/admin/instance/backups/recipients` The backup keys: age public keys backups are encrypted to, who holds each private half, a fingerprint for the printed recovery sheet, and the plans that use each key (by id or by the raw `age1…` key). The private halves never reach the server. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "data": [ {"id": "brk_…", "name": "ops-2026", "public_key": "age1q7x…m3k", "holder": "platform lead", "fingerprint": "SHA256:1a2b3c4d5e6f7a8b", "created_by": "usr_…", "created_at": "2026-09-30T08:00:00Z", "used_by": ["Complete recovery"]} ] } ``` | Status | Condition | | - | - | | `200` | The list. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `POST /api/v1/admin/instance/backups/recipients` Adds a backup key. `public_key` must be an age X25519 public key (`age1…`); a private key (`AGE-SECRET-KEY-1…`) is refused. Plans name the key by its id in `recipient_ids`. Audited as `instance.backup_recipient_added`. **Auth:** instance administrator. **Request:** ```json theme={null} {"name": "ops-2026", "public_key": "age1q7x…m3k", "holder": "platform lead"} ``` **Response:** `201` with the key, as in the list. | Status | Condition | | - | - | | `201` | Added. | | `400` | No name, or not an age public key. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `409` | The same public key is already a backup key. | | `500` | The write failed. | ## `DELETE /api/v1/admin/instance/backups/recipients/{id}` Removes a backup key. Refused while a plan still encrypts to it — change the plan first, so no plan is left encrypting to nobody. Backups already made stay readable with the key's private half. Audited as `instance.backup_recipient_removed`. **Auth:** instance administrator. **Request:** no body. **Response:** `204`. | Status | Condition | | - | - | | `204` | Removed. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No backup key with that id. | | `409` | A plan still uses the key; the message names it. | | `500` | The write failed. | ## `GET /api/v1/admin/instance/backups/destinations` The off-site destinations: endpoint, bucket and prefix, the last connection test, how many bundles have a verified copy there and their size, the plans that copy there, and what proved the newest copy's stored bytes (`last_verified_by`: `provider_checksum` — the store's own SHA-256 checksum of the object matched — or `download_rehash` — the copy was downloaded and re-hashed; `""` for a copy recorded before this was kept). The secret access key is never returned. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "data": [ {"id": "bdst_…", "name": "r2", "kind": "s3", "endpoint": "https://acct.r2.cloudflarestorage.com", "region": "auto", "bucket": "crewship-backups", "prefix": "prod", "access_key_id": "…", "path_style": false, "allow_private_network": false, "last_test_at": "2026-09-30T08:00:00Z", "last_test_error": null, "created_by": "usr_…", "created_at": "2026-09-30T08:00:00Z", "copies": 7, "copy_bytes": 9126805504, "last_verified_at": "2026-09-30T03:05:00Z", "last_verified_by": "provider_checksum", "used_by": ["Complete recovery"]} ] } ``` | Status | Condition | | - | - | | `200` | The list. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `POST /api/v1/admin/instance/backups/destinations` Adds an S3-compatible destination. The endpoint must be https and public; `allow_private_network: true` also allows loopback and private (LAN) addresses and plain http, and the answer then carries a `warning` — cloud metadata and link-local addresses stay blocked either way. Unless `skip_test`, the server first puts, reads back and deletes one small object; when that fails it answers `422` and stores nothing. The secret access key is sealed with the server's vault key and never returned, logged or audited. Audited as `instance.backup_destination_added`. A plan names the destination's id in `destinations` (after `local`, which every plan has); each bundle it writes is then uploaded and counted as an off-site copy only once the upload is verified at the destination. **Auth:** instance administrator. **Request:** ```json theme={null} {"name": "r2", "endpoint": "https://acct.r2.cloudflarestorage.com", "region": "auto", "bucket": "crewship-backups", "prefix": "prod", "access_key_id": "…", "secret_access_key": "…", "path_style": false, "allow_private_network": false} ``` **Response:** ```json theme={null} {"destination": {"id": "bdst_…", "name": "r2", "kind": "s3", "copies": 0, "used_by": []}, "test": {"ok": true, "error": null, "tested_at": "2026-09-30T08:00:00Z"}, "warning": null} ``` | Status | Condition | | - | - | | `201` | Added. | | `400` | Incomplete or refused configuration (endpoint, bucket name, keys). | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `409` | This server has no vault key to seal the secret with. | | `422` | The connection test failed; nothing was stored. | | `500` | The write failed. | ## `POST /api/v1/admin/instance/backups/destinations/{id}/test` Tests a stored destination again (put, read back, delete one small object) and stores the outcome. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} {"ok": false, "error": "offsite: connection test: upload: S3 PUT …: 403 AccessDenied", "tested_at": "2026-09-30T08:00:00Z"} ``` | Status | Condition | | - | - | | `200` | Tested; `ok` says how it went. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No destination with that id. | | `500` | A read failed. | ## `DELETE /api/v1/admin/instance/backups/destinations/{id}` Removes a destination and the server's records of the copies made there. The copies stay in the bucket. Refused while a plan copies there. Audited as `instance.backup_destination_removed`. **Auth:** instance administrator. **Request:** no body. **Response:** `204`. | Status | Condition | | - | - | | `204` | Removed. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No destination with that id. | | `409` | A plan still copies there; the message names it. | | `500` | The write failed. | ## `GET /api/v1/admin/instance/backups/incidents` Backup incidents, open ones first, newest first: one per plan and kind — `failed` (a run failed or was interrupted twice, or the plan's runs were skipped twice in a row — a single skip raises nothing), `incomplete` (a bundle with recorded gaps), `stale` (no good backup for longer than `stale_alert_hours`), `offsite` (an upload failed or did not verify), `drill` (a test restore failed or was partial). A repeat raises `count` and moves `last_at`; the next good run, or the condition clearing, resolves it. `plan_id` is null for runs made without a plan. Each incident is also an inbox item for every instance admin (see the backup guide). `?state=` is `open` or `resolved`; `?limit=` 1–500 (100 by default). **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} { "data": [ {"id": "bin_…", "plan_id": "bp_…", "plan_name": "Complete recovery", "kind": "failed", "state": "open", "count": 3, "first_at": "2026-09-28T03:00:20Z", "last_at": "2026-09-30T03:00:20Z", "resolved_at": null, "message": "Complete recovery backup failed. Last successful backup: 72 hours ago.", "run_id": "br_…"} ] } ``` | Status | Condition | | - | - | | `200` | The list. | | `400` | `state` or `limit` out of range. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `GET /api/v1/admin/instance/backups/recovery-sheet` A Markdown page (`text/markdown`, sent as a download) to keep off this server: where the bundles are (this server and every off-site destination), the backup keys' names, holders and fingerprints with their public keys, whether the vault keys ride in the recovery kit, the exact `crewship recover` and `crewship backup drill` commands for the newest instance bundle, the plans, and who the instance admins are. It holds no private key, vault key or password. **Auth:** instance administrator. **Request:** no body. **Response:** the Markdown text. | Status | Condition | | - | - | | `200` | The sheet. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `GET /api/v1/admin/instance/backups/copies` Restore from an off-site copy, step one: every bundle a destination holds — not its `.environments.json` refs objects or environment layers — and whether this server already has it (`local`, with `local_path`). `scope` and `workspace_id` are read from the key (`instance/…` or `workspaces//…`). `?destination=` is the destination id and is required. **Auth:** instance administrator. **Request:** query parameters only. **Response:** ```json theme={null} { "destination_id": "bdst_…", "destination_name": "r2", "copies": [ {"key": "instance/crewship-instance-20260929T010000Z.tar.zst", "size": 538181632, "modified": "2026-09-29T01:04:10Z", "scope": "instance", "workspace_id": null, "local": false, "local_path": null} ] } ``` | Status | Condition | | - | - | | `200` | The list. | | `400` | No `destination`. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No destination with that id. | | `502` | The destination could not be opened or listed; the message says why. | ## `POST /api/v1/admin/instance/backups/copies/fetch` Downloads one bundle, with every environment layer its refs object names, into this server's backups directory, each verified against its SHA-256, and records the layers as the bundle's so retention keeps them. The bundle is then an ordinary local bundle: restore a workspace from it, run a drill, or run `crewship recover` with it. A fetch can take far longer than one request may (the CLI gives up on a request after 30 seconds), so it runs as a job with its own six-hour deadline and the request answers `202` at once. Follow it with `GET …/copies/fetch/{id}`. The same destination and key while a fetch of it runs answers that job again. Jobs live in the server process: a restart forgets them, and a half-downloaded bundle never appears. Audited as `instance.backup_copy_fetched`. **Auth:** instance administrator. **Request:** ```json theme={null} {"destination_id": "bdst_…", "key": "instance/crewship-instance-20260929T010000Z.tar.zst"} ``` **Response:** the job (see the next section), `status` `running`. | Status | Condition | | - | - | | `202` | Started, or already running. | | `400` | No `destination_id`, or `key` is not a bundle (a refs object, a layer, a path escape). | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No destination with that id, or no object with that key there. | | `409` | The bundle is already on this server; `local_path` says where. | | `500` | The backups directory could not be resolved. | | `502` | The destination could not be reached. | ## `GET /api/v1/admin/instance/backups/copies/fetch/{id}` One off-site fetch: `running`, `done` (`path` is the local bundle, `size` its bytes, `layers` how many environment layers came with it) or `failed` (`error` says why; nothing partial is left behind). **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} {"id": "cm…", "destination_id": "bdst_…", "key": "instance/crewship-instance-20260929T010000Z.tar.zst", "status": "done", "path": "/var/lib/crewship/backups/crewship-instance-20260929T010000Z.tar.zst", "size": 538181632, "layers": 4, "error": null, "started_at": "2026-09-30T09:00:00Z", "ended_at": "2026-09-30T09:06:41Z"} ``` | Status | Condition | | - | - | | `200` | The job. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | No fetch with that id on this server (a restart forgets them). | ## `GET /api/v1/admin/instance/holds` The automations an instance restore left held, as an array. `routines`: schedules, routine schedules and recurring issues do not fire. `webhooks`: inbound webhooks answer `503`. `queue`: queued work, delayed routine runs and notification retries do not start. `all` holds all three. `count` and `detail` say what is held. **Auth:** instance administrator. **Request:** no body. **Response:** ```json theme={null} [ {"key": "queue", "reason": "instance restore", "count": 2, "detail": "2 queued work item(s) and 0 delayed routine run(s); notification retries paused", "created_at": "2026-09-30T09:40:00Z"}, {"key": "routines", "reason": "instance restore", "count": 14, "detail": "12 schedule(s) and 2 recurring issue(s) will not fire", "created_at": "2026-09-30T09:40:00Z"}, {"key": "webhooks", "reason": "instance restore", "count": 3, "detail": "3 inbound webhook(s) answer 503", "created_at": "2026-09-30T09:40:00Z"} ] ``` | Status | Condition | | - | - | | `200` | The holds (empty when nothing is held). | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `500` | A read failed. | ## `POST /api/v1/admin/instance/holds/resume` Resumes one held automation (`routines`, `webhooks`, `queue`, or `all`). It takes effect at once. The change and its instance audit entry (`instance.hold_resumed`) commit together. **Auth:** instance administrator. **Request:** ```json theme={null} {"key": "routines"} ``` **Response:** ```json theme={null} {"key": "routines", "resumed": true} ``` | Status | Condition | | - | - | | `200` | Resumed. | | `400` | `key` is not routines, webhooks, queue or all. | | `401` | Missing authentication. | | `403` | Caller is not an instance administrator. | | `404` | That automation is not held. | | `500` | The write failed; nothing changed. | ## Instance administration These routes require **ADMIN or OWNER** (`manage` permission). The mutation routes operate on instance or Docker state, although the caller must still have an authenticated workspace context. ## GET /api/v1/admin/health Returns process uptime, the current log-level state, encryption-key source, database liveness, and data-directory disk usage. The database and disk sections report their own errors while the endpoint remains a health snapshot. **Auth:** ADMIN or OWNER (`manage` permission). **Request:** no body. ### Response ```json theme={null} { "uptime_seconds": 86400, "log_level": {"level": "info", "baseline": "info"}, "encryption_key_source": "external", "db": {"connected": true}, "disk": {"path": "/var/lib/crewship", "total_bytes": 1000000, "free_bytes": 400000, "used_bytes": 600000, "used_pct": 60} } ``` | Status | Condition | | - | - | | `200` | Snapshot returned; individual probes may contain an `error` field. | | `401` | Missing authenticated workspace context. | | `403` | Caller lacks `manage`. | ## GET /api/v1/admin/log-level Reads the live process level, configured baseline, and optional expiry of a temporary override. **Auth:** ADMIN or OWNER (`manage` permission). **Request:** no body. ### Response ```json theme={null} {"level":"debug","baseline":"info","expires_at":"2026-08-04T12:00:00Z"} ``` `expires_at` is omitted when no timed override is active. | Status | Condition | | - | - | | `200` | Log-level state returned. | | `403` | Caller lacks `manage`. | ## PUT /api/v1/admin/log-level Changes the live process log level. A positive TTL automatically restores the baseline; `ttl_seconds: 0` leaves the override active until changed, and the server caps TTL at 24 hours. **Auth:** an **instance administrator** (see [Instance administration](/api-reference/admin#people-and-workspaces-across-the-instance)); a workspace ADMIN or OWNER is not enough. ### Request ```json theme={null} {"level":"debug","ttl_seconds":900} ``` `level` must be a supported logging level (`debug`, `info`, `warn`, or `error`). The baseline is the server's configured level (`CREWSHIP_LOG_LEVEL`, `info` when unset); this endpoint never changes it. Levels include everything above them: `debug` writes the most, `error` only errors. Every change is recorded in the instance audit as `instance.log_level_changed` (`from`, `to`, `baseline`, `ttl_seconds`, `expires_at`), and the server's own return to the baseline when a TTL runs out as `instance.log_level_reverted` with no user. Both carry `entity_id` `log-level`, so `GET /api/v1/admin/instance/audit?entity_id=log-level` lists them. The server log gets a line for each as well, written whatever the new level is (a change to `error` is not silenced by itself). ### Response `200 OK` returns the same `{level, baseline, expires_at}` object as the GET endpoint. | Status | Condition | | - | - | | `200` | Level changed. | | `400` | Invalid JSON or unsupported level. | | `403` | Caller is not an instance administrator. | ## GET /api/v1/admin/legacy-resources Read-only, instance-wide detection of orphaned pre-C1 slug-only Docker containers or volumes. It does not remove anything. **Auth:** ADMIN or OWNER (`manage` permission). **Request:** no body. ### Response ```json theme={null} {"present":true} ``` | Status | Condition | | - | - | | `200` | Detection completed. | | `401` | Missing authenticated workspace context. | | `403` | Caller lacks `manage`. | | `500` | Crew enumeration or provider scan failed. | | `503` | Docker detection is unavailable. | ## Rate limits Rate-limit settings are instance-wide even though the request still requires an authenticated workspace context. Reads require ADMIN or OWNER (`manage` permission); writes require an instance administrator. Overrides apply immediately and persist until reset. ## GET /api/v1/admin/rate-limits **Request:** no body. **Response:** `200 OK` with every tunable limiter. ```json theme={null} {"limiters":[{"key":"http.api_per_min","value":120,"default":120,"min":1,"max":10000,"overridden":false}]} ``` | Status | Condition | | - | - | | `200` | Limiter states returned. | | `403` | Caller lacks `manage`. | | `503` | Rate-limit configuration is unavailable. | ## PUT /api/v1/admin/rate-limits/ Overrides one registered limiter. **Auth:** an **instance administrator** (see [Instance administration](/api-reference/admin#people-and-workspaces-across-the-instance)); a workspace ADMIN or OWNER is not enough. ### Request ```json theme={null} {"value":40} ``` ### Response `200 OK` returns the updated limiter state in the same shape as the list response. Unknown keys are rejected; values must be within the limiter's published bounds. | Status | Condition | | - | - | | `400` | Invalid JSON or value outside the allowed range. | | `403` | Caller lacks `manage`. | | `404` | Unknown limiter key. | | `500` | Override could not be persisted. | | `503` | Rate-limit configuration is unavailable. | ## DELETE /api/v1/admin/rate-limits/ Resets the named limiter to its shipped default. **Auth:** instance administrator. **Request:** no body. **Response:** `200 OK` with the reset limiter state. | Status | Condition | | - | - | | `403` | Caller lacks `manage`. | | `404` | Unknown limiter key. | | `500` | Reset could not be persisted. | | `503` | Rate-limit configuration is unavailable. | ## POST /api/v1/admin/prune-legacy-resources Removes orphaned pre-C1, slug-only Docker containers and volumes across the instance. Live id-scoped resources are protected. The request has no body and the response lists the resource names removed. **Auth:** an **instance administrator** (see [Instance administration](/api-reference/admin#people-and-workspaces-across-the-instance)); a workspace ADMIN or OWNER is not enough. **Request:** no body. ### Response ```json theme={null} { "removed": ["crewship-tools-engineering", "crewship-home-engineering"], "count": 2 } ``` `200 OK` is returned on success. A Docker-unavailable deployment returns `503`; a mid-operation failure returns `500` with the partial `removed` list and `count`. | Status | Condition | | - | - | | `200` | Cleanup completed; response is the object above. | | `403` | Caller lacks `manage`. | | `500` | Cleanup failed; partial counts may be returned. | | `503` | Docker is unavailable. | ## POST /api/v1/admin/reap-orphan-containers Scans the current workspace's running crew containers for a sidecar token fingerprint that definitively disagrees with the token derived from the current internal-token master. The default is a dry run. Add `?apply=true` to stop and remove each detected orphan; the next dispatch recreates it. **Auth:** ADMIN or OWNER (`manage` permission). **Request:** no body; `apply` is an optional query parameter. **Response:** the scan object below. ### Response ```json theme={null} { "orphans": [ { "crew_id": "crew-uuid", "slug": "engineering", "container_id": "container-id", "reaped": false } ], "count": 1, "applied": false, "inspected": 3, "identified": 2, "detector_inert": false } ``` `reaped` is true only when `apply=true` and stop/remove succeeded. A running container with no advertised fingerprint is not classified or removed; `inspected` counts running containers reached and `identified` counts those that advertised a fingerprint. `detector_inert` is true when at least one container was inspected but none advertised a fingerprint. The endpoint returns `200 OK` even when an individual reap fails; that entry remains `reaped: false`. Docker-unavailable deployments return `503`. | Status | Condition | | - | - | | `200` | Scan completed, including dry-run results. | | `403` | Caller lacks `manage`. | | `503` | Docker is unavailable. | ## POST /api/v1/admin/reencrypt Re-encrypts every inventoried stored AES-256-GCM envelope to the current master-key version. The request has no body. It is instance-wide and idempotent: envelopes already at the current version are counted as skipped. Rows that cannot be decrypted are counted as failed and left untouched. **Auth:** an **instance administrator** (see [Instance administration](/api-reference/admin#people-and-workspaces-across-the-instance)); a workspace ADMIN or OWNER is not enough. **Request:** no body. ### Response ```json theme={null} { "key_version": "v2", "reencrypted": 12, "skipped": 8, "failed": 0, "columns": [ { "table": "credentials", "column": "encrypted_value", "reencrypted": 10, "skipped": 2, "failed": 0 } ] } ``` Each `columns` entry has the same three integer counters as the top-level response. A valid run returns `200 OK`. Invalid current-key configuration fails before any row is written with `500`; an infrastructure failure during the walk also returns `500` with partial counts and `columns`. | Status | Condition | | - | - | | `200` | Response contains the top-level and per-column counters below. | | `403` | Caller lacks `manage`. | | `500` | Key configuration or infrastructure failure; partial counts may be returned. | ## GET /api/v1/admin/security-posture Returns read-only, instance-level security state. It reports configuration presence and derived state only; it never returns a key, secret, or client secret. **Request:** no body. **Response:** JSON object shown below. ### Response ```json theme={null} { "environment": "prod", "encryption_key_configured": true, "plaintext_secrets_allowed": false, "private_endpoints_ceiling": false, "signup_open": false, "oauth_configured": true, "email_configured": true, "rate_limit_disabled": false, "rate_limit_effectively_disabled": false, "warnings": [ { "key": "no_backup_recorded", "severity": "medium", "message": "..." } ] } ``` `rate_limit_disabled` is configured intent; in `prod`, the limiter still runs and `rate_limit_effectively_disabled` is false. Warning keys are stable machine-readable identifiers and may include `plaintext_secrets_allowed`, `encryption_key_missing`, `rate_limit_disabled`, `rate_limit_disabled_ignored_in_prod`, `signup_open`, `private_endpoints_ceiling_open`, `encryption_key_generated`, `privileged_credentials_enabled`, `private_endpoints_in_use`, `seed_account_default_password`, and `no_backup_recorded`. | Status | Condition | | - | - | | `200` | Security posture returned. | | `403` | Caller lacks the required admin role. | ## GDPR Subject-access export and right-to-erasure across the cascadable tables. Both require ADMIN or OWNER (manage permission) and write a `gdpr_actions` audit row. > [!WARNING] > > The DELETE endpoint cascade-purges every row referencing the user across the cascadable tables and cannot be undone. A `reason` is required for the audit trail. ## GET /api/v1/admin/users/\{userId}/data GDPR Art. 15 (Right of Access) — return every row referencing the given user across the cascadable tables in the current workspace. Writes a `gdpr_actions` audit row with `action='export'`. **Required role:** ADMIN or OWNER (`manage` permission). MANAGER is intentionally **not** a SAR actor — auditor framing is Compliance/Founder separation of duties. ### Response ```json theme={null} { "data_subject_id": "user-uuid", "workspace_id": "ws-uuid", "exported_at": "2026-05-27T17:52:40.123456789Z", "action_id": "gdpr-action-cuid", "peer_cards": [ { "id": "pc-uuid", "agent_id": "agent-uuid", "user_slug": "alice", "path": "/crew/agents//peer-cards/alice.md", "bytes": 412, "created_at": "2026-05-01T...", "updated_at": "2026-05-26T..." } ], "memory_versions": [ { "id": "mv-uuid", "path": "agents//memory/long_term/...", "tier": "long_term", "sha256": "deadbeef...", "bytes": 1024, "written_at": "2026-05-10T...", "written_by": "agent-uuid", "payload_ref": "blob://..." } ], "inbox_items": [ { "id": "ib-uuid", "kind": "waitpoint", "source_id": "run-uuid", "title": "Approve PR #142", "body_md": "...", "state": "open", "payload_json": "{...}", "created_at": "2026-05-15T..." } ], "inbox_item_reads": [ { "inbox_item_id": "ib-uuid", "title": "Approve PR #142", "kind": "waitpoint", "read_at": "2026-05-15T..." } ] } ``` | Field | Type | Description | | - | - | - | | `data_subject_id` | `string` | The `userId` whose data is being exported. | | `workspace_id` | `string` | Workspace the export was scoped to. | | `exported_at` | `string` | RFC3339Nano timestamp of the export. | | `action_id` | `string` | Audit row in `gdpr_actions` for this SAR call — the operator's defensible artefact. | | `peer_cards` | `array` | Per-agent peer card rows referencing this user. | | `memory_versions` | `array` | Memory rows with `data_subject_id = userId`. Content blob is not inlined — `payload_ref` points at the content-addressed store. | | `inbox_items` | `array` | Inbox items addressed to or referencing this user. | | `inbox_item_reads` | `array` | The user's own per-item read markers (per-user read state): `{inbox_item_id, title, kind, read_at}` for every item in this workspace they marked read, whoever the item was about. `title` and `kind` ride along so the answer is legible without a second lookup. Also counted under `scope.inbox_item_reads`. | > [!NOTE] > > `lessons.md` content is **not** scanned for user mentions — a known gap (see [GDPR guide](/security/gdpr)). Operators must manually review lessons after a SAR if any lesson body could carry user-attributable text. ## DELETE /api/v1/admin/users/\{userId}/data GDPR Art. 17 (Right to Erasure) — cascade purge every row referencing the user across the cascadable tables. Writes a `gdpr_actions` audit row with `action='delete'`. **`reason` is required** for the audit trail. **Required role:** ADMIN or OWNER (`manage` permission). ### Request ```json theme={null} { "reason": "User SAR ticket #INC-1234 — Right to Erasure request" } ``` | Field | Type | Required | Description | | - | - | - | - | | `reason` | `string` | yes | Non-empty after trim. Persisted on the `gdpr_actions` row alongside the actor and target. Used in compliance reviews. | ### Response `202 Accepted` on full success; `207 Multi-Status` on partial success (some tables purged, others returned errors — the `gdpr_actions` row carries the full per-table summary). ```json theme={null} { "action_id": "gdpr-action-cuid", "data_subject": "user-uuid", "workspace_id": "ws-uuid", "rows_deleted": 7, "scope": { "peer_cards": 3, "memory_versions": 2, "inbox_items": 2, "inbox_item_reads": 9, "page_versions_anonymised": 5, "page_grants_removed": 0, "page_public_tokens_revoked": 0, "page_webhooks_revoked": 0 } } ``` On partial failure the same shape is returned with an additional `"error": ""` field and HTTP 207. | Field | Type | Description | | - | - | - | | `action_id` | `string` | The audit row id. The same SAR re-run writes a **second** action row — idempotent in row counts (zero on second run) but the audit trail records every attempt. | | `rows_deleted` | `int` | Sum of rows that went **away**, including the subject's own `inbox_item_reads` markers on this workspace's items. Rows the cascade only anonymised or reassigned (`page_versions_anonymised`, `pages_transferred`) are excluded — nothing was deleted there. | | `scope` | `object` | Per-table count summary (extensible — new keys appear additively as new tables join the cascade). A key ending in `_anonymised` means the row survived without the subject's name on it; `_removed` / `_revoked` means the row is gone and any capability it carried stopped working; `credentials_reattributed` counts credential attribution updates: live credentials transfer to a custodian and keep working; retired credentials clear their creator without requiring custody. See the [GDPR guide](/security/gdpr) for the per-table contract. | | `error` | `string?` | Present only on HTTP 207. First error encountered; consult the audit row for the full per-table picture. | > [!WARNING] > > Memory `payload_ref` content-addressed blobs on disk are **not** deleted by this endpoint — blobs are deduplicated across workspaces and require a separate sweep job (planned). The audit/index rows ARE purged so the SAR is honoured at the DB-visibility layer. See the [GDPR guide](/security/gdpr) for the operator workflow. ## Workspaces The workspaces the caller administers: the current one for a workspace admin, every workspace for the instance owner. ## GET /api/v1/admin/workspaces Lists workspaces with their counts, the week's runs, the month's spend, a few settings and the last audited change. The `X-Admin-Scope` response header is `workspace` (one row, the current workspace) or `instance` (every workspace, for the instance owner). **Required role:** ADMIN or OWNER (`manage` permission). **Request:** no body. **Response:** JSON array shown below. | Status | Condition | | - | - | | `200` | Workspaces returned. | | `401` | Missing authentication or workspace context. | | `403` | Caller is not ADMIN or OWNER. | | `500` | A query failed. | ### Response ```json theme={null} [ { "id": "ws-uuid", "name": "Engineering", "slug": "engineering", "logo_url": null, "created_at": "2025-01-01T00:00:00Z", "updated_at": "2025-06-15T12:00:00Z", "_count_members": 12, "_count_agents": 8, "_count_crews": 3, "preferred_language": "en", "run_retention_days": 90, "allow_privileged_credentials": false, "pending_invitations": 1, "last_activity_at": "2026-09-29T08:12:44Z", "runs_7d": 41, "runs_by_day": [5, 8, 6, 9, 3, 0, 10], "cost_30d_usd": 18.42, "current": true } ] ``` | Field | Type | Description | | - | - | - | | `preferred_language` | `string?` | Language agents answer in; null when unset | | `run_retention_days` | `int?` | How long runs are kept; null keeps them all | | `allow_privileged_credentials` | `bool` | Whether privileged credentials may be used | | `pending_invitations` | `int` | Invitations not accepted and not expired | | `last_activity_at` | `string?` | Time of the newest audit-log entry, as stored | | `runs_7d` | `int` | Runs started in the last seven UTC days, counted as the `runs_count` metric counts them | | `runs_by_day` | `int[7]` | The same, per UTC day, oldest first; the last entry is today | | `cost_30d_usd` | `number` | Estimated spend over the last 30 days, from the same source as the `cost_usd` metric | | `current` | `bool` | Whether this is the caller's current workspace | ## GET /api/v1/admin/journal/verify Walks the current workspace's journal **hash-chain** and reports whether it is intact — the tamper-evidence check for the append-only journal (`internal/api/admin_journal_integrity.go`). Detects content mutation, in-place reorder, and mid-chain deletion; see [Audit Log → Tamper-Evidence](/security/audit#tamper-evidence-the-journal-hash-chain) for the guarantee. **Required role:** ADMIN or OWNER (`canRole(role, "manage")`) The endpoint takes no parameters; the workspace comes from request context (`X-Workspace-ID`). It stays `200 OK` even when the chain is broken — inspect `ok`. ### Response ```json theme={null} { "workspace_id": "ws-uuid", "ok": false, "count": 42, "broken_seq": 43, "broken_id": "j_9f3c…", "reason": "content hash mismatch at seq 43: entry was modified after write" } ``` | Field | Type | Description | | - | - | - | | `ok` | boolean | `true` when the whole chain verifies | | `count` | integer | Entries walked before returning | | `broken_seq` | integer | `seq` of the first bad entry (omitted when `ok`) | | `broken_id` | string | `id` of the first bad entry (omitted when `ok`) | | `reason` | string | Human-readable cause of the break (omitted when `ok`) | | `breaks` | array | Every per-row failure (`seq`, `id`, `kind`, `reason`), capped at 100 | | `break_count` | integer | Exact number of failures, even when `breaks` is trimmed | | `repairable` | array | Rows whose content is proven authentic but whose live priority is unaccounted for: `seq`, `id`, `stored_priority`, `emit_priority` (the value the keyed hash proves) | | `repairable_count` | integer | Exact number of such rows, even when the list is trimmed | A non-empty `repairable` also produces a `priority` break, so `ok` is `false` — see [Audit Log → Recovered is not resolved](/security/audit#recovered-is-not-resolved). CLI parity: `crewship journal verify` (exits non-zero on a broken chain **or** when any entry has an unresolved priority). | Status | Condition | | - | - | | `200` | Response reports `ok`; a broken chain is still a successful HTTP response. | | `403` | Caller lacks `manage`. | ## Audit log The workspace audit trail — every `audit_logs` row for the current workspace, newest first. Requires the manage permission (ADMIN or OWNER). ## GET /api/v1/audit Returns a paginated, filterable list of audit-log entries for the current workspace, joined to the acting user for email/name display (`internal/api/audit.go:44`). **Required role:** ADMIN or OWNER (`canRole(role, "manage")` — `internal/api/audit.go:48`) ### Query Parameters | Parameter | Type | Default | Description | | - | - | - | - | | `page` | integer | `1` | 1-based page number; clamped to `1_000_000` to avoid offset overflow (`internal/api/audit.go:53-62`). | | `limit` | integer | `50` | Page size; values `< 1` or `> 100` reset to `50` (`internal/api/audit.go:63-66`). | | `action` | string | -- | Exact-match filter on `action`. | | `entity_type` | string | -- | Exact-match filter on `entity_type`. | | `entity_id` | string | -- | Exact-match filter on `entity_id`. | | `user_id` | string | -- | Exact-match filter on the acting user. | | `date_from` | string | -- | Lower bound on `created_at` (inclusive). | | `date_to` | string | -- | Upper bound on `created_at` (inclusive). | | `search` | string | -- | Case-insensitive `LIKE` across `action`, `entity_type`, and the joined user's email + full name (`internal/api/audit.go:133-143`). | ### Response ```json theme={null} { "data": [ { "id": "audit-uuid", "workspace_id": "ws-uuid", "user_id": "user-uuid", "action": "agent.update", "entity_type": "agent", "entity_id": "agent-uuid", "metadata": "{\"field\":\"llm_model\"}", "ip_address": "203.0.113.7", "user_agent": "crewship-cli/0.4.1", "created_at": "2026-06-30T14:02:11Z", "user_email": "demo@crewship.ai", "user_name": "Demo User" } ], "pagination": { "page": 1, "limit": 50, "total": 128, "total_pages": 3 } } ``` | Field | Type | Description | | - | - | - | | `user_id` | string? | Acting user; `null` for system-generated events (`internal/api/audit.go:25`). | | `metadata` | string? | Free-form JSON string captured with the event (`internal/api/audit.go:29`). | | `ip_address` / `user_agent` | string? | Request context, when recorded (`internal/api/audit.go:30-31`). | | `user_email` / `user_name` | string? | Joined from `users`; omitted (`omitempty`) when the row has no user (`internal/api/audit.go:33-34`). | | `data` | array | Always present; empty array when no rows match (`internal/api/audit.go:173-175`). | | `pagination` | object | `page`, `limit`, `total`, `total_pages` (`internal/api/audit.go:186-191`). | | Status | Condition | | - | - | | `200` | Page returned. | | `403` | Caller lacks the manage permission (`internal/api/audit.go:48-51`). | ## Memory admin Inspect and tune the memory subsystem: aggregate stats, row-level version drill-down, raw blob retrieval, and the per-workspace retention config. All require ADMIN or OWNER (manage permission). ## GET /api/v1/admin/memory/stats Returns aggregate statistics for the memory subsystem within the current workspace -- totals, per-tier rollups, and per-agent rollups derived from `memory_versions`. **Required role:** ADMIN or OWNER (manage permission) **Request:** no body. **Response:** the totals and rollups object below. ### Response ```json theme={null} { "workspace_id": "ws-uuid", "totals": { "versions": 1284, "bytes": 4823104, "blobs": 612, "oldest_at": "2026-03-02T07:14:22Z", "newest_at": "2026-05-18T08:30:00Z" }, "by_tier": [ { "tier": "agent", "versions": 904, "bytes": 3120388 }, { "tier": "crew", "versions": 220, "bytes": 1102716 }, { "tier": "workspace", "versions": 160, "bytes": 600000 } ], "by_agent": [ { "agent_slug": "", "versions": 380, "bytes": 1702716, "newest_at": "2026-05-18T08:12:11Z" }, { "agent_slug": "martin", "versions": 412, "bytes": 1880388, "newest_at": "2026-05-18T08:30:00Z" } ] } ``` | Field | Type | Description | | - | - | - | | `workspace_id` | `string` | Current workspace ID | | `totals.versions` | `integer` | Total `memory_versions` rows | | `totals.bytes` | `integer` | Sum of `bytes` across all rows | | `totals.blobs` | `integer` | Distinct sha256s; content-identical re-writes share one blob | | `totals.oldest_at` | `string` | RFC3339 of the oldest row; `""` when no rows | | `totals.newest_at` | `string` | RFC3339 of the newest row; `""` when no rows | | `by_tier[].tier` | `string` | `agent`, `crew`, `workspace`, `pins`, or `learned` | | `by_tier[].versions` | `integer` | Row count for the tier | | `by_tier[].bytes` | `integer` | Sum of `bytes` for the tier | | `by_agent[].agent_slug` | `string` | Slug extracted from canonical `agent:/...` prefix; `""` for crew/workspace-tier rows | | `by_agent[].versions` | `integer` | Row count for the agent | | `by_agent[].bytes` | `integer` | Sum of `bytes` for the agent | | `by_agent[].newest_at` | `string` | RFC3339 of the agent's newest row | ### Example ```bash theme={null} curl -H "Authorization: Bearer $TOKEN" \ https://crewship.example.com/api/v1/admin/memory/stats ``` | Status | Condition | | - | - | | `400` | Missing workspace context | | `403` | MEMBER role (manage permission required) | | `500` | Underlying SQLite query failure | > [!NOTE] > > Tiers with zero rows are omitted from `by_tier`. Tiers with rows the operator has never written to are NOT included as zero entries. ## GET /api/v1/admin/memory/versions Row-level drill-down into `memory_versions`. Pairs with the stats endpoint above: stats answers "how much memory does this workspace have?", versions answers "which rows specifically?". Results are ordered newest-first by `written_at DESC, id DESC` and paginated via an opaque keyset cursor. **Required role:** ADMIN or OWNER (manage permission) ### Query Parameters All parameters are optional and AND-composed. | Parameter | Type | Default | Description | | - | - | - | - | | `tier` | `string` | -- | Exact tier filter: `agent`, `crew`, `workspace`, `pins`, or `learned` | | `agent_slug` | `string` | -- | Slug from canonical `agent:/...` prefix; literal `%` / `_` in the slug match themselves | | `path_prefix` | `string` | -- | Match rows whose canonical path starts with this string; literal `%` / `_` match themselves | | `since` | `string` | -- | RFC3339 lower bound on `written_at` (inclusive) | | `until` | `string` | -- | RFC3339 upper bound on `written_at` (exclusive) | | `limit` | `integer` | `50` | Page size; hard cap at `500` | | `cursor` | `string` | -- | Opaque `next_cursor` from a prior response | ### Response ```json theme={null} { "workspace_id": "ws-uuid", "rows": [ { "id": "mv_01HZ...", "path": "agent:martin/AGENT.md", "tier": "agent", "sha256": "abc...", "bytes": 1234, "written_at": "2026-05-18T08:30:00Z", "written_by": "audit-watcher", "parent_sha": "def..." } ], "next_cursor": "djE6MjAyNi0wNS0xOFQwODozMDowMC4wMDBafG12XzAxSFo...", "limit": 50, "filters_applied": { "tier": "agent", "agent_slug": "martin" } } ``` | Field | Type | Description | | - | - | - | | `workspace_id` | `string` | Current workspace ID | | `rows[].id` | `string` | `memory_versions.id` | | `rows[].path` | `string` | Canonical memory path | | `rows[].tier` | `string` | Tier (`agent` / `crew` / `workspace` / `pins` / `learned`) | | `rows[].sha256` | `string` | Content sha256 of the blob | | `rows[].bytes` | `integer` | Byte length of the blob | | `rows[].written_at` | `string` | RFC3339 timestamp | | `rows[].written_by` | `string` | Writer identifier; `""` when NULL | | `rows[].parent_sha` | `string?` | Previous version's sha256; omitted when NULL | | `next_cursor` | `string?` | Opaque cursor for the next page; `null` on last page | | `limit` | `integer` | The resolved page size | | `filters_applied` | `object` | Echo of the normalised filters that produced this response | The cursor is a base64url-encoded `v1:|` tuple pinning `(written_at, id)`. Offset pagination would duplicate or skip rows because the audit watcher writes continuously; keyset pagination pins the boundary so concurrent inserts above the cursor land on the next refresh naturally. ### Example ```bash theme={null} curl -H "Authorization: Bearer $TOKEN" \ "https://crewship.example.com/api/v1/admin/memory/versions?tier=agent&agent_slug=martin&limit=20" ``` | Status | Condition | | - | - | | `400` | Unknown tier, malformed `since` / `until` (not RFC3339), non-positive `limit`, or unparseable `cursor` | | `403` | MEMBER role | | `500` | Underlying SQLite query failure | ## `GET /api/v1/admin/memory/versions/{id}/content` Returns the raw blob bytes for a single `memory_versions` row. Used by the dashboard's row-detail view and by compliance auditors who need the literal content (not just the metadata) -- for example, to confirm a PII scrubber fired on the offending payload. **Required role:** ADMIN or OWNER (manage permission) ### Response The body is the raw blob bytes (NOT JSON-wrapped). `Content-Type` is `text/markdown; charset=utf-8` for paths ending in `.md`, otherwise `application/octet-stream` so the client cannot auto-render untrusted bytes as HTML. Audit metadata travels alongside the body via response headers: | Header | Description | | - | - | | `X-Memory-Sha256` | sha256 from the `memory_versions` row | | `X-Memory-Bytes` | Length from the row (matches the row's recorded size) | | `X-Memory-Tier` | Tier (`agent` / `crew` / `workspace` / `pins` / `learned`) | | `X-Memory-Path` | Canonical memory path | | `X-Memory-Written-At` | RFC3339 timestamp | | `X-Memory-Written-By` | Writer identifier (omitted when NULL) | | `Cache-Control` | `private, max-age=31536000, immutable` -- blobs are content-addressed | ### Example ```bash theme={null} curl -H "Authorization: Bearer $TOKEN" \ -D - \ https://crewship.example.com/api/v1/admin/memory/versions/mv_01HZ.../content ``` | Status | Condition | | - | - | | `400` | Missing workspace context OR missing `id` path segment | | `403` | MEMBER role | | `404` | Unknown id OR cross-workspace probe (no existence leak) | | `410` | Row exists but the blob file is missing on disk (retention sweep, restore-from-backup race) | | `413` | Blob exceeds the 10 MB cap (DB-claimed size OR on-disk size) | | `500` | sha mismatch (blob tampered after recording) OR `payload_ref` resolves outside the configured blob root | | `503` | Memory versioning is not configured (lite-mode deployment without blob root) | > [!WARNING] > > The handler refuses to follow symlinks under `payload_ref`. The on-disk layout is fixed at `blobRoot//`; `filepath.EvalSymlinks` is used to verify the resolved path stays inside the blob root, defending against path-traversal vectors in a corrupted or malicious `payload_ref`. ## GET /api/v1/admin/memory/config Returns the per-workspace memory configuration. Drives the retention sweep (`versions_retention_days`) and is the operator's read surface for inspecting drift between "what's stored on the row" and "what's effective". **Required role:** ADMIN or OWNER (manage permission) **Request:** no body. **Response:** the configuration object below. ### Response ```json theme={null} { "workspace_id": "ws-uuid", "versions_retention_days": 30, "is_default": true, "raw_config": null } ``` | Field | Type | Description | | - | - | - | | `workspace_id` | `string` | Current workspace ID | | `versions_retention_days` | `integer` | Resolved retention window; falls back to the built-in default (30) when no row or no key is set | | `is_default` | `boolean` | `true` when no row exists, the key is missing, or the value fell back to the default | | `raw_config` | `string?` | Literal JSON stored on the `workspaces.memory_config` column; `null` when empty | ### Example ```bash theme={null} curl -H "Authorization: Bearer $TOKEN" \ https://crewship.example.com/api/v1/admin/memory/config ``` | Status | Condition | | - | - | | `400` | Missing workspace context | | `403` | MEMBER role | | `500` | Stored JSON is malformed (PATCH still works -- see below) | ## PATCH /api/v1/admin/memory/config Partial-merge update of the per-workspace memory configuration. Merges the request body's keys into the existing JSON document; unspecified keys are preserved. **Required role:** ADMIN or OWNER (manage permission) ### Request Body ```json theme={null} { "versions_retention_days": 7 } ``` | Field | Type | Description | | - | - | - | | `versions_retention_days` | `integer` | Positive integer in `[1, 3650]`. Zero, negative, fractional, or non-numeric values produce a 400 naming the offending field | Unknown top-level keys are passed through to the stored document for forward compatibility (e.g. future fields like `compaction_hour_override`). ### Response Returns the post-merge config in the same shape as the GET response above. A PATCH that produces no diff (e.g. resetting to the same value) returns `200` with the current shape and emits NO journal entry -- the audit trail tracks actual change, not request count. ### Example ```bash theme={null} curl -X PATCH \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"versions_retention_days": 7}' \ https://crewship.example.com/api/v1/admin/memory/config ``` | Status | Condition | | - | - | | `400` | Missing workspace context, malformed JSON, trailing garbage after the JSON value, empty body, or `versions_retention_days` outside `[1, 3650]` / not a positive integer | | `403` | MEMBER role | | `413` | Request body exceeds 16 KB | | `500` | UPDATE / commit failure | > [!NOTE] > > The read-merge-write runs inside a SQLite `BEGIN IMMEDIATE` (serializable) transaction so concurrent PATCHes touching different keys serialise rather than last-write-wins. Each real diff emits a `memory.config_updated` journal entry (Notice severity, ActorUser) with payload `{workspace_id, changes: {field: {from, to}}}`. If the stored JSON is corrupt, PATCH still succeeds (treats the existing document as empty) so operators can fix the row without resorting to manual SQL. ## POST /api/v1/admin/memory/user-model-sync ``` POST /api/v1/admin/memory/user-model-sync ``` Runs the operator-model sweep now — the one the server otherwise runs once a day at 05:00 UTC — and returns the per-workspace summary the scheduled run only ever logs. It is the same sweep, on the same extractor (the `curator` aux slot, resolved per call, with the `memory.user_model_profile` setting read fresh), over the same set of workspaces; only the trigger and the report differ. Why it exists: everything about the operator model fails silently by design. Nothing is written when the model proposes nothing, when every candidate is refused by the evidence gate, when the curator slot cannot be built, or when the person is below the interaction threshold — and all four look identical from outside. The summary tells them apart, now, instead of at 05:00 UTC. The sweep is safe to re-run: the merge is idempotent and the write is capped. It runs synchronously inside the request, one model call per candidate on the slot's per-call budget, so a workspace with many active operators can take minutes — clients must not cap the request at the usual 30 s (the CLI does not). **Auth:** ADMIN or OWNER (manage permission) in the session workspace. Without a `workspace_id` in the body the run is instance-wide, exactly like the scheduled sweep. **Request:** optional JSON body. `?workspace_id=` in the query is the *session* workspace, as on every admin route — it is not a filter. ```json theme={null} { "workspace_id": "ws_01HZ…", "dry_run": true } ``` | Field | Type | Description | | - | - | - | | `workspace_id` | `string?` | Narrow the run to one workspace, by id or slug. Omitted: every active (non-deleted) workspace on the instance. | | `dry_run` | `boolean?` | Run everything up to the write — the candidate query, the consent probe, the threshold, the extractor — and report what *would* have happened. Nothing lands on disk, in `user_models`, or in `peer_card_audit`. Also accepted as `?dry_run=true`. | **Response:** `200 OK` with the run's report. ```json theme={null} { "sweep": "user_model", "dry_run": false, "workspaces": [ { "workspace_id": "ws_01HZ…", "candidates": 3, "writes": 1, "skipped_threshold": 1, "skipped_empty": 1, "skipped_opt_out": 0, "purged_opt_out": 0, "errors": 0 } ], "totals": { "candidates": 3, "writes": 1, "skipped_threshold": 1, "skipped_empty": 1, "skipped_opt_out": 0, "purged_opt_out": 0, "errors": 0 }, "duration_ms": 4120 } ``` | Field | Description | | - | - | | `sweep` | `user_model` here; `peer_card` on the sibling route. | | `dry_run` | Echoes the request, so a report cannot be mistaken for a record of what happened. | | `workspaces[].candidates` | Operators with a chat in the 14-day lookback window. | | `workspaces[].writes` | Models written (or, on a dry run, that would have been). | | `workspaces[].skipped_threshold` | Below the interaction threshold (messages and session length). | | `workspaces[].skipped_empty` | The extractor had nothing to write. With no model on the curator slot this is every candidate. | | `workspaces[].skipped_opt_out` / `purged_opt_out` | The operator has opted out; `purged` means an existing model was deleted (or would have been). | | `workspaces[].errors` | Candidates that failed inside the sweep — an extractor error, a failed write. Each has a `Warn` line in the server log. | | `workspaces[].error` | Present only when the sweep for that workspace could not run at all (the candidate query failed). The other workspaces still ran. | | `totals` | The same counters summed over `workspaces`. | ### Example ```bash theme={null} curl -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"dry_run": true}' \ "https://crewship.example.com/api/v1/admin/memory/user-model-sync?workspace_id=$WS" ``` | Status | Condition | | - | - | | `200` | The sweep ran (or, with `dry_run`, was simulated); per-workspace failures are on the rows, not the status | | `400` | Malformed JSON body, an unknown field, or a `dry_run` that is not `true`/`false` | | `401` | No or invalid credentials | | `403` | MEMBER or MANAGER role | | `404` | `workspace_id` names no active workspace | | `500` | The workspace list or lookup failed | | `503` | The server has no storage base path, so the sweep has nowhere to write (the scheduled worker is not running either) | CLI: `crewship admin memory sync user-model [--all] [--dry-run]`. ## POST /api/v1/admin/memory/peer-card-sync ``` POST /api/v1/admin/memory/peer-card-sync ``` Runs the peer-card sweep now — the 04:00 UTC one — and returns the same report shape as the operator-model route above, with `"sweep": "peer_card"`. The sweep walks every (agent, operator) pair that crossed the interaction threshold, purges the cards of operators who have opted out, and writes a card where the extractor produced one. The server wires no peer-card extractor today, so a run indexes and purges without writing new bodies — which is also what the scheduled run does — and every threshold-crosser shows up under `skipped_empty`. **Auth:** ADMIN or OWNER (manage permission) in the session workspace; instance-wide without `workspace_id`. **Request:** the same optional body as the operator-model route — `workspace_id` (id or slug) and `dry_run`, the latter also as `?dry_run=true`. **Response:** `200 OK` with the report — `sweep`, `dry_run`, `workspaces[]`, `totals`, `duration_ms` — where the per-workspace counters are `candidates`, `writes`, `skipped_threshold`, `skipped_empty`, `skipped_opt_out`, `purged_opt_out`, `errors`, plus `error` when that workspace's sweep could not run. | Status | Condition | | - | - | | `200` | The sweep ran, or was simulated with `dry_run` | | `400` | Malformed JSON body, an unknown field, or a `dry_run` that is not `true`/`false` | | `401` | No or invalid credentials | | `403` | MEMBER or MANAGER role | | `404` | `workspace_id` names no active workspace | | `500` | The workspace list or lookup failed | | `503` | No storage base path on this server | CLI: `crewship admin memory sync peer-cards [--all] [--dry-run]`. ## Keeper The operator-facing Keeper audit log, plus the Phase 2 F4 evaluator routes. The audit-log read requires ADMIN or OWNER (manage permission); the Phase 2 evaluator routes are internal-auth (see below). ## POST /api/v1/admin/prune-crew-runtimes Prunes crew runtime containers and volumes that are no longer needed. The operation is restricted to callers with `manage` permission (ADMIN or OWNER). **Request:** no body. **Response:** `200 OK` with the number of pruned runtimes. The operation is safe to repeat; an unavailable runtime provider returns `503` and a pruning failure returns `500`. **Statuses:** `200 OK`; `401` without authentication; `403` without manage permission; `503` when the runtime provider is unavailable; `500` for a prune failure. ## GET /api/v1/admin/keeper/requests Returns the Keeper access request audit log -- every credential access and command execution request evaluated by the Keeper. **Required role:** ADMIN or OWNER (manage permission) ### Query Parameters | Parameter | Type | Default | Description | | - | - | - | - | | `limit` | `integer` | `50` | Max entries to return (1-200) | | `offset` | `integer` | `0` | Offset for pagination | ### Response ```json theme={null} [ { "id": "request-uuid", "agent_id": "agent-uuid", "agent_name": "Viktor", "crew_id": "crew-uuid", "credential_id": "cred-uuid", "credential_name": "Anthropic Production", "intent": "Need to call the Claude API to analyze code", "request_type": "credential", "command": null, "decision": "ALLOW", "reason": "Low-risk API call with clear intent", "risk_score": 2, "exit_code": null, "ollama_prompt": "...", "ollama_raw_response": "...", "created_at": "2025-01-15T10:30:00Z", "decided_at": "2025-01-15T10:30:01Z" } ] ``` | Field | Type | Description | | - | - | - | | `id` | `string` | Request ID | | `agent_id` | `string` | Requesting agent ID | | `agent_name` | `string` | Agent display name | | `crew_id` | `string` | Crew the agent belongs to | | `credential_id` | `string` | Credential being accessed | | `credential_name` | `string` | Credential display name | | `intent` | `string` | Agent's stated intent for access | | `request_type` | `string` | One of `credential` / `execute` / `skill_review` / `behavior` / `memory_health` / `negative_learning` (see Keeper Phase 2 below) | | `command` | `string?` | Shell command (for execute requests); omitted when null | | `decision` | `string?` | `ALLOW`, `DENY`, or `ESCALATE` | | `reason` | `string?` | LLM-generated explanation | | `risk_score` | `integer?` | Risk assessment (1-10 scale) | | `exit_code` | `integer?` | Command exit code (for execute requests); omitted when null | | `ollama_prompt` | `string?` | Full prompt sent to the Keeper LLM; omitted when null | | `ollama_raw_response` | `string?` | Raw LLM response text; omitted when null | | `created_at` | `string` | ISO 8601 request timestamp | | `decided_at` | `string?` | ISO 8601 decision timestamp | > [!NOTE] > > Phase 2 request types (`skill_review`, `behavior`, `memory_health`, `negative_learning`) populate the same audit log surface as Phase 1 (`credential`, `execute`) with the same shape. The `intent` column carries the F4 evaluator's structured summary instead of a free-form access reason; the `ollama_prompt` + `ollama_raw_response` capture the LLM evaluation round-trip. Filter by `request_type` to slice the log into per-evaluator views. > [!NOTE] > > This endpoint returns the **current** state of each request. `decision` is written `PENDING` and updated in place, so it cannot tell you how the request got there. For that, use the transition history below. ## GET /api/v1/admin/keeper/requests//events Returns the **append-only transition history** for one Keeper request, oldest first — the record that the in-place `decision` update would otherwise destroy (issue #1369). **Required role:** ADMIN or OWNER (manage permission) **Request:** no body. **Statuses:** `200 OK`; `401` without authentication; `403` without manage permission; `404` when the request does not exist; `500` for a database error. ### Path Parameters | Parameter | Type | Description | | - | - | - | | `requestId` | `string` | The `keeper_requests.id` whose history to read | ### Response ```json theme={null} [ { "seq": 1, "state": "PENDING", "request_type": "execute", "requesting_agent_id": "agent-uuid", "agent_name": "Viktor", "credential_id": "cred-uuid", "credential_name": "Deploy Key", "intent": "Ship the release branch", "command": "gh pr merge 1449", "actor_type": "agent", "actor_id": "agent-uuid", "recorded_at": "2026-07-25T10:30:00Z" }, { "seq": 2, "state": "ALLOW", "request_type": "execute", "reason": "Scoped merge with clear intent", "risk_score": 2, "exit_code": 0, "actor_type": "keeper", "actor_id": "keeper", "recorded_at": "2026-07-25T10:30:05Z" } ] ``` | Field | Type | Description | | - | - | - | | `seq` | `integer` | 1-based, monotonic per request. A gap or duplicate is itself a signal | | `state` | `string` | The state *entered* by this transition: `PENDING`, `ALLOW`, `DENY`, `ESCALATE`, `DUPLICATE_SUPPRESSED`, or a Phase-2 verdict | | `actor_type` | `string` | `agent` (raised the request), `keeper` (decided it), `user` (an operator resolved it), `system` (dedup suppression) | | `actor_id` | `string?` | The specific actor, when known | | `reason` / `risk_score` / `exit_code` | — | Decision detail at that transition. Omitted where not yet applicable: a `PENDING` has no risk score, and no exit code exists before the command ran | | `request_type`, `requesting_agent_id`, `agent_name`, `requesting_crew_id`, `credential_id`, `credential_name`, `intent`, `command` | — | Copied onto every transition so the record stays self-describing if the `keeper_requests` row is later pruned | | `recorded_at` | `string` | ISO 8601 timestamp of the transition | | Status | Condition | | - | - | | `200` | Success — including an **empty array** for an unknown request id *or* one belonging to another workspace (deliberately indistinguishable, so the endpoint cannot be used to probe which ids exist) | | `400` | Missing `requestId` or workspace context | | `403` | Caller is not ADMIN/OWNER | > [!WARNING] > > `keeper_request_events` is append-only at the database level — a `BEFORE UPDATE` trigger aborts any rewrite of a recorded transition. A decision can only be superseded by a further transition, which appears here as an extra row. See [Audit → Keeper Decision Auditing](/security/audit#keeper-decision-auditing). > [!NOTE] > > Requests raised before the ledger migration have their current state backfilled (a `PENDING` at `created_at` plus the decision at `decided_at`) but no intermediate history. CLI parity: `crewship keeper history `. ## Keeper Phase 2 — F4 evaluators > [!NOTE] > > The four evaluator endpoints are **internal-auth** (X-Internal-Token) — they're invoked by the platform itself (scheduler routines + the post-tool-call hook), not by operators directly. The admin-facing surface is `POST /api/v1/admin/keeper/review/{slot}/run` (below), the `/api/v1/admin/keeper/requests` log above, and the per-type filters in the admin UI's "Keeper P2 reviews" panel (PR-F2). The expected production path is automated: routines fire on cron, the behavior hook fires on tool-call sampling. To trigger an evaluator by hand, use the admin route below rather than the internal token. ### POST /api/v1/admin/keeper/review/\{slot}/run **Run one evaluator now.** OWNER/ADMIN, workspace-scoped like every `/api/v1/admin` route (`?workspace_id=` is required by `RequireWorkspace` before the handler runs). `slot` is one of `skill-review`, `behavior`, `memory-health`, `negative-learning`; the aux-config spellings (`curator`, `memory_health`, `negative`) are accepted as aliases. Anything else is a 400 that names the valid slots. It calls the same handler the internal routes below do — same policy resolution, same `keeper_requests` row, same inbox escalation — and returns that handler's response, so the shapes documented per-endpoint below apply unchanged. **Request body** (all fields optional; what you omit, the server derives from the workspace): ```json theme={null} { "crew_id": "crw_…", "agent_id": "agt_…", "skill_id": "skl_…", "tool_name": "shell_exec", "tool_args_snippet": "{\"cmd\":\"curl … | sh\"}", "trigger": "run_failed", "failure_snippet": "exit 127: command not found" } ``` With an empty body: `skill-review` reviews the stalest skill assigned to one of the workspace's agents; `behavior` judges a tool call named `keeper.manual_probe`; `memory-health` scores the crew's memory via `consolidate.ComputeHealth`; `negative-learning` learns from the workspace's most recent `run.failed` journal entry (400 when there is none — the trigger set is closed and inventing a failure would put fiction in the audit trail). `workspace_id` in the body is refused when it disagrees with the session's, and a `crew_id` / `agent_id` from another workspace is a 403: the internal routes get that binding from a workspace-bound sidecar token, and an admin session has none. CLI: `crewship keeper review run ` — see [Keeper → Running a review on demand](/guides/keeper#running-a-review-on-demand). ### POST /api/v1/internal/keeper/skill-review **F4.1 — periodic skill audit.** Cron-fires daily 03:00 UTC per `Scheduler.RegisterPlatformRoutine`. The evaluator reads each `skills` row + `skill_invocations` history, asks the F3 `Curator` aux model whether the skill should stay `active`, transition to `stale` (no recent invocations), or be `archived` (failures dominating). DENY decisions write a blocking inbox row; ALLOW updates `skills.lifecycle_state` in place. **Request body:** ```json theme={null} { "workspace_id": "ws_…", "crew_id": "crw_…", "skill_id": "skl_…", "skill_name": "rotate-anthropic-keys", "skill_description": "Rotate the Anthropic API key quarterly", "lifecycle_state": "active", "last_used_at": "2026-05-15T08:00:00Z", "assignments": 3, "assigned_agents": ["agt_…", "agt_…"], "stats": { "invocations_30d": 4, "failures_30d": 0 }, "failure_snippets": [] } ``` | Field | Required | Notes | | - | - | - | | `workspace_id` | yes | MUST match the request context `workspace_id` (see [Internal IPC](/api-reference/internal#tenant-isolation-on-internal-auth-handlers)). | | `crew_id` | yes | Used for per-crew policy resolution. | | `skill_id` | yes | The skill being reviewed. | | `skill_name`, `skill_description`, `lifecycle_state` | yes | Current state snapshot the LLM evaluates. | | `last_used_at` | optional | RFC3339; empty = "never". | | `assignments`, `assigned_agents` | optional | Fan-out context for ESCALATE → inbox routing. | | `stats` | optional | 30-day invocation + failure counts. | | `failure_snippets` | optional | Up to 3 most-recent failure excerpts (truncated). | **Response:** ```json theme={null} { "request_id": "kpr_skr_a3f8e2…", "decision": "ALLOW", "reason": "Skill still actively used (4 invocations in 30d, 0 failures)", "risk_score": 1, "verify_after_decide": true, "unverify_after_decide": false, "proposed_lifecycle": "active" } ``` DENY routes a blocking `inbox_items` row to the assigned agents' workspace (per `assigned_agents` fan-out). ESCALATE routes a `MANAGER`-targeted blocking row. ### POST /api/v1/internal/keeper/behavior **F4.2 — post-tool-call behavior monitor.** Fires from `behaviorhook.MaybeEvaluate` (orchestrator `EventPostToolCall` event), sampled at the per-crew rate (default 1-in-5). The evaluator reads the `(tool_name, tool_args_snippet, current crew behavior_mode)` triple and returns ALLOW / DENY / ESCALATE. `behavior_mode=warn` (default): DENY → non-blocking inbox; agent's NEXT tool call proceeds. `behavior_mode=block`: DENY → blocking inbox + `ShouldBlock=true` in the response so the orchestrator interrupts the agent's next call. Forbidden combination `(autonomy=full + behavior_mode=block)` rejected at API + DB layer. **Request body:** ```json theme={null} { "workspace_id": "ws_…", "crew_id": "crw_…", "agent_id": "agt_…", "agent_name": "Anna", "crew_name": "Ops", "tool_name": "shell_exec", "tool_args_snippet": "{\"cmd\":\"rm -rf node_modules\"}" } ``` **Response:** ```json theme={null} { "request_id": "kpr_bhv_b71e9c…", "decision": "DENY", "reason": "Destructive command without scoped path; recommend restricting to a specific directory", "risk_score": 7, "should_block": true, "policy_decision": "block_inbox" } ``` `policy_decision` is the resolved per-crew policy verdict (e.g. `inbox_approve`, `auto_log_inbox`, `block_inbox`) that drives whether an inbox row is written and whether it blocks. ### POST /api/v1/internal/keeper/memory-health **F4.3 — periodic memory consolidation review.** Cron-fires daily 03:30 UTC. The evaluator consumes a `consolidate.HealthSnapshot` (the 5-metric health score: Freshness / Coverage / Coherence / Efficiency / Reachability, each in `[0, 100]`, plus the weighted `Overall`) and decides whether to auto-trigger a consolidation routine. Staleness and contradiction counts travel as separate top-level body fields, not inside `snapshot`. **Request body:** ```json theme={null} { "workspace_id": "ws_…", "crew_id": "crw_…", "crew_name": "Ops", "agent_name": "Anna", "snapshot": { "WorkspaceID": "ws_…", "CrewID": "crw_…", "Freshness": 80, "Coverage": 70, "Coherence": 65, "Efficiency": 90, "Reachability": 87, "Overall": 76 }, "agent_md_bytes": 2840, "persona_md_bytes": 1120, "crew_md_bytes": 5120, "stalest_entry_days": 412, "contradiction_count": 3 } ``` > [!NOTE] > > `snapshot` is the `consolidate.HealthSnapshot` Go struct serialised **without JSON tags**, so its wire keys are PascalCase (`Freshness`, `Reachability`, `Overall`, …) and each metric is on a `0–100` scale — not the `reachability_pct` / `0–1` shape an external caller might guess. `stalest_entry_days` and `contradiction_count` are top-level fields alongside `snapshot`, not nested inside it. **Response:** ```json theme={null} { "request_id": "kpr_mhc_c83a4b…", "decision": "DENY", "reason": "412-day stalest entry + 3 contradictions; consolidator recommended", "risk_score": 6, "auto_consolidate": true, "overall_score": 38 } ``` `auto_consolidate=true` triggers `consolidator.Run` for the workspace; ESCALATE writes a blocking inbox row instead. ### POST /api/v1/internal/keeper/negative-learning **F4.4 — failure-event lesson capture.** Fires after a guardrail trip, run failure, or explicit operator "log this lesson" action. The evaluator decides whether the failure is worth a `kind=negative` lesson in the agent's `lessons.md`. ALLOW writes through `consolidate.WriteLesson` (PR-Z Z.7) which enforces YAML schema + idempotency by ID + flock + atomic-rename. **Self-learning gate:** ALLOW auto-applies only when the agent has `self_learning_enabled = 1` (migration v106). With `self_learning_enabled = 0` (default), ALLOW queues a blocking inbox row with the full lesson proposal in `payload_json` and the marker `"self_learning_gate": "off"` so the UI can distinguish the gate-demoted path. See [Autonomy + self-learning](/guides/autonomy-and-self-learning). **Trigger kinds:** `run_failed`, `guardrail_warn`, `guardrail_error`, `keeper_execute_deny`. **Request body:** ```json theme={null} { "workspace_id": "ws_…", "crew_id": "crw_…", "agent_id": "agt_…", "agent_name": "Anna", "crew_name": "Ops", "agent_memory_dir": "/output/agt_…/.memory", "trigger": "run_failed", "tool_name": "shell_exec", "failure_snippet": "deploy.sh: missing DATABASE_URL", "prior_lesson": "" } ``` | Field | Notes | | - | - | | `agent_memory_dir` | Container-side path where `lessons.md` lives; the consolidate writer mkdir-p's as needed. | | `trigger` | One of the four kinds above. | | `prior_lesson` | Optional dup-suppression: if non-empty, the evaluator gets it as "the agent already knows X" context and is less likely to ALLOW a near-duplicate. | **Response:** ```json theme={null} { "request_id": "kpr_neg_d94f5a…", "decision": "ALLOW", "reason": "Recurring deploy-env mistake worth a permanent lesson", "risk_score": 4, "write_lesson": true, "lesson_id": "les_abc123…" } ``` When `self_learning_enabled = 0` the response still says `write_lesson: true` (the evaluator's intent), but no lesson lands on disk — the operator must approve via inbox. Check `gdpr_actions`-style audit via `GET /api/v1/admin/keeper/requests?request_type=negative_learning`. ### Cross-tenant guard > [accordion] How the four evaluators enforce workspace isolation > > All four endpoints assert `body.workspace_id == ctx.workspace_id` via `assertBodyWorkspaceMatchesCtx` before any evaluator runs. Asymmetric forgery (query=A, body=B) returns `400 Bad Request`. Empty ctx workspace also returns 400 — the gate refuses to operate without the middleware that's supposed to set it. Symmetric forgery (caller picks one workspace consistently) requires PR-F24 token-to-workspace binding to close fully. See [Internal IPC — Tenant isolation](/api-reference/internal#tenant-isolation-on-internal-auth-handlers). ## System Small cross-cutting endpoints that don't belong to any single domain handler. They surface install state, telemetry consent, the running binary's version, and dashboard time-series metrics. > [!NOTE] > > `setup-status` and `telemetry` are intentionally **unauthenticated** because the login page needs to read them before any session exists; `version` and `metrics/timeseries` require an authenticated user (`metrics/timeseries` also needs workspace context). ### GET /api/v1/system/setup-status First-run gate. Returns whether the install needs to be bootstrapped (empty `users` table) and whether public signup is enabled. The login page calls this on every page paint -- when `needs_bootstrap` is `true`, the browser routes to `/bootstrap` instead of `/login`. **Auth:** none -- the answer is what tells the browser which page to render. **Request:** no body. **Response:** `{needs_bootstrap, allow_signup}`. | Status | Condition | | - | - | | `200` | Bootstrap state returned; database errors fail closed in the body. | #### Response ```json theme={null} { "needs_bootstrap": false, "allow_signup": false } ``` | Field | Type | Description | | - | - | - | | `needs_bootstrap` | boolean | `true` when `COUNT(*) FROM users = 0`. DB errors fail closed as `false` -- a transient blip won't ship the user into the bootstrap flow on a healthy install. | | `allow_signup` | boolean | Mirrors the `CREWSHIP_ALLOW_SIGNUP` server flag. When `false`, the login page hides the "Sign up" link. | ### GET /api/v1/system/telemetry Read-only consent gate for the frontend's Sentry client. The Next.js `sentry.client.config.ts` fetches this before calling `Sentry.init` and bails out if `enabled=false`. Consent is flipped via the CLI (`crewship telemetry on/off`), never over HTTP -- making this endpoint mutating would create a CSRF vector that flips the bit on every cross-site navigation. **Auth:** none -- the login page must boot crash reporting before any session exists. **Request:** no body. **Response:** `{enabled, install_id}`. | Status | Condition | | - | - | | `200` | Consent state returned; transient failures fall back to disabled. | #### Response ```json theme={null} { "enabled": true, "install_id": "a3f9c2e1b8d74f5a" } ``` | Field | Type | Description | | - | - | - | | `enabled` | boolean | `true` only when the operator has opted in, a DSN is wired, AND the backend Sentry init succeeded. | | `install_id` | string | Anonymous identifier the backend already ships as Sentry's `ServerName`. Exposed so frontend events group with backend events for the same install. | Errors fall back to `{enabled: false, install_id: ""}` rather than 5xx -- a transient DB blip defaults to the privacy-preserving outcome. ### GET /api/v1/system/version Reports the running binary's **build identity** and (cache-permitting) the latest release from GitHub. The web UI uses `current`/`latest`/`newer`/`url` to render an "update available" banner; the build fields answer the separate question of *which build this server actually is*. This is the only way to ask a running server what it is. `crewship version --remote` is the CLI for it. **Auth:** required (any authenticated user, no workspace role needed). **Request:** no body. **Response:** build identity and release metadata below. | Status | Condition | | - | - | | `200` | Version information returned. | | `401` | Missing or invalid authentication. | #### Response ```json theme={null} { "current": "0.4.1", "latest": "0.4.2", "newer": true, "url": "https://github.com/crewship-ai/crewship/releases/tag/v0.4.2", "commit": "496c8c1a84be761abdb5cbe323a1fd501b8b9ab7", "build_time": "2026-08-02T15:35:24Z", "dirty": false, "go_version": "go1.26.5", "os": "linux", "arch": "amd64", "schema_version": 20260801150210 } ``` | Field | Type | Description | | - | - | - | | `current` | string | The running binary's version (`SetBuild`-injected from `cmd_start`). `"dev"` for any build made without `-ldflags`. | | `latest` | string? | Latest release tag from GitHub. `null` on a cold cache + GitHub timeout. | | `newer` | boolean | `true` when `latest > current` by semver. | | `url` | string? | Release page URL. `null` paired with `null` `latest`. | | `commit` | string | Full git SHA of the build. Falls back to the binary's embedded VCS stamp when no `-ldflags` were passed, which is the only source an unstamped build has. `""` when neither is available (`go run`, `go install` from the module proxy). | | `build_time` | string | RFC 3339. The `-ldflags` build date, else the commit time from the VCS stamp. `""` when unknown. | | `dirty` | boolean? | Whether the working tree had uncommitted changes at build time. **`null` means unknown** -- a build with `-ldflags` but no VCS stamping (the Dockerfile path) genuinely does not know, and reporting that as `false` would be a confident wrong answer. | | `go_version` | string | Go toolchain that compiled the server. | | `os` / `arch` | string | `GOOS` / `GOARCH` of the server binary. | | `schema_version` | integer | The highest migration this server binary can apply. For anything past the closed legacy sequential block this is a `YYYYMMDDHHMMSS` timestamp, so it also dates the newest schema change the build contains. A booted server has already migrated its database to this number. | The handler imposes a 4 s upper bound on top of the update package's 5 s internal HTTP timeout -- a cold cache + slow network still returns "no info" rather than blocking the UI render. The build fields are computed in-process and are unaffected by it. > [!NOTE] > > `current` alone cannot identify a build. Every binary an `-ldflags`-less `go build` has ever produced calls itself `dev` -- which is how a dev slot once sat a full day behind `main` with nothing able to say so. Compare `commit`. ### GET /api/v1/metrics/timeseries Bucketed time-series metrics for the dashboard charts. Returns zero-filled bucket sequences so the client never has to patch visual gaps. Reads `workspace_id` from the request context, never from a query param. **Auth:** required + workspace context. `metric=cost_usd` additionally requires `OWNER` or `ADMIN` and answers `403` ("Spend requires OWNER or ADMIN") to every other role; the other metrics are open to every member. See [Who sees cost figures](/api-reference/paymaster#who-sees-cost-figures). #### Query parameters | Param | Type | Default | Description | | - | - | - | - | | `metric` | string | -- | Required. One of `issues_closed`, `cost_usd`, `runs_count`, `active_missions`, `success_rate`, `p95_duration_ms`. `success_rate` is the percentage of finished runs that succeeded and `p95_duration_ms` the nearest-rank p95 run duration, both per bucket by the run's start, from the same rules as `GET /api/v1/runs/insights` (cancelled and running runs are not counted as success or failure). A bucket in which nothing finished has no `total` value instead of a zero. These two accept only `group_by=none`. | | `window` | string | `"24h"` | One of `24h`, `7d`, `30d`. | | `bucket` | string | `"1h"` | One of `15m`, `1h`, `1d`. Combinations producing >200 buckets are rejected. | | `group_by` | string | `"none"` | One of `none`, `crew`, `model`, `status`. Some group-by values are metric-specific (see error matrix). | #### Response ```json theme={null} { "metric": "issues_closed", "window": "7d", "bucket": "1d", "group_by": "none", "buckets": [ { "ts": "2026-05-14T00:00:00Z", "series": { "total": 4 } }, { "ts": "2026-05-15T00:00:00Z", "series": { "total": 0 } }, { "ts": "2026-05-16T00:00:00Z", "series": { "total": 7 } } ], "series_labels": { "total": "Total" } } ``` | Field | Type | Description | | - | - | - | | `metric` / `window` / `bucket` / `group_by` | string | Echo of the resolved query parameters. | | `buckets[].ts` | string | Bucket-start in UTC, aligned to wall-clock boundaries (`15m` → `:00/:15/:30/:45`, `1h` → top of hour, `1d` → UTC midnight). | | `buckets[].series` | object | Map of series key to numeric value. Always floats on the wire so cost and counts share the JSON shape. | | `series_labels` | object | Map of series key to display label (e.g. crew name, model name, status). For `group_by=none` always contains `{"total": "Total"}`. | | Status | Condition | | - | - | | `400` | Unknown `metric` / `window` / `bucket` / `group_by`; bucket larger than window; combination produces >200 buckets; `group_by=model` for a metric other than `cost_usd`; `group_by=crew` for a metric other than `issues_closed`/`runs_count`; `group_by=status` for a metric other than `issues_closed`/`active_missions`. | | `401` | Workspace context missing from the request. | | `500` | SQLite fill query failed. | ## License System > [!NOTE] > > **Current behavior.** The open-source edition has unlimited crews, members and agents. The license API reports `0` for each resource limit, meaning unlimited. Resource licensing may change in future releases; the signed-license infrastructure remains available for that purpose. The edition identifiers below are retained for future licensing. They do not impose resource limits in current releases, even when a loaded signed license contains finite caps. ### Editions | Edition | Description | Limits | | - | - | - | | **Community** | Free, default edition | Unlimited crews, agents/crew and members | | **Team** | Paid team tier | Reserved for future licensing | | **Enterprise** | Full enterprise tier | Reserved for future licensing | ### License Claims Each license contains signed claims: | Claim | Type | Description | | - | - | - | | `license_id` | `string` | Unique license identifier | | `licensee_name` | `string` | Licensed user name | | `licensee_org` | `string` | Licensed organization | | `edition` | `string` | `community`, `team`, or `enterprise` | | `max_crews` | `integer` | Maximum number of crews | | `max_agents_per_crew` | `integer` | Maximum agents per crew | | `max_members` | `integer` | Maximum workspace members | | `features` | `string[]` | Enabled feature flags | | `issued_at` | `integer` | Unix timestamp of issuance | | `expires_at` | `integer` | Unix timestamp of expiration | ### License Verification Licenses are verified using Ed25519 digital signatures: **1. Signed format** A license file contains a JSON object with `payload` (the claims as a JSON string) and `signature` (base64-encoded Ed25519 signature). **2. Public key embedding** The Ed25519 public key is embedded into the binary at build time via `ldflags`. This prevents license tampering by tying verification to the specific build. **3. Signature verification** On startup, Crewship decodes the public key and signature from base64, then verifies the payload using `ed25519.Verify()`. **4. Expiration check** If the license has an `expires_at` timestamp and it is in the past, the license is rejected and community defaults apply. **5. Fallback** If no license file exists, verification fails, or the license is expired, Crewship runs with community edition defaults. > [!WARNING] > > The public key variable is set at build time. Without a valid public key embedded in the binary, license loading will fail with "no public key embedded in binary" and community defaults will apply. ## What's Next > [card] [RBAC](/security/rbac) > > Role-based access control and permission levels. > [card] [Keeper Guide](/guides/keeper) > > Configure the AI-powered security gatekeeper. # Agents Source: https://docs.crewship.ai/api-reference/agents Manage agents — AI coding agents with configurable roles, CLI adapters, skills, and credentials. Agents in a crew share one Linux container. An **agent** is an AI coding agent with a configurable role, CLI adapter, skills, and credentials. Agents belonging to the same crew share one Linux container. These endpoints cover the full agent lifecycle: creating and configuring permanent agents, hiring short-lived ephemeral "contractors", managing their skills and credentials, driving chats and runs, inspecting workspace files, and tuning the persona and self-learning layers that shape each agent's behavior. > [!NOTE] > > Cost fields on this page are `OWNER` / `ADMIN` only. Other roles receive the same response with them left out — see [Who sees cost figures](/api-reference/paymaster#who-sees-cost-figures). > [!NOTE] > > All `/api/v1/agents/*` endpoints require authentication and workspace context. Workspace context may be supplied as `workspace_id`, a `{workspaceId}` path value, or the `X-Workspace-ID` header; the chat-message proxy (`/api/v1/chats/{chatId}/messages`) is the exception — it resolves the workspace from the chat row and takes no workspace context parameter. ## Endpoints | Method | Endpoint | Purpose | | - | - | - | | GET | [/api/v1/agents/crews-status](#crews-status) | Lightweight agent counts by status for toolbar/dashboard widgets | | GET | [/api/v1/agent-load](#agent-load) | Agent load metrics across the workspace | | GET | [/api/v1/models](#model-discovery) | Enumerate the models a provider can serve (live or curated) | | GET | [/api/v1/agents](#list-agents) | List agents (optionally filtered by crew) | | POST | [/api/v1/agents](#create-agent) | Create a new agent | | GET | [/api/v1/agents/](#get-agent) | Get a single agent | | PATCH | [/api/v1/agents/](#update-agent) | Partially update an agent | | DELETE | [/api/v1/agents/](#delete-agent) | Soft-delete an agent | | POST | [/api/v1/agents//webhook-secret/rotate](#rotate-webhook-secret) | Rotate and return an agent webhook secret once | | DELETE | [/api/v1/agents//webhook-secret/previous](#rotate-webhook-secret) | End a rotation overlap now | | POST | [/api/v1/agents/hire](#hire-agent) | Spawn a new ephemeral agent under a crew | | POST | [/api/v1/agents//rehire](#rehire-agent) | Resurrect or extend an ephemeral agent | | POST | [/api/v1/agents//release](#release-agent) | End a temporary hire now | | POST | [/api/v1/agents//approve-hire](#approve-hire) | Approve a guided-autonomy pending hire | | GET | [/api/v1/agents//persona](#get-persona) | Get the resolved persona | | PUT | [/api/v1/agents//persona](#set-persona) | Operator-only direct persona write | | DELETE | [/api/v1/agents//persona](#reset-persona) | Remove the agent persona layer | | GET | [/api/v1/agents//persona/history](#get-persona-history) | List persona version history | | POST | [/api/v1/agents//persona/suggest](#suggest-persona) | Agent-initiated persona proposal | | GET | [/api/v1/agents//learning](#get-self-learning) | Get the self-learning flag and audit triple | | PATCH | [/api/v1/agents//learning](#set-self-learning) | Flip the self-learning flag | | GET | [/api/v1/agents//inbox](#agent-inbox-summary) | Consolidated "what's waiting on this agent" payload | | GET | [/api/v1/agents//peers](#list-agent-peers) | List the agent's peer-card index | | GET | [/api/v1/agents//peers/](#get-agent-peer-card) | Get one peer card's full content | | DELETE | [/api/v1/agents//peers/](#delete-agent-peer-card) | Delete one peer card | | GET | [/api/v1/agents//skills](#list-skills) | List skill assignments | | POST | [/api/v1/agents//skills](#add-skill) | Assign a skill | | DELETE | [/api/v1/agents//skills/](#remove-skill) | Remove a skill | | GET | [/api/v1/agents//credentials](#list-credentials) | List credential assignments | | POST | [/api/v1/agents//credentials](#assign-credential) | Assign a credential | | DELETE | [/api/v1/agents//credentials/](#remove-credential) | Remove a credential | | GET | [/api/v1/agents//credential-readiness](#credential-readiness) | Report whether a delivered credential authenticates the agent's model | | GET | [/api/v1/agents//chats](#list-chats) | List chat sessions | | POST | [/api/v1/agents//chats](#create-chat) | Create a new chat session | | PUT | [/api/v1/agents//chats//read](#mark-chat-read) | Mark a chat read | | PATCH | [/api/v1/agents//chats/](#rename-chat) | Rename a chat session | | DELETE | [/api/v1/agents//chats/](#delete-chat) | Delete a chat session | | POST | [/api/v1/agents//chats//attachments](#chat-attachments) | Upload a chat attachment | | GET | [/api/v1/agents//chats//attachments](#list-chat-attachments) | List a chat's attachments | | DELETE | [/api/v1/agents//chats//attachments/](#delete-chat-attachment) | Delete one chat attachment | | GET | [/api/v1/agents//runs](#agent-runs) | List execution history | | GET | [/api/v1/agents//credential-bindings](#credential-bindings) | List MCP credential bindings | | GET, POST, PATCH, DELETE | [/api/v1/agents//integrations](#agent-integrations) | Manage agent MCP integrations | | GET | [/api/v1/agents//integrations/resolved](#agent-integrations) | Resolve effective MCP integrations | | GET | [/api/v1/agents//notification-channels](#agent-notification-channels) | List notification channels available to an agent | | GET | [/api/v1/agents//debug](#agent-proxy-endpoints) | Debug information for a running agent | | GET | [/api/v1/agents//files](#agent-proxy-endpoints) | List files in agent workspace | | GET | [/api/v1/agents//files/download](#agent-proxy-endpoints) | Download a file | | PUT | [/api/v1/agents//files/save](#agent-proxy-endpoints) | Save/upload a file | | GET | [/api/v1/agents//container-files](#container-files) | List files inside the running container | | GET | [/api/v1/agents//git-log](#git-log) | Recent git commits from the container workspace | | GET | [/api/v1/agents//logs](#agent-proxy-endpoints) | Get agent logs | | POST | [/api/v1/agents//stop](#agent-proxy-endpoints) | Stop a running agent | | GET | [/api/v1/chats//messages](#chat-messages) | Get messages for a chat session | ## Status & Metrics Lightweight, read-only aggregates that power toolbar and dashboard widgets. ### Crews Status ``` GET /api/v1/agents/crews-status?workspace_id={workspaceId} # Response is a per-workspace aggregate counting agents by status # (IDLE/RUNNING/ERROR — no STOPPED bucket). Drives the 'Crews idle/online' # badge in the top toolbar. ``` Returns lightweight agent counts by status for toolbar/dashboard widgets. **Auth:** Authenticated session or CLI token with resolved workspace context; the router applies the workspace-scoped authenticated middleware. **Request:** No body. Supply workspace context with `X-Workspace-ID` (or the equivalent workspace context accepted by the API). **Response:** `200 OK` ```json theme={null} { "total": 12, "running": 3, "error": 1, "idle": 8, "queued": 0 } ``` **Status:** `400` for invalid workspace context, `401` when unauthenticated, `403` when the caller cannot access the workspace, and `500` when the status query fails. #### Contract: `GET /api/v1/agents/crews-status` **Auth:** Authenticated request with workspace context. **Request:** no body; the workspace is supplied through the workspace context/header. **Response:** `200 OK` with the status-count object above. **Status:** `400`, `401`, `403`, or `500` as described above. The agent status buckets (`total`, `running`, `error`, `idle`) are always present — zero counts are not omitted. Any status that is not `RUNNING` or `ERROR` (including `IDLE` and `PENDING_REVIEW`) folds into the `idle` bucket; there is no `stopped` bucket. The `queued` field counts admission-queue *assignments* (not agents) currently in the `QUEUED` state — independent of the agent buckets, and `0` on servers that pre-date the queue migration (`internal/api/agents.go:111-151`). *** ### Agent Load ``` GET /api/v1/agent-load?workspace_id={workspaceId} ``` Returns agent load metrics across the workspace. **Auth:** Authenticated session or CLI token with resolved workspace context. **Request:** No body. Supply workspace context with `X-Workspace-ID` (or the equivalent workspace context accepted by the API). **Response:** `200 OK` — an array (never `null`) of entries with `agent_id`, `agent_name`, `agent_slug`, `agent_status`, `active_tasks`, `pending_tasks`, `completed_today`, `tokens_used_today`, and `token_budget`. Active tasks include `IN_PROGRESS`; pending tasks include `PENDING` and `BLOCKED`; token usage and completed counts are calculated over the current UTC day/24-hour reporting window used by the handler. **Status:** `400` for invalid workspace context, `401` when unauthenticated, and `403` when the caller cannot access the workspace. *** ## Model Discovery Enumerate the models an LLM provider can serve, so an operator (or an agent building a `POST`/`PATCH /api/v1/agents` request) doesn't have to guess a model identifier. Discovery is **live when possible, curated when not** (`internal/api/models.go:84`): if the workspace has an active `API_KEY` credential for the provider, Crewship queries the provider's own models API; otherwise it returns a hand-maintained curated fallback. The `source` field reports which path was taken. See the [Model discovery guide](/guides/model-discovery) for the CLI equivalent (`crewship model list`) and the `llm_model` validation this same resolver drives on [agent update](#update-agent). ### List Models ``` GET /api/v1/models?provider={PROVIDER}&workspace_id={workspaceId} ``` **Auth:** Any authenticated workspace member (`authed` + workspace context; the active provider credential is read from the resolved workspace) (`internal/api/router_crews.go:230`). **Query Parameters:** | Parameter | Type | Required | Description | | - | - | - | - | | `provider` | string | Yes | Provider to enumerate. Case-insensitive; upper-cased server-side. One of `ANTHROPIC`, `OPENAI`, `GOOGLE`, `OLLAMA`, `OPENCODE`, `OPENCODE_GO`, `ZAI_CODING_PLAN` (`internal/api/models.go:66-74`; the three gateway providers answer from a curated list and never reject custom ids). | | `workspace_id` | string | Yes | Workspace whose provider credential is used for live listing. | **Response:** `200 OK` ```json theme={null} { "provider": "ANTHROPIC", "source": "live", "models": [ { "id": "claude-opus-4-8", "display_name": "Claude Opus 4.8", "provider": "anthropic" }, { "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6", "provider": "anthropic" } ] } ``` | Field | Type | Description | | - | - | - | | `provider` | string | Echo of the resolved (upper-cased) provider (`internal/api/models.go:36`). | | `source` | string | `"live"` when the provider's own API answered, `"curated"` when the static fallback was used (`internal/api/models.go:37`). | | `models` | array | Always a JSON array (never `null`), even when empty (`internal/api/models.go:120`). | | `models[].id` | string | Model identifier to pass as `llm_model` (`internal/llm/provider.go:100`). | | `models[].display_name` | string | Human-readable name; omitted when the provider gives none (`internal/llm/provider.go:101`). | | `models[].provider` | string | Lower-case provider tag on the model (`internal/llm/provider.go:102`). | > [!NOTE] > > **`OLLAMA` has no curated fallback.** Its model set is whatever the local daemon has pulled, so there is no sensible static list. When the daemon can't be reached the endpoint returns **`502`** rather than an empty list, so "daemon unreachable" is never mistaken for "no models installed" (`internal/api/models.go:151-157`). `GOOGLE` has no live lister yet and always resolves to its curated set (`internal/api/models.go:119`). | Status | Condition | | - | - | | `200` | Model set returned (`source` reports live vs curated). | | `400` | `provider` missing, or not one of the supported providers (`internal/api/models.go:129-137`). | | `502` | `OLLAMA` daemon unreachable and no curated fallback exists (`internal/api/models.go:155`). | *** ## Lifecycle & CRUD Create, read, update, and soft-delete permanent agents. ### List Agents ``` GET /api/v1/agents?workspace_id={workspaceId} ``` **Query Parameters:** | Parameter | Type | Description | | - | - | - | | `workspace_id` | string | Required. Workspace ID | | `crew_id` | string | Optional. Filter by crew | | `limit` | integer | Optional. Page size, default `100`, maximum `500` | | `offset` | integer | Optional. Rows to skip | | `q` | string | Optional. Server-side search on name, slug and role title | | `include_setup` | `1` | Optional. Also return agents of the onboarding Guide's crew (`kind=setup`). Hidden by default from every roster and every total, the way `GET /crews` hides the crew itself. | **Paging (every windowed list on this API):** the body stays a bare array; the window is described in three response headers so no consumer breaks: | Header | Meaning | | - | - | | `X-Total-Count` | rows matching the filter, before `limit`/`offset` | | `X-Limit` | the limit actually applied (after clamping) | | `X-Offset` | the offset actually applied | `q` is a case-insensitive substring search on the server (name and slug and role title); it narrows the total as well as the page. The web app and the CLI read the headers to say "showing 1–100 of 103" instead of calling a page the whole. \| `include_setup` | `1` | Optional. Also return agents of the onboarding Guide's crew (`kind=setup`). Hidden by default from every roster, the way `GET /crews` hides the crew itself. | \| `limit`, `offset` | int | Optional. Page (default 100, max 500). | **Response:** `200 OK` ```json theme={null} [ { "id": "agent_abc", "crew_id": "crew_123", "workspace_id": "ws_456", "name": "Backend Dev", "slug": "backend-dev", "description": "Go backend developer", "role_title": "Senior Developer", "agent_role": "AGENT", "lead_mode": null, "status": "IDLE", "cli_adapter": "CLAUDE_CODE", "llm_provider": "ANTHROPIC", "llm_model": "claude-sonnet-5", "system_prompt": "You are a Go backend developer...", "avatar_seed": "backend-dev", "avatar_style": "bottts", "timeout_seconds": 1800, "tool_profile": "CODING", "memory_enabled": true, "cli_tools": null, "schedule_cron": null, "schedule_prompt": null, "schedule_enabled": false, "schedule_last_run": null, "schedule_next_run": null, "mcp_config_json": null, "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:00Z", "crew": { "name": "Engineering", "slug": "engineering", "color": "blue", "avatar_style": "bottts" }, "_count": { "skills": 2, "credentials": 1, "chats": 5 }, "created_by_user_id": "user_789", "ephemeral": false, "expires_at": null, "expired_at": null, "parent_lead_id": null, "hire_reason": null } ] ``` `mcp_config_json` and `created_by_user_id` carry `omitempty` — they are dropped from the JSON entirely when null/empty rather than serialized as `null`. #### Response Fields | Field | Type | Description | | - | - | - | | `id` | string | Agent ID | | `crew_id` | string | Parent crew ID | | `workspace_id` | string | Workspace ID | | `name` | string | Display name | | `slug` | string | URL-safe identifier | | `description` | string? | Agent description | | `role_title` | string? | Human-readable role title | | `agent_role` | string | `AGENT` or `LEAD` | | `lead_mode` | string? | `"active"` or `"passive"` (LEAD agents only) | | `status` | string | `IDLE`, `RUNNING`, or `ERROR` | | `cli_adapter` | string | CLI tool used to run the agent | | `llm_provider` | string? | LLM provider name | | `llm_model` | string? | LLM model identifier | | `system_prompt` | string? | System prompt for the agent | | `avatar_seed` | string? | Seed for avatar generation | | `avatar_style` | string? | Avatar style slug (e.g., `"voxel-bot"`, `"pixel-art"`); `null` follows the crew's style, else the default. See [Avatar styles](#avatar-styles). | | `avatar_url` | string? | Serve URL for the agent's **stored** avatar, or `null` when it has none and is still generated from the seed. See [Agent avatars](#agent-avatars). | | `timeout_seconds` | integer | Maximum execution time | | `tool_profile` | string | Tool access profile | | `memory_enabled` | boolean | Whether agent memory is enabled | | `suggested_prompts` | string? | Chat suggestions offered under an empty conversation, one per line (max 8, max 120 chars each). `null` when unconfigured -- the chat then shows the built-in defaults | | `ask_forms` | string? | The agent's questionnaires: a JSON array of form definitions, canonical as stored (max 4 forms, max 6 fields each). `null` when unconfigured -- see **Ask forms** under [Update Agent](#update-agent) | | `cli_tools` | string? | Comma-separated list of allowed CLI tools | | `schedule_cron` | string? | Cron expression for scheduled runs | | `schedule_prompt` | string? | Prompt used for scheduled runs | | `schedule_enabled` | boolean | Whether schedule is active | | `schedule_last_run` | string? | ISO 8601 timestamp of last scheduled run | | `schedule_next_run` | string? | ISO 8601 timestamp of next scheduled run | | `mcp_config_json` | string? | Agent-level MCP server config (omitted when empty) | | `crew` | object? | Embedded crew info (name, slug, color, avatar\_style) | | `_count` | object | Counts: skills, credentials, chats | | `created_by_user_id` | string | Creator user ID; omitted for legacy rows with no creator | | `ephemeral` | boolean | `true` for hired contractor agents, `false` for permanent agents | | `expires_at` | string? | RFC3339 TTL deadline (ephemeral agents only) | | `expired_at` | string? | RFC3339 ghost timestamp once the TTL elapses | | `parent_lead_id` | string? | LEAD agent that parented this ephemeral | | `hire_reason` | string? | Timestamped hire/rehire reason log | *** ### Create Agent ``` POST /api/v1/agents?workspace_id={workspaceId} ``` **Auth:** `OWNER`, `ADMIN`, or `MANAGER` role **Request Body:** | Field | Type | Required | Default | Description | | - | - | - | - | - | | `name` | string | Yes | -- | Display name (2-100 characters) | | `slug` | string | Yes | -- | URL-safe identifier (2-50 chars, lowercase letters/digits/hyphens) | | `crew_id` | string | Conditional | `null` | Parent crew ID. Required when `agent_role` is `LEAD`; optional for `AGENT` (`internal/api/agents_create.go:73`). Must belong to the caller's own workspace — a crew from another workspace is rejected with `400`. | | `description` | string | No | `null` | Agent description | | `role_title` | string | No | `null` | Human-readable role title | | `agent_role` | string | No | `"AGENT"` | `AGENT` or `LEAD` | | `lead_mode` | string | No | `"active"` | `"active"` or `"passive"` (LEAD agents only) | | `cli_adapter` | string | No | `"CLAUDE_CODE"` | CLI adapter | | `llm_provider` | string | No | `null` | LLM provider | | `llm_model` | string | No | `null` | LLM model | | `system_prompt` | string | No | `null` | System prompt | | `avatar_seed` | string | No | `null` | Avatar seed | | `avatar_style` | string | No | `null` | Avatar style slug ([Avatar styles](#avatar-styles)); `null` follows the crew, else Voxel Bot. An unknown slug is a `400`. | | `timeout_seconds` | integer | No | `1800` | Max execution time in seconds | | `tool_profile` | string | No | `"CODING"` | Tool profile | | `memory_enabled` | boolean | No | `false` | Enable agent memory | ```json theme={null} { "name": "Backend Dev", "slug": "backend-dev", "crew_id": "crew_123", "agent_role": "AGENT", "cli_adapter": "CLAUDE_CODE", "system_prompt": "You are a Go backend developer...", "memory_enabled": true, "tool_profile": "CODING" } ``` **Agent Roles:** | Role | Description | Crew Required | | - | - | - | | `AGENT` | Worker that executes tasks | Yes | | `LEAD` | Crew leader that plans and delegates | Yes (max 1 per crew) | **CLI Adapters:** `CLAUDE_CODE`, `CODEX_CLI`, `GEMINI_CLI`, `OPENCODE`, `CURSOR_CLI`, `FACTORY_DROID` **Tool Profiles:** `MINIMAL`, `CODING`, `FULL` **Response:** `201 Created` -- returns the created agent object. | Status | Condition | | - | - | | `400` | Invalid name, slug, role, missing required crew\_id, or crew\_id belongs to another workspace | | `402` | Reserved for future license limits; currently unlimited | | `403` | Insufficient role | | `409` | Slug already taken (`code: agent_slug_taken`), slug reserved by a former agent of the crew (`agent_slug_reserved`), or crew already has a LEAD agent (`crew_lead_exists`). See [Error Format](/api-reference/overview#error-format). | *** ### Get Agent ``` GET /api/v1/agents/{agentId}?workspace_id={workspaceId} ``` Provider-account metadata is permission-dependent. Callers without account access receive `pays_with: { "provider": "OPENAI", "restricted": true }` (with the applicable provider), not an unfunded-agent verdict. Account name, credential id, owner, plan and refresh details are withheld. **Response:** `200 OK` -- full agent object, plus `pays_with`: the provider login paying for this agent's model — `{ "credential_id", "name", "login" }` with the same `login` object the credentials API returns (see [Credentials → Response Fields](/api-reference/credentials#response-fields)), or `null` when nothing in the agent's resolved delivery is a login of its adapter's provider (`CLAUDE_CODE` → `ANTHROPIC`, `CODEX_CLI` → `OPENAI`, `GEMINI_CLI` → `GOOGLE`, `CURSOR_CLI` → `CURSOR`, `FACTORY_DROID` → `FACTORY`, `OPENCODE` → the agent's `llm_provider`). Derived on this route only; list rows carry `null`. | Status | Condition | | - | - | | `404` | Agent not found | *** ### Update Agent ``` PATCH /api/v1/agents/{agentId}?workspace_id={workspaceId} ``` Partial update -- only provided fields are changed. **Auth:** Per-agent edit gate (`canEditAgent` in `internal/api/agents_update.go:27`, defined at `internal/api/rbac.go:151`). `OWNER` / `ADMIN` may edit any agent; `MANAGER` may edit only agents they created or agents in crews where they hold per-crew `ADMIN`/`OWNER`; `MEMBER` / `VIEWER` are refused. **Request Body:** Same fields as Create, all optional. `status` is not mutable through this endpoint. Additionally supports: | Field | Type | Description | | - | - | - | | `cli_tools` | string | Comma-separated CLI tools | | `schedule_cron` | string | Cron expression | | `schedule_prompt` | string | Schedule prompt | | `schedule_enabled` | boolean | Enable/disable schedule | | `mcp_config_json` | string | Agent MCP config JSON (must contain an `mcpServers` object) | | `suggested_prompts` | string | Chat suggestions, one per line (see below) | | `ask_forms` | string | Ask forms as a JSON array, given as a **string** (see below) | **Suggested prompts.** `suggested_prompts` holds the questions this agent offers as buttons under an empty conversation, one per line -- at most 8 lines, at most 120 characters each. The server normalises on write: CRLF becomes LF, each line is trimmed, blank lines are dropped, and a value that ends up empty is stored as `null`. An agent with `null` here is not misconfigured; it simply shows the built-in defaults, which is what every agent did before the field existed. Rejections name the offending line -- `"at most 8 prompts are allowed (got 9)"`, `"prompt 3 exceeds 120 characters (it has 154)"` -- so a caller can fix the entry rather than the whole list. Set it from the console under an agent's **Config -> Chat suggestions**, or with `crewship agent update --suggested-prompts @questions.txt`. **Ask forms.** `ask_forms` holds the questionnaires this agent offers: a chip that opens a short form, whose answers are rendered into an **ordinary user message** and sent. The value is a JSON array given as a *string* -- the column is TEXT, the console edits it in a textarea and the CLI reads it from a file, and accepting a nested array as well would put two encodings of one value on one endpoint. ```json theme={null} [{ "id": "receipt", "label": "Add a receipt", "template": "Please file this receipt.\n\nSupplier: {{supplier}}\nAmount: {{amount}} {{amount_currency}}\nPeriod: {{month}}\nCategory: {{category}}\nDocument: {{document}}", "attachment": "required", "fields": [ {"name": "supplier", "label": "Supplier", "type": "text", "required": true, "placeholder": "Vodafone"}, {"name": "amount", "label": "Amount", "type": "money", "required": true, "currency": ["CZK", "EUR", "USD"]}, {"name": "month", "label": "Period", "type": "month", "default": "2026-08"}, {"name": "category", "label": "Category", "type": "select", "options": ["Telco", "Hosting"]}, {"name": "document", "label": "Document", "type": "file"} ] }] ``` `id` is a slug and must be unique; `label` is the chip's text (max 48 characters); `attachment` is `none` | `optional` | `required` and defaults to `none`; `template` is at most 2000 characters. Field types are `text`, `textarea`, `number`, `money`, `date`, `month`, `select`, `multiselect`, `checkbox`, `file` and `photo` -- **an unrecognised type is accepted and falls back to a text input**, which is what lets a new type ship without a coordinated frontend release. `select` and `multiselect` must carry `options`. A JSON Schema for authoring lives at `schemas/ask-form.v1.json`. **Money fields answer to two placeholders.** A `money` field named `amount` renders as `{{amount}}` for the number and `{{amount_currency}}` for the chosen currency. The second name is derived so that two money fields on one form cannot fight over a single `{{currency}}`. **Template rendering.** `{{field}}` substitution only -- no conditionals, no loops, no expressions. Three rules decide what gets sent: 1. Every placeholder must name a field on **its own form**, and this is checked when the form is **saved**, not when it is rendered. The author finds out while authoring; the person talking to the agent never meets a broken template. 2. An empty optional value **drops the whole line it sits on**, static label and all, unless another placeholder on that line produced something. So a receipt with no category sends no `Category:` line rather than a dangling one. This is the only rule that is not obvious from reading a template. 3. Values are inserted verbatim -- the result is a user message, so nothing is markdown-escaped -- but control characters are stripped, each value is capped at 2000 characters and the finished message at 32000. `file` and `photo` values render as the agent-visible path `attachments//`, one per line when there are several. **Rejections name the form and the placeholder**, because the caller is mid-edit: `form "receipt": template names {{suplier}}, which is not a field on that form`, `form "receipt": has no fields`, `two forms share the id "receipt"`, `at most 4 forms are allowed per agent (got 5)`. Nothing is written when a definition is refused. A value that normalises to nothing -- `""`, whitespace, `[]`, or `null` -- clears the column. The stored value is **canonical**: parsed, validated and re-encoded with defaults spelled out and a stable key order, so what a caller reads back is stable rather than showing a diff nobody made. Set it from the console under an agent's **Config -> Ask forms**, or with `crewship agent update --ask-forms @forms.json`, and render one without a browser with `crewship agent ask-preview --var k=v`. **Response:** `200 OK` -- updated agent object. | Status | Condition | | - | - | | `409` | Renaming onto a slug another live agent of the workspace holds (`code: agent_slug_taken`, `field: slug`), or onto a slug a former agent of the target crew still owns (`agent_slug_reserved`). A slug held only by a deleted agent of another crew is free. | *** ### Delete Agent ``` DELETE /api/v1/agents/{agentId}?workspace_id={workspaceId} ``` Soft-deletes the agent (sets `deleted_at`). **Request:** No body; `agentId` is a required path parameter and workspace context scopes the lookup. > [!WARNING] > > This is a destructive operation. Same per-agent edit gate as Update (`canEditAgent` in `internal/api/agents_query.go:266`, defined at `internal/api/rbac.go:151`). `OWNER` / `ADMIN` delete any agent; `MANAGER` deletes only agents they created or agents in crews where they hold per-crew `ADMIN`/`OWNER`. **Response:** `200 OK` ```json theme={null} { "success": true } ``` ### Rotate Webhook Secret ``` POST /api/v1/agents/{agentId}/webhook-secret/rotate ``` Uses the same per-agent edit gate as Update. The new signing secret is returned exactly once; Crewship stores only its protected form and does not provide a read endpoint. Optional body `{"previous_secret_ttl_seconds": N}` keeps the replaced secret valid for N seconds (`0`, the default, or `60` to `604800`); the response then also carries `previous_secret_expires_at`. Rotating again during an overlap replaces the remembered secret. `DELETE /api/v1/agents/{agentId}/webhook-secret/previous` ends an overlap now (idempotent, same edit gate, `204`). Each delivery verified with the previous secret is audited as `agent.webhook_previous_secret.used`. **Response:** `200 OK` ```json theme={null} { "webhook_secret": "whsec_…", "rotated_at": "2026-06-04T12:00:00Z" } ``` | Status | Condition | | - | - | | `403` | Caller lacks edit rights for this agent. | | `404` | Agent not found in this workspace. | | `500` | Secret storage is not configured or failed. | *** ## Hire / Rehire / Approve Ephemeral agents ("contractors") are short-lived agents spawned against a crew with a TTL. When the TTL elapses the agent becomes a **ghost** (the row is preserved for audit but no longer counts against the crew's quota). The hire flow is gated by the crew's **autonomy policy** (`strict` / `guided` / `trusted` / `full`) and bounded by the crew's `max_ephemeral_agents` quota (ghosts excluded). > [!NOTE] > > All three endpoints require `OWNER`, `ADMIN`, or `MANAGER` role (`canRole(role, "create")`). ### Hire Agent ``` POST /api/v1/agents/hire?workspace_id={workspaceId} ``` Spawns a new ephemeral agent under a crew. The crew's autonomy policy decides the outcome: | Autonomy | Outcome | | - | - | | `strict` | `403` — the hire is rejected with a structured reason. | | `guided` | `202` — the agent row is created in `PENDING_REVIEW`, a **blocking** inbox waitpoint is dropped, and the agent will not start until [approved](#approve-hire). | | `trusted` | `201` — the agent goes live immediately; a non-blocking inbox visibility item is recorded. | | `full` | `201` — the agent goes live immediately; journal-only, no inbox row. | **Auth:** `OWNER`, `ADMIN`, or `MANAGER` role **Request Body:** | Field | Type | Required | Description | | - | - | - | - | | `crew_id` | string | Conditional | Target crew by id. Provide exactly one of `crew_id` / `crew_slug`. | | `crew_slug` | string | Conditional | Target crew by slug. Mutually exclusive with `crew_id`. | | `template_slug` | string | Yes | Crew template the ephemeral is built from (built-in or workspace-owned). | | `ttl_minutes` | integer | No | Lifetime in minutes. Clamped to `1–1440`; a value of `0`/negative falls back to the server floor of **30**. | | `reason` | string | Yes | Audit/history trail for the hire. | | `model` | string | No | LLM model override. Empty falls back to the template default at provisioning time. | | `parent_lead_id` | string | No | A `LEAD` agent in the **same crew + workspace** that parents this ephemeral. | ```json theme={null} { "crew_slug": "engineering", "template_slug": "backend-dev", "ttl_minutes": 60, "reason": "Spike: investigate the flaky deploy script", "model": "claude-sonnet-5" } ``` **Response:** `201 Created` (live) or `202 Accepted` (pending review). ```json theme={null} { "id": "agent_abc", "crew_id": "crew_123", "workspace_id": "ws_456", "slug": "backend-dev-eph-1a2b3c", "name": "Backend Dev", "status": "IDLE", "ephemeral": true, "expires_at": "2026-06-04T13:00:00Z", "expired_at": null, "parent_lead_id": null, "hire_reason": "[2026-06-04T12:00:00Z] hire: Spike: investigate the flaky deploy script", "pending_review": false, "inbox_item_id": "ib-cuid", "decision": "auto_log_journal" } ``` | Field | Type | Description | | - | - | - | | `id` | string | New agent id. | | `crew_id` | string? | Resolved crew id. | | `workspace_id` | string | Workspace id. | | `slug` | string | Generated ephemeral slug (`