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.

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	Aggregate stats for the current workspace
`GET`	/api/v1/admin/users	List workspace users with roles
`GET`	/api/v1/admin/users/{userId}/data	GDPR Art. 15 — export every row referencing a user
`DELETE`	/api/v1/admin/users/{userId}/data	GDPR Art. 17 — cascade purge a user’s data
`GET`	/api/v1/admin/workspaces	Workspace details with member/agent/crew counts
`POST`	/api/v1/admin/prune-legacy-resources	Remove orphaned pre-C1 Docker resources
`GET`	/api/v1/admin/legacy-resources	Detect orphaned pre-C1 Docker resources
`GET`	/api/v1/admin/health	Read uptime, database, disk, and logging health
`GET`	/api/v1/admin/log-level	Read live and baseline log levels
`PUT`	/api/v1/admin/log-level	Change the live log level temporarily or persistently
`GET`	/api/v1/admin/rate-limits	List runtime rate-limit settings
`PUT`	/api/v1/admin/rate-limits/	Override one rate limit
`DELETE`	/api/v1/admin/rate-limits/	Reset one rate limit to its default
`POST`	/api/v1/admin/reap-orphan-containers	Detect, and optionally remove, stale-token crew containers
`POST`	/api/v1/admin/reencrypt	Re-encrypt stored envelopes to the current key version
`GET`	/api/v1/admin/security-posture	Read instance security posture and warnings
`GET`	/api/v1/audit	Paginated, filterable workspace audit log
`GET`	/api/v1/admin/memory/stats	Memory subsystem totals + per-tier/per-agent rollups
`GET`	/api/v1/admin/memory/versions	Row-level drill-down into `memory_versions`
`GET`	/api/v1/admin/memory/versions/{id}/content	Raw blob bytes for a single memory version
`GET`	/api/v1/admin/memory/config	Read per-workspace memory configuration
`PATCH`	/api/v1/admin/memory/config	Partial-merge update of memory configuration
`GET`	/api/v1/admin/keeper/requests	Keeper access-request audit log
`GET`	/api/v1/admin/keeper/requests/{requestId}/events	Append-only transition history for one request
`GET`	/api/v1/admin/journal/verify	Verify the audit journal hash-chain (tamper-evidence)
`POST`	/api/v1/internal/keeper/skill-review	F4.1 — periodic skill audit
`POST`	/api/v1/internal/keeper/behavior	F4.2 — post-tool-call behavior monitor
`POST`	/api/v1/internal/keeper/memory-health	F4.3 — periodic memory consolidation review
`POST`	/api/v1/internal/keeper/negative-learning	F4.4 — failure-event lesson capture
`GET`	/api/v1/system/setup-status	First-run bootstrap + signup gate
`GET`	/api/v1/system/telemetry	Read-only Sentry consent gate
`GET`	/api/v1/system/version	Running binary’s build identity + latest release
`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

{
  "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

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 all users in the current workspace with their roles. Required role: OWNER Request: no body. Response: JSON array shown below.

Status	Condition
`200`	Members returned.
`403`	Caller is not OWNER.

Response

[
  {
    "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"
  }
]

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`	ISO 8601 creation timestamp
`workspace`	`object?`	Workspace details (id, name, slug)
`role`	`string?`	Role in this workspace (OWNER, ADMIN, MEMBER, VIEWER)

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

