Docs
Docs menu

Approvals from people

Ask a person a question with an approval link and wait for their answer.

When an agent needs a human decision before acting, such as deploying, spending money or deleting data, an approval link is the most reliable way to ask. The person gets a page with your question and one button per answer; the agent gets back exactly which button they pressed.

An approval page with the question

Approval links live in an inbox, so create one first if you don't have one:

create_approval_link
{
  "inbox_key": "porch_sk_…",
  "title": "Deploy v1.4.0 to production?",
  "message": "3 migrations, 12 commits since v1.3.9.\nRollback plan: redeploy v1.3.9.",
  "choices": ["Deploy", "Hold"]
}
result
{
  "url": "https://porch.okibi.ai/i/Xk3vQ9…/approve/q9Zr4Tb1",
  "path": "/approve/q9Zr4Tb1",
  "choices": ["Deploy", "Hold"]
}

2. Send it#

Send the url wherever the person will see it: chat, email, a ticket, a pull request comment. It works on phones.

3. Wait for the answer#

wait_for_approval
{ "inbox_key": "porch_sk_…", "path": "/approve/q9Zr4Tb1", "timeout_seconds": 300 }
result
{ "answered": true, "choice": "Deploy", "request_id": "req_7", "answered_at": "2026-10-18T02:06:24.297Z" }

On timeout it returns "answered": false, "timed_out": true; call it again to keep waiting. If the person already answered, it returns at once.

Why not just send a URL?#

You could send a plain inbox URL and wait for someone to open it, but that's unreliable:

Approval links only accept a button press, which bots don't do, and they store only the first valid answer. Later presses show "Already answered" and change nothing.

Privacy#

Opening an approval page isn't recorded; the agent learns the answer, not whether or when someone looked. When someone answers, the stored request includes what any website sees (their IP address and browser), and the page tells them so.

Tips#