Inbox

The inbox is the unified human-in-the-loop surface for the workspace. Rows are written by source-of-truth handlers (waitpoint create, escalation create, run-failure terminal, generic agent messages); these endpoints are the read + state-flip surface the UI consumes — no inserts (the one destructive op is an ADMIN purge). For the source endpoints that create inbox items (and the conflict rules about how items get resolved), see the Inbox guide.

All endpoints require an authenticated session and a workspace context.

Authentication and scope

The request has no authentication payload: send the session cookie or bearer token established by the normal API login flow. The server derives both user_id and workspace_id from that context. List, count, get, patch, and bulk operations apply the visibility model below; purge additionally requires the workspace OWNER or ADMIN role.

Endpoints

Method	Endpoint	Purpose
GET	`/api/v1/inbox`	List items (newest-first, with unread count)
GET	`/api/v1/inbox/count`	Unread count for the bell badge
GET	`/api/v1/inbox/{id}`	Fetch a single item (full body + payload)
PATCH	`/api/v1/inbox/{id}`	Flip an item’s state
POST	`/api/v1/inbox/{id}/act`	Act on a `run_needs_human` card: answer (resumes the run), take over, dismiss
POST	`/api/v1/inbox/bulk`	Apply one state transition to many items in a single request
DELETE	`/api/v1/inbox`	Purge items in the workspace (ADMIN only)

Visibility model

Every query restricts to:

workspace_id = <current workspace> AND (
   (target_user_id IS NULL AND target_role IS NULL)   -- workspace-wide
   OR target_user_id = <session user>                 -- addressed to me
   OR target_role    = <my workspace role>            -- addressed to my role (OWNER, ADMIN, ...)
)

An item addressed to OWNER never appears for a MEMBER, even if both belong to the same workspace. The visibility predicate is identical across List / UnreadCount / PatchState — a cross-workspace or cross-target id returns 404, not a silent no-op, so the surface can’t be probed for which items exist.

Item shape

Field	Type	Notes
`id`	string (CUID)
`workspace_id`	string	Always the current workspace.
`kind`	string	`waitpoint`, `escalation`, `failed_run`, `message`, `memory_consolidation`, `schedule_missed`, `schedule_circuit_breaker_tripped`, `webhook_fire_failed`, `automation_enqueue_failed`, `run_needs_human`. `inbox.AllKinds` is the source of truth and is CI-checked against the DB CHECK.
`source_id`	string	Source row id — e.g. waitpoint token, escalation id, pipeline run id.
`target_user_id`	string \| omitted	Set when addressed to a specific user.
`target_role`	string \| omitted	Set when addressed to a workspace role.
`title`	string	Display title.
`body_md`	string \| omitted	Markdown body for the detail panel.
`sender_type`	string \| omitted	`user` or `agent`.
`sender_id`	string \| omitted
`sender_name`	string \| omitted	Pre-joined display name.
`state`	`"unread"` \| `"read"` \| `"resolved"`	Computed for the calling user — see the “Reading is per-user” note under State transitions.
`priority`	string	`low` / `normal` / `high` / `urgent`.
`blocking`	bool	When `true`, the source flow is paused until the item is resolved.
`payload`	object \| omitted	Parsed JSON — inlined so the UI doesn’t need a second `JSON.parse`.
`thread_key`	string \| omitted	The §12 attention contract’s merge key (work package B10). Rows sharing a `thread_key` in one workspace collapse to one card server-side — see The attention contract. Omitted for a kind that hasn’t adopted the contract.
`attention_class`	string \| omitted	`decision` \| `input` \| `review` \| `repair`. Omitted for a kind that hasn’t adopted the contract.
`actions`	array \| omitted	`[{"id", "label", "effect", "irreversible"}, ...]` — the permitted actions for this row, unioned across every producer that merged into it. Omitted for a kind that hasn’t adopted the contract; fall back to the kind-specific action row in the Inbox guide.
`read_at`	RFC3339 \| omitted	Legacy, workspace-shared: the first time anyone marked this item read. Not what `state` reflects — see the “Reading is per-user” note under State transitions.
`resolved_at`	RFC3339 \| omitted
`resolved_by_user_id`	string \| omitted
`resolved_action`	string \| omitted	`approved`, `rejected`, `retried`, `cancelled` — what the human did.
`created_at`	RFC3339
`updated_at`	RFC3339
`second_approver_required`	bool \| omitted	`kind=escalation` only. Whether resolving this needs someone other than the owner of the agent that raised it.
`second_approver_by_workspace`	bool \| omitted	Because the workspace `require_second_approver` toggle is on.
`second_approver_by_tier`	bool \| omitted	Because the linked credential’s tier forces it, whatever the toggle says.
`security_level_label`	string \| omitted	The linked credential’s tier, e.g. `"L4 · critical"`.
`source_missing`	bool \| omitted	Detail read only (`GET /api/v1/inbox/{id}`), `kind` ∈ `{ waitpoint, escalation }` only. Whether the row that would decide this item is gone: `true` when no pending waitpoint token, `PENDING_REVIEW` hire or pending approval backs a waitpoint (or no `escalations` row backs an escalation), `false` when the source is live. Omitted on list rows and on every other kind — absent means “not probed”, never “live”. It is the same probe the PATCH guard runs, so it predicts whether `state: "resolved"` will be accepted or answer `409`.

