Human Approval

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

1) Magic-link email

Pass notify: { email: "approver@example.com" } when creating the action. SafeFetch sends an email with approve and reject buttons. Clicking approve or reject takes no additional setup — it resolves the action and redirects to the receipt page.

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,
    "notify": { "email": "approver@example.com" }
  }'

Requires RESEND_API_KEY to be set in your environment. If unset, the action is still created but no email is sent.

2) In-conversation via MCP

Agent calls approve tool after explicit human confirmation.

3) Callback notification path

Your app receives action events via callback, prompts a reviewer, then calls approve/cancel via API.

4) Direct API approval call

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.

Getting Started

CLI

Core Concepts

Guides

Templates

MCP Server

Why it matters

Create a gated action

Four approval paths

Incompatibility with `sync: true`

Rejecting an action

End-to-end conversation example

​Why it matters

​Create a gated action

​Four approval paths

​Incompatibility with sync: true

​Rejecting an action

​End-to-end conversation example

Why it matters

Create a gated action

Four approval paths

Incompatibility with `sync: true`

Rejecting an action

End-to-end conversation example