Skip to main content

​
How it works

End-to-end flow: your automation creates an approval, teammates are notified (for example via push on mobile), someone responds in the web dashboard or mobile app, and your automation receives the outcome—either by callback or by polling. The sequence diagram below shows the mobile path; responding in the browser uses the same API behind the scenes.

​
Sequence

​
Steps in plain language

  1. Create — Your automation sends POST /v1/approvals with question, context, and options. timeout is optional on REST: omitted values are filled from the agent’s dashboard defaults; you can override part or all of timeout per request if needed. MCP exposes request_human_approval and create_approval for the same create (no timeout in tool args—only those defaults apply). request_id is optional (the API can assign a UUID); include your own when you need a stable id for idempotent retries. See the Agent API for the exact JSON.
  2. Notify — Subscribers may get a push on mobile; if no subscribers are configured for the agent, the service may fall back to all workspace members (see Agent settings). Anyone with access can also open the web dashboard or mobile app and see pending work.
  3. Respond — One person resolves the approval by choosing an option or entering custom text (in the browser or on a device).
  4. Deliver — If you provided a callback URL, the service POSTs the final result there. Otherwise your automation polls GET /v1/approvals/:requestId/result until the result is no longer pending.
  5. Expire — If time runs out, the request expires according to the timeout mode you set.

​
Resolved result (polling)

When the result is ready, the polling endpoint returns JSON including fields such as:
  • request_id, agent_id, correlation_id (if set)
  • status
  • selected_option_index, selected_option_label when an option was chosen
  • custom_instruction when used
  • resolved_by, resolved_at
Full field list and error codes: Agent API.