The four second_approver_* / security_level_label fields are the same ones GET /api/v1/crews/{id}/escalations carries, and they are computed when the row is read — not stored on the item at raise time. Both inputs change afterwards (the workspace toggle, and the credential’s tier), so a stored answer would promise a resolve that then 403s. Omitted means the server said nothing, not that a single approver will do. When the rule applies and the raising agent has no recorded owner, the fields still say it applies, and the resolve fails closed with a 403 (“the initiating identity is unknown”) — an unknown initiator is never treated as a different person. See Keeper → The switch is a floor, not a master switch.

Reading the inbox

List visible items or fetch just the unread count for the bell badge — both share the visibility predicate above.

`GET /api/v1/inbox`

Paginated, newest-first list. The UI calls this on first load and after every WS inbox.updated event.

Query param	Type	Default	Notes
`state`	`unread` \| `read` \| `resolved` \| `active` \| `all`	`all`	Linear-Triage default — resolved items stay visible-but-dimmed. `active` returns everything not resolved (unread + read). `""` behaves like `all`. Invalid value → `400 invalid state`.
`kind`	string	(unset)	Narrows by item type.
`limit`	int	`100`	Capped at `500`.
`offset`	int	`0`	Rows to skip. Pair with `has_more` to walk the feed; `crewship inbox list --all` does exactly that. Offset paging is not stable across a mutating feed — a row that leaves the filter between two requests shifts the window and is never returned, so a full walk is exact only on a quiet workspace.

The response inlines both row count and unread count so the bell badge renders from the same fetch (no second round-trip on every poll), plus has_more so a client can tell a full page from the final page:

{
  "rows": [
    {
      "id": "ibx_01HVZ...",
      "workspace_id": "ws_01HV...",
      "kind": "waitpoint",
      "source_id": "wp_tok_abc",
      "target_role": "OWNER",
      "title": "Review production deploy",
      "body_md": "PR #128 ready for production roll-out…",
      "sender_type": "agent",
      "sender_id": "ag_01HVY...",
      "sender_name": "Daniel",
      "state": "unread",
      "priority": "high",
      "blocking": true,
      "payload": { "deploy_target": "prod-us-east-1" },
      "created_at": "2026-05-20T08:14:22Z",
      "updated_at": "2026-05-20T08:14:22Z"
    }
  ],
  "count": 1,
  "unread_count": 7,
  "has_more": false,
  "active_by_kind": { "waitpoint": 2, "escalation": 1, "failed_run": 4 },
  "decision_count": 3
}

active_by_kind is an exact per-kind count of the caller’s visible not-resolved items, independent of the request’s own state/kind filters — the dashboard’s “Needs your attention” counts come from it, because rows are a limit window (default 100) and silently plateau there. Keys are real item kinds (waitpoint, escalation, failed_run, message, memory_consolidation, run_needs_human, schedule_missed, …), and a kind with no active items has no key. The field is omitempty: it is absent when nothing is active and when the aggregate could not be computed completely, so its absence alone never means “nothing active”. decision_count is the number of active items that actually block on a person (waitpoints, actionable escalations, blocking items such as run_needs_human; source-less Keeper advisories are excluded). It is present on every successful aggregate — 0 is a real, known-empty answer — and absent only when the aggregate failed. The dashboard’s “Needs your attention” headline uses it, falling back to counting its windowed rows when it is absent.

`GET /api/v1/inbox/count`

Request: no body. Response: 200 OK with unread_count; 401 is returned without authenticated workspace context and 500 on a database failure. Bell-badge endpoint. Same visibility predicate as List, cheaper payload — no JSON parse, no payload column read.

