Approvals - Crewship

The Harbormaster approval queue is the human-in-the-loop gate for agent actions that match a policy rule. Enqueue is internal-only — it fires from harbormaster.Gate when an agent hits a rule-matching action — so the public surface is the read + decide flow operators use to triage, approve, or deny pending requests. See the Harbormaster guide.

This queue is not where a Keeper escalation is decided. Keeper’s ESCALATE verdicts resolve through POST /api/v1/admin/keeper/requests/{requestId}/resolve (Keeper), and a human ALLOW there additionally mints the single-use consumable approval the agent presents on its retry. The rows on this page are Harbormaster’s own rule-matched actions and share no state with Keeper requests.

All endpoints require authentication and are workspace-scoped, and every endpoint on this page — reads included — additionally requires OWNER or ADMIN role (#2233). Before this, the two read endpoints were reachable by any workspace member; a request’s full payload is shown verbatim in the approval detail UI, so the read floor now matches the decide/cancel floor it always should have.

Endpoints

Method	Endpoint	Purpose
GET	`/api/v1/approvals`	List approval requests
GET	`/api/v1/approvals/{id}`	Get a single request
POST	`/api/v1/approvals/{id}/decide`	Approve or deny a request
POST	`/api/v1/approvals/reset-auto-tuning`	Reset learned auto-tuning state for a tool

Queue

Read the approval queue and inspect individual requests.

List approvals

GET /api/v1/approvals?status=pending&limit=50

Auth: OWNER or ADMIN only (#2233). 403 for any other role. Query parameters:

Param	Type	Default	Description
`status`	string	`pending`	One of `pending`, `approved`, `denied`, `timeout`, `cancelled`, `all`. `all` removes the status filter.
`limit`	integer	`50`	1-200.
`offset`	integer	`0`	Rows to skip. Pair with `has_more` to walk the queue; `crewship approvals list --all` does exactly that. Offset paging is not stable across a mutating queue — a row decided between two requests shifts the window and is never returned.

Response: 200 OK

{
  "rows": [
    {
      "id": "req_01HXYZABCDEF",
      "workspace_id": "ws_123",
      "crew_id": "crw_backend",
      "agent_id": "agt_viktor",
      "mission_id": "MIS-42",
      "requested_by": "agt_viktor",
      "kind": "destructive_op",
      "reason": "rm -rf /data/*",
      "payload": { "tool": "Bash", "args": { "command": "rm -rf /data/*" } },
      "status": "pending",
      "decided_by": "",
      "decided_at": null,
      "decision_comment": "",
      "timeout_at": "2026-04-17T11:23:41Z",
      "created_at": "2026-04-17T10:23:41Z"
    }
  ],
  "status": "pending",
  "count": 1,
  "has_more": false
}

has_more is true when more rows exist past offset + count. Row keys are snake_case, like every other endpoint. They were PascalCase until harbormaster.Request was given JSON tags: the struct was serialized straight onto the wire with its Go field names, so the API answered "ID"/"Kind"/ "CreatedAt" while the web client’s zod schema and the generated OpenAPI spec both declared snake_case. Every browser surface rejected the body and rendered an empty approvals queue; only the Go CLI worked, because encoding/json matches field names case-insensitively on decode — which is also why no Go test caught it. TestApprovals_WireShape_IsSnakeCase now asserts the emitted keys. decided_at and timeout_at are pointers — they serialize as null when unset rather than being omitted. TimeoutSecs was an in-memory-only field that leaked into responses as a constant 0; it is now json:"-" and absent (the effective deadline is timeout_at). For ?status=all, the status envelope key echoes back as an empty string (""), not "all" — the handler maps all to “no status filter” internally.

Field	Type	Description
`rows[].kind`	string	`tool_call`, `cost_threshold`, `destructive_op`, `target_environment`, `ephemeral_hire`, `autonomy_gate`, `custom`.
`rows[].status`	string	See Status values above.
`rows[].payload`	object	Tool call context (`tool`, `args`, plus any rule-specific fields). `args` doubles as the gate’s reward-tuning fingerprint (see Harbor Master → Reward-adjusted gating), so callers keep it to values stable across repeated calls; per-invocation human context (e.g. `agent_run`’s scrubbed prompt preview) rides in a sibling `review` key instead, omitted when the caller passes none. For `ephemeral_hire` it carries `inbox_item_id`, the inbox waitpoint projecting the same decision.
`rows[].timeout_at`	string?	RFC3339 deadline; the sweeper flips past-due rows to `timeout`.
`rows[].decision_comment`	string	The comment passed with the decision (`comment` in the decide body). Empty while pending.
`rows[].routine_version`	int, omitted when 0	For an `autonomy_gate` raised by a routine’s autonomy-gated schedule (§9.8, #2364): the `pipeline_versions.version` the approval was requested against — “was it the same version that then ran?”. Omitted (stored as NULL, not 0) on every approval that has nothing to do with a routine’s authored definition.

Get approval

GET /api/v1/approvals/{id}

Auth: OWNER or ADMIN only (#2233). 403 for any other role. The optional X-Workspace-ID header selects the workspace when it is not already present in the request context. Response: 200 OK — the full approval request object, with the same snake_case fields as a rows[] item from List (including decision_comment, timeout_at and, when set, routine_version). Errors:

Status	Condition
401	No workspace.
403	Not OWNER/ADMIN.
404	ID not found or belongs to another workspace.
500	Database error while loading the request.

Decisions

Approve or deny a pending request, and manage the auto-tuning model that learns from those decisions.

Decide

POST /api/v1/approvals/{id}/decide

Auth: OWNER or ADMIN only. 403 for any other role. Request body:

{
  "status": "approved",
  "comment": "reviewed with staging validation"
}

Field	Type	Required	Description
`status`	string	Yes	`approved` or `denied`. Any other value = 400.
`comment`	string	No	Free-form decision rationale. Stored in `approvals_queue.decision_comment`.

Response: 200 OK

{
  "status": "approved",
  "decided_by": "user_123"
}

Errors:

Status	Condition
400	Bad JSON, missing/invalid `status`.
401	Not authenticated.
403	Not OWNER/ADMIN.
404	Request not found.
409	Request already decided (status != `pending`), or the decision’s side effect could not be applied (see below).

The decision and its side effects are one transaction. For kind=ephemeral_hire rows the decision also flips the staged agent (approve → IDLE, deny → ghosted) and resolves the blocking inbox waitpoint. All three writes commit together or not at all.If the staged agent can no longer take that transition — it was deleted, already activated through POST /api/v1/agents/{agentId}/approve-hire, or ghosted by the TTL sweeper — the whole decision is rolled back and you get 409 staged hire is no longer decidable. The queue row stays pending and is still decidable (or will time out on its own); it is never left approved/denied against an agent that never moved.A kind=ephemeral_hire row that times out ghosts the staged agent in the same sweep, so the lapsed hire is no longer approvable through either surface until crewship rehire reopens the cycle — see Ephemeral agents.

Cancel

POST /api/v1/approvals/{id}/cancel

Withdraw a still-pending request, moving it to the cancelled status. Unlike decide, this records no approve/deny outcome — it marks the gated action moot (mission aborted, agent retired, duplicate request). Auth: OWNER or ADMIN only. 403 for any other role. Request body: optional. A bare POST cancels with no reason; a present-but-malformed body is a 400.

{ "reason": "mission aborted" }

Field	Type	Required	Description
`reason`	string	No	Free-form cancellation rationale. Stored in `approvals_queue.decision_comment`.

Response: 200 OK

{
  "status": "cancelled",
  "cancelled_by": "user_123"
}

Errors:

Status	Condition
400	Body present but malformed JSON.
401	Not authenticated.
403	Not OWNER/ADMIN.
404	Request not found.
409	Request not pending (already decided or cancelled).

Reset auto-tuning

POST /api/v1/approvals/reset-auto-tuning

Harbormaster observes operator decisions over time and auto-tunes its rule confidences (a denied request that would have auto-approved next time is a calibration signal). This endpoint resets that learned state to defaults — useful after a major change in policy or after a misconfiguration polluted the auto-tuning model. Auth: OWNER or ADMIN only. Request body: requires a non-empty tool field — the reset is scoped to a single tool’s auto-tuning state.

{ "tool": "Bash" }

Field	Type	Required	Description
`tool`	string	Yes	Tool whose rolling reward window to clear. Omitting it (or sending `""`) returns 400 `tool required`.

Response: 200 OK

{
  "tool": "Bash",
  "rows_deleted": 14,
  "workspace_id": "ws_123"
}

rows_deleted is the number of auto-tuning rows wiped for that tool. Idempotent — calling twice in a row returns rows_deleted: 0 on the second call. Errors: 400 bad JSON or missing tool; 401 not authenticated; 403 wrong role; 500 DB error. This does not affect already-decided approval rows, journal history, or the rule definitions themselves — only the per-rule confidence that drives auto-mode (async/sync/required) selection.

Journal side-effects

Every write emits a journal entry:

Action	Entry
Enqueue	`approval.requested` (info)
Decide approved	`approval.granted` (info)
Decide denied	`approval.denied` (warn)
Timeout sweep	`approval.timeout` (warn)
Cancel (agent self-withdraw)	`approval.cancelled` (notice, actor = agent)
Cancel (operator via API/CLI)	`approval.cancelled` (notice, actor = user)

See Crew Journal for payload shapes.

​Endpoints

​Queue

​List approvals

​Get approval

​Decisions

​Decide

​Cancel

​Reset auto-tuning

​Journal side-effects

​Related

Endpoints

Queue

List approvals

Get approval

Decisions

Decide

Cancel

Reset auto-tuning

Journal side-effects

Related