Approvals API
Human-in-the-loop approval workflows — list, approve, and deny pending agent actions.
When the Gate API returns a require_approval decision, the agent is paused and an approval request is created. The Approvals API lets your team review the pending action, inspect its parameters, and approve or deny it. Once a decision is made, the agent resumes or aborts accordingly.
GET /api/approvals
/api/approvals
List approval requests. Defaults to returning only pending items. Use the ?status= query parameter to filter by status: pending, approved, denied, expired. Supports ?agent_id=, ?page=, and ?limit=.
Response
{
"approvals": [
{
"approval_id": "apr_abc123",
"agent_id": "customer-support-bot",
"action": "send_customer_email",
"parameters": {
"to": "customer@example.com",
"subject": "Your refund"
},
"risk_level": "MEDIUM",
"status": "pending",
"requested_at": "2026-04-06T14:23:11Z",
"expires_at": "2026-04-06T14:28:11Z"
}
],
"total": 3,
"page": 1
}| Field | Type | Description |
|---|---|---|
approval_id | string | Unique identifier for this approval request |
action | string | The tool or action awaiting approval |
parameters | object | Tool call parameters for review |
risk_level | string | LOW, MEDIUM, HIGH, CRITICAL |
expires_at | string (ISO 8601) | If no decision is made by this time, the action is blocked |
GET /api/approvals/{approval_id}
/api/approvals/{approval_id}
Retrieve a specific approval request by its ID. The agent runtime polls this endpoint after receiving a require_approval gate decision, waiting for status to transition from pending to approved or denied.
Response schema is the same as a single item in the GET /api/approvals list, plus approved_by, approved_at, and note fields once a decision has been made.
POST /api/approvals/{approval_id}/approve
/api/approvals/{approval_id}/approve
Approve the pending action. The agent resumes execution immediately after a successful approval. The decision, approver identity, and optional note are persisted in the audit log.
Request body
{
"approver": "admin@company.com",
"note": "Verified — correct customer, correct refund amount"
}Response
{
"approval_id": "apr_abc123",
"status": "approved",
"approved_by": "admin@company.com",
"approved_at": "2026-04-06T14:24:33Z",
"action_executed_at": "2026-04-06T14:24:34Z"
}| Field | Type | Description |
|---|---|---|
approver | string | Identity of the person approving (email or user ID) |
note | string | Optional justification, stored in the audit log |
action_executed_at | string | Timestamp when the agent's tool call was executed post-approval |
POST /api/approvals/{approval_id}/deny
/api/approvals/{approval_id}/deny
Deny the pending action. The agent receives a block response and the tool call is not executed. The reason field is surfaced to the agent so it can communicate the outcome to the end user.
Request body
{
"approver": "admin@company.com",
"reason": "Wrong recipient address"
}| Field | Type | Description |
|---|---|---|
approver | string | Identity of the person denying |
reason | string | Required. Reason for denial, stored in audit log and returned to the agent. |
GET /api/approvals/audit
/api/approvals/audit
Full audit log of all approval decisions across all agents. Returns both approved and denied decisions with full context. Useful for compliance reporting and security reviews.
Query parameters
| Parameter | Type | Description |
|---|---|---|
agent_id | string | Filter by agent |
status | string | Filter by status: approved, denied, expired |
from | ISO 8601 | Start of time range (inclusive) |
to | ISO 8601 | End of time range (inclusive) |
page | integer | Page number (default: 1) |
limit | integer | Results per page (default: 50, max: 500) |
expires_at, the action is blocked by default. You can change this behavior with on_timeout: allow in your gate policy — but this is not recommended for production environments where high-risk actions require explicit sign-off.