Approvals API Endpoints for human-in-the-loop approval workflows — list, create, poll, and resolve approvals.
The approvals API powers Veto's human-in-the-loop (HITL) workflow. When a policy requires human review, an approval record is created and the SDK polls until a human resolves it.
HITL requires the Team plan or above.
List all pending approvals for the current organization.
Header Required Description X-Veto-API-Key or AuthorizationYes API key or Bearer JWT
{ "data" : [ { "id" : "apr_abc123def456" , "toolName" : "transfer_funds" , "arguments" : { "amount" : 5000 , "to" : "vendor-123" }, "status" : "pending" , "expiresAt" : "2025-01-15T10:35:00Z" , "createdAt" : "2025-01-15T10:30:00Z" } ] } Create an approval request manually. Useful for triggering HITL outside the normal validation flow.
Header Required Description X-Veto-API-Key or AuthorizationYes API key or Bearer JWT Content-TypeYes application/json
{ "decisionId" : "d7f2a1b3-4c5e-6f78-9a0b-1c2d3e4f5a6b" , "toolName" : "transfer_funds" , "arguments" : { "amount" : 5000 , "to" : "vendor-123" }, "expiresInSeconds" : 3600 } Field Type Required Description decisionIdstring (UUID)No Link to an existing decision record toolNamestringYes Name of the tool awaiting approval argumentsobjectNo Tool call arguments for reviewer context expiresInSecondsnumberNo TTL in seconds (60–86400, default: 3600)
{ "id" : "apr_abc123def456" , "toolName" : "transfer_funds" , "status" : "pending" , "expiresAt" : "2025-01-15T11:30:00Z" , "createdAt" : "2025-01-15T10:30:00Z" } Poll an approval record. The SDK calls this automatically — you do not need to call it directly.
Header Required Description X-Veto-API-Key or AuthorizationYes API key or Bearer JWT
Parameter Type Description idstringThe approval ID
{ "id" : "apr_abc123def456" , "status" : "pending" , "toolName" : "transfer_funds" , "arguments" : { "amount" : 5000 , "to" : "vendor-123" }, "createdAt" : "2025-01-15T10:30:00Z" , "expiresAt" : "2025-01-15T10:35:00Z" } { "id" : "apr_abc123def456" , "status" : "approved" , "toolName" : "transfer_funds" , "resolvedBy" : "user@company.com" , "resolvedAt" : "2025-01-15T10:31:15Z" } { "id" : "apr_abc123def456" , "status" : "denied" , "toolName" : "transfer_funds" , "resolvedBy" : "user@company.com" , "resolvedAt" : "2025-01-15T10:31:15Z" } { "id" : "apr_abc123def456" , "status" : "expired" , "toolName" : "transfer_funds" , "expiresAt" : "2025-01-15T10:35:00Z" } Field Type Description idstringApproval record ID status"pending" | "approved" | "denied" | "expired"Current status toolNamestringName of the tool awaiting approval argumentsobject?Tool call arguments (included while pending) resolvedBystring?Who resolved the approval resolvedAtstring?ISO 8601 timestamp of resolution createdAtstring?ISO 8601 timestamp of creation expiresAtstring?ISO 8601 timestamp of expiration
Resolve a pending approval — approve or deny.
Header Required Description X-Veto-API-Key or AuthorizationYes API key or Bearer JWT Content-TypeYes application/json
Parameter Type Description idstringThe approval ID to resolve
{ "action" : "approve" , "resolvedBy" : "user@company.com" } Field Type Required Description action"approve" | "deny"Yes Resolution action resolvedBystringYes Identifier of the person resolving
{ "id" : "apr_abc123def456" , "status" : "approved" , "resolvedBy" : "user@company.com" , "resolvedAt" : "2025-01-15T10:31:15Z" } Status Code Description 404 not_foundApproval ID does not exist 410 expiredApproval has already expired 400 invalid_statusApproval is already resolved
The SDK handles polling automatically. The flow:
Validate endpoint returns { decision: "require_approval", approval_id: "apr_..." }
SDK fires the onApprovalRequired / on_approval_required hook
SDK polls GET /v1/approvals/:id every 2 seconds (configurable)
When status changes from pending, SDK returns the decision to the agent
If the poll exceeds the timeout (default 5 minutes), SDK throws ApprovalTimeoutError
Agent calls tool │ ▼ SDK validates with cloud ──── allow ──── Tool executes │ ├── deny ──── ToolCallDeniedError │ └── require_approval │ ▼ Fire onApprovalRequired hook │ ▼ Poll GET /v1/approvals/:id │ ┌──────┼──────┐ │ │ │ approved denied expired/timeout │ │ │ Tool runs Error Error