{ "unread_count": 7 }

`GET /api/v1/inbox/{id}`

Fetch a single item with its full body and parsed payload — the detail the list view omits. Backs crewship inbox get <id> and the web detail pane. Visibility is enforced exactly like List / PATCH: an id in another workspace, or one targeted at another user/role, returns 404 (never a leak of an item you can’t see). Response: 200 OK — a single item object (same shape as one rows[] entry from List), plus the detail-only fields: the keeper evidence block, the four-eyes second_approver_* fields, and — for a waitpoint or escalation — source_missing, which says whether a source-managed row can still be decided at its source (false) or may be dismissed from the inbox (true). crewship inbox get <id> --format json passes it through unchanged.

Status	Condition
`400`	Missing `id`.
`401`	No workspace context.
`404`	Unknown id, or an id not visible to the caller.

Updating state

Flip an item between unread / read / resolved. Source-managed kinds are restricted to read — see the conflict rule below.

`PATCH /api/v1/inbox/{id}`

Response: 200 OK with the updated item state. 400 indicates an invalid state or body, 401 missing workspace context, 404 an invisible item, and 409 a source-managed item that must be resolved through its source endpoint. Flip an item’s state. The body is JSON:

{
  "state": "resolved",
  "resolved_action": "approved"
}

Field	Type	Notes
`state`	`"unread"` \| `"read"` \| `"resolved"`	Required. Invalid → `400 state must be unread\|read\|resolved`.
`resolved_action`	string	Optional. Recorded on `resolved` transitions so the audit trail captures what the user did, not just that they did something. Conventional values: `approved`, `rejected`, `retried`, `cancelled`.

Returns 200:

{ "id": "ibx_01HVZ...", "state": "resolved" }

Source-managed kinds — `409 Conflict`

For kind in { waitpoint, escalation }, the inbox row is a mirror of an authoritative source row (the waitpoint token, the escalation row). PATCH only supports state: "read" for these while that source row is live — unread and resolved would desync the inbox row from the source, because the user expects the flip to also approve the waitpoint / close the escalation, and the inbox PATCH doesn’t do that. Exception — the source is gone. state: "resolved" is accepted on a source-managed row whose backing record no longer exists, because there is no source endpoint left to drive it and the row would otherwise sit in Needs action forever. The server probes before refusing: a waitpoint is source-less when no pipeline_waitpoints token is still pending, no staged hire is in PENDING_REVIEW, and no pending approval names it as target_id; an escalation is source-less when no escalations row exists (a keeper-synthetic escalation — Skill review, memory health, behaviour verdicts — never had one). state: "unread" stays refused either way. The detail read reports the same probe as source_missing, so a client can offer the dismiss only where it will succeed. failed_run (and message) are not source-managed — they resolve freely between all three states via PATCH or the bulk endpoint, because there is no source row whose state the inbox flip would contradict. The non-read transition returns 409 with a hint at the right endpoint:

{
  "error": "use the source endpoint for this kind (e.g. /pipelines/waitpoints/{token}/approve) — inbox PATCH only supports 'read' for source-managed items",
  "kind": "waitpoint"
}

Generic kinds (message, failed_run) flip freely between all three states.

State transitions

→ read marks the item read for the calling user only: it upserts the caller’s row in inbox_item_reads (idempotent — a second “mark read” by the same user doesn’t move the timestamp). It also still sets the legacy shared read_at / read_by_user_id columns on inbox_items, first-write-wins (COALESCE’d) — but those are not what state reflects in any response; see the note below.
→ unread clears only the caller’s own row in inbox_item_reads — a role-targeted item another recipient already read stays read for them. It also clears the legacy shared read_at, read_by_user_id, resolved_at, resolved_by_user_id, resolved_action columns on inbox_items.
→ resolved sets resolved_at, resolved_by_user_id, resolved_action (and overwrites whatever’s currently set, in case the user resolved with a different action). Unlike read/unread, resolved is workspace-shared — one decision closes the item for everyone who can see it.

Reading is per-user. state in every response (GET /api/v1/inbox, GET /api/v1/inbox/{id}, and the unread_count on both) is computed for the calling user: resolved is read straight off the shared inbox_items.state (one decision closes the item for everyone), but read vs unread comes from whether the caller has a row in the per-(item, user) table inbox_item_reads. Marking an item read or unread only ever affects the caller — a role-targeted item another recipient has already read still comes back unread for you, and marking it read yourself doesn’t touch their state.The legacy read_at / read_by_user_id columns on inbox_items are kept and still written on every read/unread transition, but they now answer a narrower, separate question — “has anyone dealt with this” (useful for e.g. an operator dashboard that doesn’t care which manager looked) — and are no longer what state reports.A refreshed item — one an upsert resurrects to unread (e.g. a stale escalation re-raised) — clears every caller’s per-user read marker along with the shared columns, so it reads as unread again for everyone, including users who had read the earlier version.

