Execute a workflow transition

Moves a document to a new workflow state. Policy gates are enforced automatically.

POST/api/v1/documents/:id/workflow/transition

Authorization

workflow:writeapi key scoperequired

Required scope when calling with an API key.

document:workflow_writesession capabilityoptional

Required capability when calling with a signed-in session.

Path parameters

idstringrequired

Document ID

Example: doc_abc123

Request body

Target workflow state

reasonstringoptional

Optional reason for the transition

Example request

{
  "to": "in_review",
  "reason": "Ready for review"
}

Request

POST /api/v1/documents/:id/workflow/transition

curl -X POST "https://www.digitalstack360.com/api/v1/documents/doc_abc123/workflow/transition" \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"in_review","reason":"Ready for review"}'

Examples use a placeholder key from your environment. Store your key in $DS_API_KEY — never commit it.

Response

200 OK

{
  "data": {
    "state": "in_review",
    "available_transitions": [
      "approved",
      "draft"
    ],
    "updated_at": "2026-05-12T10:30:00.000Z"
  }
}

Errors

401

missing_auth

No credentials provided

401

invalid_api_key

API key is invalid or revoked

400

bad_request

Missing or invalid request fields

403

scope_insufficient

Key lacks the required write scope

404

not_found

Document not found

409

workflow_gate_failed

Policy gate blocked the transition

409

workflow_transition_invalid

Transition not valid from current state