Skip to main content

​
Tutorial: Your first approval

This tutorial ties together creating an approval from an automation and resolving it as a human, then getting the result back to your workflow.

​
What you need

  • Agent ID and workspace API key from the web dashboard or mobile app (Credentials).
  • Base URL for the Agent API.
  • Permission to open Approvals on the web or Approval Inbox on mobile.

​
1. Create an approval

Send POST {BASE_URL}/v1/approvals with headers:
  • X-Agent-Id — your agent UUID
  • X-Api-Key — your workspace key
  • Content-Type: application/json
Body fields must match Agent API: POST /v1/approvals: question, context_markdown, and options are required. timeout is optional—the server merges your agent’s default timeout when you omit it. request_id is optional (the API assigns a UUID if you omit it). You can use curl, the Quickstart “custom” snippet, n8n, or Zapier. Save the response if you need approval_id or timing fields; for polling, use the request_id returned in the create response (whether you supplied one or not).

​
2. Respond as a human

  1. Open Approvals in the web dashboard, or the Approval Inbox / agent inbox on mobile.
  2. Open the pending request, read the question and context, then choose an option or enter custom text if allowed.
Only one resolved outcome wins if several people view the same request.

​
3. Get the result to your automation

Pick one:
  • Callback — If you set callback.url on create, the service POSTs the final JSON when the approval resolves. Point it at a reachable webhook (for example in n8n).
  • Polling — Call GET {BASE_URL}/v1/approvals/{requestId}/result where {requestId} is the request_id from the create response. Repeat until status is no longer pending.
Field details: Agent API.