Workflow + Approvals API

Stories move through configurable workflow stages (e.g. draft → in-review → published). Each transition is permission-checked, optionally requires N approvals from authorized reviewers, and is recorded in an immutable audit log.

Workflow stages

GET    /v1/spaces/{slug}/workflow-stages
POST   /v1/spaces/{slug}/workflow-stages
PATCH  /v1/spaces/{slug}/workflow-stages/{id}
DELETE /v1/spaces/{slug}/workflow-stages/{id}

Stages are space-scoped and ordered via position. Each carries:

Field	Purpose
key	machine name (draft, review, published)
label	human display name
position	ordering
required_approvals	how many distinct reviewers must approve before next stage
can_publish	terminal stage that flips the Story's status to published
allowed_role	minimum role that may initiate this transition

Transitions

POST /v1/spaces/{slug}/stories/{uuid}/transitions

Body:

{
  "to_stage": "review",
  "message": "Headline reworked, ready for editorial."
}

Response: 200 { workflow_stage_id, history_entry_id } on success; 422 { error: "stage_not_reachable" } if the destination doesn't follow the configured graph; 403 if your role lacks the allowed_role.

Approvals

POST /v1/spaces/{slug}/stories/{uuid}/approvals

Reviewers post one approval each. Once required_approvals is hit, the transition completes automatically.

DELETE /v1/spaces/{slug}/stories/{uuid}/approvals/{approval_id}

Revoke an approval before the threshold is reached.

History (audit log)

GET /v1/spaces/{slug}/stories/{uuid}/workflow-history

Returns the full transition trail: who, when, from, to, message, approval count. Never deleted, never edited — RBAC ensures only the viewer+ role can read.

See also

• /api/stories — story CRUD
• /api/collab — presence + comments
• Audit log — system-wide event trail