{
  "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

{"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: ADMIN or OWNER (manage permission).

Request

{"level":"debug","ttl_seconds":900}

level must be a supported logging level (debug, info, warn, or error).

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 lacks `manage`.

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

{"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 and writes require ADMIN or OWNER (manage permission). Overrides apply immediately and persist until reset.

GET /api/v1/admin/rate-limits

Request: no body. Response: 200 OK with every tunable limiter.

{"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: ADMIN or OWNER (manage).

Request

{"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: ADMIN or OWNER (manage). 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: ADMIN or OWNER (manage permission). Request: no body.

Response

{
  "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

{
  "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: ADMIN or OWNER (manage permission). Request: no body.

Response

{
  "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

{
  "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.

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.

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

{
  "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/<slug>/peer-cards/alice.md",
      "bytes": 412,
      "created_at": "2026-05-01T...",
      "updated_at": "2026-05-26T..."
    }
  ],
  "memory_versions": [
    {
      "id": "mv-uuid",
      "path": "agents/<slug>/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..."
    }
  ]
}

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.

lessons.md content is not scanned for user mentions — a known gap (see GDPR guide). 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

{
  "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).

{
  "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
  }
}

On partial failure the same shape is returned with an additional "error": "<first-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 across all cascadable tables.
`scope`	`object`	Per-table count summary (extensible — new keys appear additively as new tables join the cascade).
`error`	`string?`	Present only on HTTP 207. First error encountered; consult the audit row for the full per-table picture.

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 for the operator workflow.

Workspaces

Workspace detail read, scoped to the current workspace. Requires the OWNER role.

GET /api/v1/admin/workspaces

Lists workspace details with member, agent, and crew counts. Required role: OWNER Request: no body. Response: JSON array shown below.

Status	Condition
`200`	Current workspace returned.
`403`	Caller is not OWNER.

Response

[
  {
    "id": "ws-uuid",
    "name": "Engineering",
    "slug": "engineering",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-06-15T12:00:00Z",
    "_count_members": 12,
    "_count_agents": 8,
    "_count_crews": 3
  }
]

This endpoint is scoped to the current workspace only. It does not list other workspaces in the system.

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 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

{
  "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. 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

{
  "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

{
  "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:<slug>/...` 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

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

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:<slug>/...` 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

{
  "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:<rfc3339nano>|<id> 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

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

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)

The handler refuses to follow symlinks under payload_ref. The on-disk layout is fixed at blobRoot/<sha[:2]>/<sha>; 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

{
  "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

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

{
  "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

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

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.

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

[
  {
    "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

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.

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

[
  {
    "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

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.

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 <request-id>.

Keeper Phase 2 — F4 evaluators

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):

{
  "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 <slot> — see 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:

{
  "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).
`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:

{
  "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:

{
  "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:

{
  "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:

{
  "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
}

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:

{
  "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. Trigger kinds: run_failed, guardrail_warn, guardrail_error, keeper_execute_deny. Request body:

{
  "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:

{
  "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

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.

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.

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

{
  "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

{
  "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

{
  "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.

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.

Query parameters

Param	Type	Default	Description
`metric`	string	—	Required. One of `issues_closed`, `cost_usd`, `runs_count`, `active_missions`.
`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

{
  "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

Roadmap (v0.2). The license/edition system below is on the v0.2 roadmap. v0.1 ships as fully open-source Apache-2.0 with no edition gating.

Crewship will use a three-tier licensing model that controls workspace limits and feature availability.

Editions

Edition	Description	Limits
Community	Free, default edition	15 crews, 10 agents/crew, 5 members
Team	Paid team tier	Higher limits, additional features
Enterprise	Full enterprise tier	Unlimited, all features enabled

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:

Signed format

A license file contains a JSON object with payload (the claims as a JSON string) and signature (base64-encoded Ed25519 signature).

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.

Signature verification

On startup, Crewship decodes the public key and signature from base64, then verifies the payload using ed25519.Verify().

Expiration check

If the license has an expires_at timestamp and it is in the past, the license is rejected and community defaults apply.

Fallback

If no license file exists, verification fails, or the license is expired, Crewship runs with community edition defaults.

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.

​Admin API

​Endpoints

​Stats & users

​GET /api/v1/admin/stats

​Response

​GET /api/v1/admin/users

​Response

​Instance administration

​GET /api/v1/admin/health

​Response

​GET /api/v1/admin/log-level

​Response

​PUT /api/v1/admin/log-level

​Request

​Response

​GET /api/v1/admin/legacy-resources

​Response

​Rate limits

​GET /api/v1/admin/rate-limits

​PUT /api/v1/admin/rate-limits/

​Request

​Response

​DELETE /api/v1/admin/rate-limits/

​POST /api/v1/admin/prune-legacy-resources

​Response

​POST /api/v1/admin/reap-orphan-containers

​Response

​POST /api/v1/admin/reencrypt

​Response

​GET /api/v1/admin/security-posture

​Response

​GDPR

​GET /api/v1/admin/users/{userId}/data

​Response

​DELETE /api/v1/admin/users/{userId}/data

​Request

​Response

​Workspaces

​GET /api/v1/admin/workspaces

​Response

​GET /api/v1/admin/journal/verify

​Response

​Audit log

​GET /api/v1/audit

​Query Parameters

​Response

​Memory admin

​GET /api/v1/admin/memory/stats

​Response

​Example

​GET /api/v1/admin/memory/versions

​Query Parameters

​Response

​Example

​GET /api/v1/admin/memory/versions/{id}/content

​Response

​Example

​GET /api/v1/admin/memory/config

​Response

​Example

​PATCH /api/v1/admin/memory/config

​Request Body

​Response

​Example

​Keeper

​POST /api/v1/admin/prune-crew-runtimes

​GET /api/v1/admin/keeper/requests

​Query Parameters

​Response

​GET /api/v1/admin/keeper/requests//events

​Path Parameters

​Response

​Keeper Phase 2 — F4 evaluators

​POST /api/v1/admin/keeper/review/{slot}/run

​POST /api/v1/internal/keeper/skill-review

​POST /api/v1/internal/keeper/behavior

​POST /api/v1/internal/keeper/memory-health

​POST /api/v1/internal/keeper/negative-learning

​Cross-tenant guard

​System

Admin API

Endpoints

Stats & users

GET /api/v1/admin/stats

Response

GET /api/v1/admin/users

Response

Instance administration

GET /api/v1/admin/health

Response

GET /api/v1/admin/log-level

Response

PUT /api/v1/admin/log-level

Request

Response

GET /api/v1/admin/legacy-resources

Response

Rate limits

GET /api/v1/admin/rate-limits

PUT /api/v1/admin/rate-limits/

Request

Response

DELETE /api/v1/admin/rate-limits/

POST /api/v1/admin/prune-legacy-resources

Response

POST /api/v1/admin/reap-orphan-containers

Response

POST /api/v1/admin/reencrypt

Response

GET /api/v1/admin/security-posture

Response

GDPR

GET /api/v1/admin/users/{userId}/data

Response

DELETE /api/v1/admin/users/{userId}/data

Request

Response

Workspaces

GET /api/v1/admin/workspaces

Response

GET /api/v1/admin/journal/verify

Response

Audit log

GET /api/v1/audit

Query Parameters

Response

Memory admin

GET /api/v1/admin/memory/stats

Response

Example

GET /api/v1/admin/memory/versions

Query Parameters

Response

Example

`GET /api/v1/admin/memory/versions/{id}/content`

Response

Example

GET /api/v1/admin/memory/config

Response

Example

PATCH /api/v1/admin/memory/config

Request Body

Response

Example

Keeper

POST /api/v1/admin/prune-crew-runtimes

GET /api/v1/admin/keeper/requests

Query Parameters

Response

GET /api/v1/admin/keeper/requests//events

Path Parameters

Response

Keeper Phase 2 — F4 evaluators

POST /api/v1/admin/keeper/review/{slot}/run

POST /api/v1/internal/keeper/skill-review

POST /api/v1/internal/keeper/behavior

POST /api/v1/internal/keeper/memory-health

POST /api/v1/internal/keeper/negative-learning

Cross-tenant guard

System