Skip to main content
When an agent reaches a step that needs human sign-off, it pauses and creates an approval record. Operators review the action and its payload, then approve or deny. The agent resumes or stops based on the decision. By the end of this page you will know which endpoints exist, the status values an approval moves through, and the consequences of denial. Approval endpoints live at root /v1/approvals — they are not workspace-scoped in the URL path. A token with approvals:read or approvals:write can act on records from any workspace the token has access to.
To see which agent produced an approval, use the agent_id field on the record and cross-reference Agents.

​
An approval in shape

action and payload are agent-defined — interpretation is whatever the agent’s configuration says they mean.

​
Endpoints

List pending and historical approval records. Fetch a single approval record. Approve the requested action — the run resumes. Deny the requested action — the run stops.

​
Status values

​
Filtering and pagination

GET /v1/approvals accepts status (one of pending, approved, denied — omit for all), limit (default 20, max 100), and cursor. See Pagination for cursor mechanics.
Denying an approval stops the run permanently. The agent does not retry the step or continue to later steps. To re-run the task, trigger the agent again after addressing the underlying issue.

​
Common errors

Agents

Manage the agents that produce approval records.