Skip to main content

Approvals API

List, approve, and reject approval requests created when policies require human review.

List approvals​

GET /v1/approvals

Auth: JWT Bearer Token (reviewer or admin)

Query parameters​

ParameterTypeDescription
statusstringFilter by status: pending, approved, rejected

Example​

# All pending approvals
curl "http://localhost:3000/v1/approvals?status=pending" \
  -H "Authorization: Bearer $TOKEN"

Response​

[
  {
    "approvalId": "appr_abc123",
    "runId": "run_xyz789",
    "toolCallId": "tc_def456",
    "policyId": "pol_ghi012",
    "status": "pending",
    "reason": "Matched policy: Approve production deploys",
    "requestedAt": "2026-03-19T10:00:00.000Z",
    "resolvedAt": null,
    "resolvedBy": null,
    "decisionReason": null
  }
]

Approve request​

POST /v1/approvals/:id/approve

Auth: JWT Bearer Token (reviewer or admin)

Request body​

{
  "resolvedBy": "reviewer@company.com",
  "reason": "Reviewed the deploy config, looks safe"
}

Both fields are optional. If resolvedBy is not provided, the authenticated user is used.

Example​

curl -X POST http://localhost:3000/v1/approvals/appr_abc123/approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Approved after reviewing deploy config"}'

Reject request​

POST /v1/approvals/:id/reject

Auth: JWT Bearer Token (reviewer or admin)

Request body​

{
  "resolvedBy": "reviewer@company.com",
  "reason": "Deploy includes untested changes"
}

Example​

curl -X POST http://localhost:3000/v1/approvals/appr_abc123/reject \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Contains untested database migration"}'