Waitpoints - Crewship

Waitpoints are durable approval/external-completion pauses created by a routine wait step. Tokens are opaque capabilities; do not expose them in logs.

List pending waitpoints

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

Requires workspace authentication and membership. The response is an array (maximum 200) of objects:

Field	Type	Description
`token`	string	The waitpoint’s opaque capability — what `approve` and the external route take
`pipeline_run_id`	string	The parked run
`step_id`	string	The `wait` step
`kind`	string	The wait kind (`approval`, …)
`prompt`	string	The prompt shown to the decider
`invoking_crew_id`	string?	Omitted when empty
`timeout_at`	string	When the wait expires
`created_at`	string	When the run parked
`decision_form`	object?	The typed decision form the step declared (see Typed decisions). Omitted when the step has none
`inbox_item_id`	string?	The inbox card that carries this waitpoint. Omitted when none was written
`callback_url`	string?	The public token-authenticated completion endpoint (below). Only present when the step has no `decision_form` — a typed decision has to be made through the authenticated route, so nothing outside the workspace is handed a way to complete it

A database failure is 500.

Who may decide

Every completing route goes through one resolve door (B14, #2388, PR #2394) that derives the decider from the request’s auth, never from the body:

a session or CLI-token principal is a person — the inbox, the routine page, crewship routine waitpoints approve|reject;
the holder of the token on the external route is external (recorded as external-callback);
an agent’s internal token is an agent, and the door refuses it: 403 {"error": …, "reason": "waitpoint_decider_not_allowed"}. The waitpoint is untouched and the attempt is written to the audit log as waitpoint.decision_refused (crewship audit --action waitpoint.decision_refused). A request with no principal at all is refused the same way. In practice an agent never reaches the authenticated route — internal tokens are 401 there — but the door checks the kind regardless, so a future agent-facing route cannot quietly become a way for a peer agent to say “go”.

Approve or deny from the inbox

POST /api/v1/workspaces/{workspaceId}/pipelines/waitpoints/{token}/approve
Content-Type: application/json

{"approved": true, "comment": "Reviewed"}

The body is optional; absent approved means false on this authenticated route. comment is optional and is stored as the decision payload. This is an update/MANAGER+ operation. A successful response is {"ok":true,"approved":true|false} and resumes the parked run for either decision. Missing tokens are 400; malformed JSON is 400; an expired/already-decided token is 409; an unauthenticated caller is 401, a role below MANAGER 403, and an agent or principal-less caller 403 with reason: waitpoint_decider_not_allowed (see above); an unavailable waitpoint store is 503; and completion failures are 500.

Complete from an external service

POST /api/v1/waitpoint-tokens/{token}
Content-Type: application/json

{"approved": true, "payload": {"ticket": "INC-42"}}

This route has no JWT: the high-entropy token is the authentication. The body is optional and approved defaults to true (unlike the authenticated approve route). payload accepts any JSON and is stored for the resumed step. It returns {"ok":true,"approved":true|false}; an empty token is 400, an already-decided or expired token is 409, malformed JSON is 400, an unavailable or non-completing waitpoint store is 503, and other completion failures are 500.

​List pending waitpoints

​Who may decide

​Approve or deny from the inbox

​Complete from an external service

List pending waitpoints

Who may decide

Approve or deny from the inbox

Complete from an external service