Approval Workflows

Approval workflows let you require one or more sign-offs before a post can be published. Posts that enter an approval workflow are blocked from publishing until every required step is approved. A rejected step sends the post back to DRAFT for edits.

Base URL

https://api.voxburst.io/v1

How It Works

1. A workspace owner creates a workflow with one or more ordered steps. Each step names a role label and a list of approver user IDs.
2. When a post is ready for review, call POST /v1/posts/:id/start-approval (or the workflow can be triggered automatically based on workspace settings).
3. The post status moves to PENDING_APPROVAL. Approvers are notified.
4. Each approver calls POST /v1/posts/:id/approve or POST /v1/posts/:id/reject.
5. When the final step is approved, the post status moves to APPROVED. If a scheduledFor time was set, an EventBridge schedule is created automatically. Otherwise the post remains APPROVED and must be published manually.
6. A rejection at any step resets the post to DRAFT for edits.

Post status transitions

DRAFT → (start approval) → PENDING_APPROVAL
                           ↓ approved (final step)
                           APPROVED → SCHEDULED (if scheduledFor set)
                                    → PUBLISHED (if immediate publish)
                           ↓ rejected
                           DRAFT

Workflow Structure

{
  "name": "Content Review",
  "steps": [
    {
      "order": 1,
      "role": "Editor",
      "approverIds": ["user_abc", "user_def"],
      "required": true
    },
    {
      "order": 2,
      "role": "Legal",
      "approverIds": ["user_xyz"],
      "required": true
    }
  ]
}

List Workflows

GET /v1/workspaces/:workspaceId/approval-workflows

curl https://api.voxburst.io/v1/workspaces/ws_abc/approval-workflows \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Create Workflow

POST /v1/workspaces/:workspaceId/approval-workflows

curl -X POST https://api.voxburst.io/v1/workspaces/ws_abc/approval-workflows \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Content Review",
    "steps": [
      { "order": 1, "role": "Editor", "approverIds": ["user_abc"], "required": true }
    ]
  }'

Update Workflow

PUT /v1/workspaces/:workspaceId/approval-workflows/:workflowId

Replaces the full workflow definition. To reorder steps, submit the full updated steps array.

Start Approval on a Post

POST /v1/posts/:id/start-approval

Begins the approval process for a post using the specified workflow. The post status moves to PENDING_APPROVAL.

curl -X POST https://api.voxburst.io/v1/posts/post_abc123/start-approval \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "workflowId": "wf_abc123" }'

Get Approval Status

GET /v1/posts/:id/approval-status

Returns the current step, who has approved so far, and whether the post is still pending.

curl https://api.voxburst.io/v1/posts/post_abc123/approval-status \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Approve a Post

POST /v1/posts/:id/approve

Approves the current pending step. Only users listed in that step’s approverIds can approve. If this is the final step, the post moves to APPROVED.

Request body (optional):

curl -X POST https://api.voxburst.io/v1/posts/post_abc123/approve \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "comment": "Looks great — approved!" }'

Reject a Post

POST /v1/posts/:id/reject

Rejects the current step. The post is reset to DRAFT.

Request body:

curl -X POST https://api.voxburst.io/v1/posts/post_abc123/reject \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "comment": "Please shorten the caption and remove the third hashtag." }'

Approval History

GET /v1/posts/:id/approval-history

Returns the full lifecycle of a post: approval steps taken, publish results, and status transitions — in chronological order.

Pending Queue

GET /v1/approval-queue/items

Returns all posts with an active approval workflow in the workspace. Use GET /v1/approval-queue/pending-count to get a quick unread badge count.

Step Status Values

Error Codes