Skip to main content

​
Why it matters

For high-impact actions (payments, account changes, deletions), approve prevents automatic execution until a human approves.

​
Create a gated action

curl -X POST http://localhost:3000/v1/actions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/refunds",
    "body": { "refund_id": "rf_123", "amount": 2500 },
    "approve": true
  }'
Initial status is awaiting_approval.

​
Four approval paths

Agent calls approve tool after explicit human confirmation.
Your app receives action events via callback, prompts a reviewer, then calls approve/cancel via API.
Backend or operator console calls POST /v1/actions/{id}/approve.

​
Incompatibility with sync: true

approve: true cannot be combined with sync: true. Synchronous mode blocks the request until the action completes — that’s incompatible with waiting for a human decision. Attempting both returns a 400 with error code invalid_sync. 
# This returns 400
curl -X POST http://localhost:3000/v1/actions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "...", "approve": true, "sync": true }'
# → { "error": "invalid_sync", "message": "Cannot use sync with approve: true — sync cannot wait for human approval" }

​
Rejecting an action

Reject by cancelling while in awaiting_approval: 
curl -X POST http://localhost:3000/v1/actions/<act_id>/cancel \
  -H "Authorization: Bearer <API_KEY>"

​
End-to-end conversation example

User: Send a $5,000 vendor payout to ACME.
Agent: This action requires approval. Should I send it for review?
User: Yes.
Agent: Action created: act_abc123 (awaiting_approval).
Reviewer: Approved.
Agent (MCP -> approve): Action act_abc123 approved and now pending delivery.
Agent: Payout dispatch has started. I'll report completion status.