Approvals

Approval requests are created automatically when a workflow run reaches an approval step. The run pauses until a human submits a decision through the API. Decisions can approve, reject, or edit the content before continuing.

List Approval Requests

GET /v1/approval-requests

Returns all approval requests in your workspace. Use the pending query parameter to filter for requests that still need a decision.

Query Parameters

Parameter	Type	Default	Description
`pending`	`string`	--	Filter by pending status: `true` for undecided requests, `false` for decided requests

Example Request

# List all pending approval requests
curl "https://api.stevora.dev/v1/approval-requests?pending=true" \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": [
    {
      "id": "apr_abc123",
      "workflowRunId": "wfrun_def456",
      "stepRunId": "srun_ghi789",
      "stepName": "review-email",
      "contentKey": "welcomeEmail",
      "content": {
        "subject": "Welcome to Acme Corp!",
        "body": "Dear Jane, we are thrilled to have you on board..."
      },
      "prompt": "Review the generated welcome email before sending",
      "decision": null,
      "decidedBy": null,
      "decidedAt": null,
      "createdAt": "2026-04-02T12:00:05.000Z"
    }
  ]
}

Error Responses

Status	Code	Cause
401	`AUTH_ERROR`	Missing or invalid API key

Decide on an Approval Request

POST /v1/approval-requests/:id/decide

Submits a decision for a pending approval request. Once decided, the workflow run resumes automatically.

Path Parameters

Parameter	Type	Description
`id`	`string`	The approval request ID

Request Body

Field	Type	Required	Description
`decision`	`string`	Yes	One of: `approved`, `rejected`, `edited`
`editedContent`	`object`	No	Replacement content (required when decision is `edited`)
`decidedBy`	`string`	No	Identifier of the person making the decision

Example: Approve

curl -X POST https://api.stevora.dev/v1/approval-requests/apr_abc123/decide \
  -H "x-api-key: stv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approved",
    "decidedBy": "jane@acme.com"
  }'

Example: Edit and Approve

curl -X POST https://api.stevora.dev/v1/approval-requests/apr_abc123/decide \
  -H "x-api-key: stv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "edited",
    "editedContent": {
      "subject": "Welcome aboard, Jane!",
      "body": "Hi Jane, welcome to Acme Corp. We look forward to working with you."
    },
    "decidedBy": "manager@acme.com"
  }'

Example: Reject

curl -X POST https://api.stevora.dev/v1/approval-requests/apr_abc123/decide \
  -H "x-api-key: stv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "rejected",
    "decidedBy": "manager@acme.com"
  }'

Response `200 OK`

{
  "success": true,
  "data": {
    "id": "apr_abc123",
    "workflowRunId": "wfrun_def456",
    "stepRunId": "srun_ghi789",
    "stepName": "review-email",
    "decision": "approved",
    "decidedBy": "jane@acme.com",
    "decidedAt": "2026-04-02T12:10:00.000Z",
    "createdAt": "2026-04-02T12:00:05.000Z"
  }
}

Error Responses

Status	Code	Cause
400	`VALIDATION_ERROR`	Invalid `decision` value or missing required fields
401	`AUTH_ERROR`	Missing or invalid API key
404	`NOT_FOUND`	Approval request not found or belongs to another workspace
409	`CONFLICT`	Approval request has already been decided

Decision Types

Decision	Behavior
`approved`	The content is accepted as-is. The workflow continues with the original content.
`rejected`	The content is rejected. The workflow step fails (retry policy may trigger re-generation).
`edited`	The reviewer provides replacement content via `editedContent`. The workflow continues with the edited version.

Approvals

On this page