Acting on a card

A run_needs_human card — raised when a run reports outcome NEEDS_HUMAN (work package B6) — carries actions a person can perform. Performing one closes the loop with the session that asked (PRD §18 scenario 15, B15): the run resumes, a receipt is written, and the same card is updated rather than a new one raised.

`POST /api/v1/inbox/{id}/act`

{ "action": "answer", "input": "Use the staging bucket, not prod." }

Field	Type	Notes
`action`	`"answer"` \| `"take_over"` \| `"dismiss"`	Required. The kind’s closed vocabulary; a card written before B15 offers only `take_over` in its `actions[]` but accepts all three.
`input`	string	Required for `answer`, ignored otherwise.

What each action does:

answer — the input is posted as a comment on the issue, authored by you, and delivered to the same agent session that asked (§10.5: “the exact session that asked, never a generic assignment”). It goes through the mention door, so B2’s exactly-once delivery and B3’s one-turn rule apply: one delivery, one run. The run resumes from its checkpoint with your answer as the next unread delta in its context pack (B5). If the session is mid-run, the delivery queues and is consumed when that run ends.
take_over — you continue the work yourself. Runs the same hold as Transfer Issue Work with action: take_over (#2448): parked routine runs are cancelled, live runs are stamped cancel_requested_at and hard-stopped, non-running assignments and open plan tasks are cancelled, pending mentions are superseded, issue_work becomes mode: human with you as worker_user_id and a bumped work_revision, and the issue moves to TODO. The agent’s session leaves awaiting_input for idle. The action’s effect reads Transfers the issue to you and pauses automatic agent work.
dismiss — no further work now. Same session transition.

Every action writes a receipt: an inbox_acted event on the issue’s event log (GET .../events, seq-ordered) naming who acted, the action, the card, the session’s agent_version (§11.6 — the routine_version analogue for an issue run) and, for an answer, the comment, delivery and run it produced. The card is resolved in place — state: resolved, resolved_action: <action>, and the same receipt merged into payload.receipt — so the thread stays one card. Response: 200 OK

{
  "id": "ibx_run_needs_human_asg_…",
  "state": "resolved",
  "action": "answer",
  "receipt": {
    "action": "answer",
    "acted_by": "usr_…",
    "acted_at": "2026-09-05T15:40:00Z",
    "inbox_item_id": "ibx_…",
    "session_id": "ses_…",
    "agent_version": 3,
    "source_run_id": "asg_… (the run that asked)",
    "comment_id": "cmt_…",
    "delivery_id": "mcm_…",
    "run_id": "asg_… (the resumed run)",
    "dispatch_state": "dispatched",
    "event_id": "act_…",
    "seq": 14
  }
}

Status	Condition
`400`	Unknown action, `answer` without input, invalid body
`401`	No workspace context
`404`	The card is not visible to the caller
`409`	Already acted on (`resolved_action` and `resolved_by_user_id` in the body); the kind has no server-side action (waitpoints and escalations are decided through their source endpoints); the run behind the card is gone; or the answer was recorded as a comment but could not be delivered (`dispatch_state`, `detail`, `comment_id` in the body — the card stays open so you can retry once the cause is fixed)

CLI: crewship inbox act <id> <action> [--input …].

Bulk state transition

Apply one state transition over many ids in a single round-trip. This backs the tree-grouped UI’s “resolve all under this routine / crew” action — instead of N PATCHes, the client sends one request and gets back a per-id breakdown.

`POST /api/v1/inbox/bulk`

Request body is JSON:

{
  "ids": ["ibx_01HVZ...", "ibx_01HW0...", "ibx_01HW1..."],
  "state": "resolved",
  "resolved_action": "approved"
}

Field	Type	Notes
`ids`	string[]	Required. Explicit id list. Empty → `400 ids required`. Duplicate / empty ids are de-duped and ignored.
`state`	`"unread"` \| `"read"` \| `"resolved"`	Required. Invalid → `400 state must be unread\|read\|resolved`.
`resolved_action`	string	Optional. Recorded on `resolved` transitions, same as PATCH.

More than 500 ids → 400 too many ids (max 500), matching the list LIMIT ceiling. Per-id visibility re-check. The server applies the inbox visibility clause per id. Ids targeted at another user or another workspace count as not_found, not an error — you cannot flip rows you can’t see, and the bulk call can’t be used to probe which ids exist. Decision-item protection (partial skip, never whole-batch fail). Decision items are skipped individually rather than failing the request:

On state: "resolved", rows are skipped when kind ∈ { waitpoint, escalation } or blocking = true (any kind) — these need their source endpoint to resolve. Same exception as PATCH: a waitpoint / escalation whose source is gone resolves rather than being skipped, so “select all → archive” does not leave the orphans behind.
On state: "unread", waitpoint / escalation rows are skipped (flipping them would desync the source).
Non-blocking message / failed_run rows resolve freely.
state: "read" is always harmless and applies to all rows.

Returns 200 with a per-id breakdown:

{ "updated": 22, "skipped": 3, "skipped_ids": ["ibx_…", "ibx_…", "ibx_…"], "not_found": 0, "state": "resolved" }

updated — rows that took the transition.
skipped / skipped_ids — rows the server refused to flip on this transition. Two reasons: source-managed kinds (waitpoint / escalation) must be resolved via their source endpoint; and blocking=true rows of any kind are left for individual handling (they have no generic source endpoint). The UI surfaces e.g. “22 resolved, 3 left open” and routes each skipped id to the appropriate action.
not_found — ids that didn’t resolve to a visible row (wrong workspace / target, or already gone).

A single inbox.updated event broadcasts for the whole batch — see the WebSocket section below.

Purge

Bulk-clear inbox rows for the whole workspace — an operator cleanup, not a per-user action. Unlike List / PATCH / bulk, purge does not apply the per-user visibility clause: it deletes the whole workspace partition regardless of who each row was targeted at. Because that’s destructive and cross-user, it’s gated on the manage role (OWNER/ADMIN).

`DELETE /api/v1/inbox`

Query param	Type	Notes
`kind`	`waitpoint` \| `escalation` \| `failed_run` \| `message`	Optional. Scopes the delete to one kind (the common case: drop the `failed_run` spam a broken routine piled up without touching pending waitpoints/escalations). Any other value → `400`. With no `kind`, every row in the workspace is deleted.

Response: 200 OK

{ "deleted": 42 }

Emits a single inbox.updated (payload { "purge": "true" }) when at least one row was deleted, so open inboxes repaint their list + bell badge.

Status	Condition
`400`	`kind` present but not one of the four valid kinds.
`401`	No workspace context.
`403`	Caller is not OWNER/ADMIN.
`500`	DB error.

WebSocket event

Every successful PATCH broadcasts on the workspace channel:

{
  "type": "inbox.updated",
  "channel": "workspace:wsp_01HVZ...",
  "payload": { "id": "ibx_01HVZ...", "state": "resolved" }
}

A bulk transition emits a single inbox.updated for the whole batch instead of one per id — but only when updated > 0 (a request that skipped everything broadcasts nothing). Its payload carries the batch markers rather than a single row id:

{
  "type": "inbox.updated",
  "channel": "workspace:wsp_01HVZ...",
  "payload": { "bulk": "true", "state": "resolved" }
}

The frontend re-fetches list + count on this event so every connected client sees the same state without polling.

​Inbox

​Authentication and scope

​Endpoints

​Visibility model

​Item shape

​Reading the inbox

​GET /api/v1/inbox

​GET /api/v1/inbox/count

​GET /api/v1/inbox/{id}

​Updating state

​PATCH /api/v1/inbox/{id}

​Source-managed kinds — 409 Conflict

​State transitions

​Acting on a card

​POST /api/v1/inbox/{id}/act

​Bulk state transition

​POST /api/v1/inbox/bulk

​Purge

​DELETE /api/v1/inbox

​WebSocket event

​See also

Inbox

Authentication and scope

Endpoints

Visibility model

Item shape

Reading the inbox

`GET /api/v1/inbox`

`GET /api/v1/inbox/count`

`GET /api/v1/inbox/{id}`

Updating state

`PATCH /api/v1/inbox/{id}`

Source-managed kinds — `409 Conflict`

State transitions

Acting on a card

`POST /api/v1/inbox/{id}/act`

Bulk state transition

`POST /api/v1/inbox/bulk`

Purge

`DELETE /api/v1/inbox`

WebSocket event

See also