Outcomes and confirmations
done, confirm, awaiting_approval and suggested: what each means and how to continue.
A call returns one of four outcomes, named by status.
| Status | HTTP | Meaning |
|---|---|---|
done | 200 | It ran. The result is under output; actionId names the logged action. |
confirm | 202 | A person must confirm first. Nothing has happened yet. |
awaiting_approval | 202 | An approver must approve first. Nothing has happened yet. |
suggested | 202 | A draft was saved for someone to review in the app. |
Refusals use the error envelope instead.
Confirmations
When an operation would email people, spend money or do something permanent, the first call returns a review:
{
"status": "confirm",
"confirmation": {
"id": "pa_…",
"operation": "outreach.send",
"status": "pending",
"expiresAt": "2026-11-07T12:30:00Z",
"review": { "summary": "Email 12 people about Senior Backend Engineer from jane@acme.com" }
}
}Show review.summary to the person. If they agree, send the same request again (same input, same
Idempotency-Key) with the confirmation id:
{ "input": { … }, "confirmation": "pa_…" }A confirmation is bound to that exact input. If the input changes, or it expires, you get 409 conflict and a new
review. Never confirm on a person's behalf.
Approvals
awaiting_approval means the action waits for someone with approval rights in the app, for example when Autopilot
asks before acting. Poll the same request later, or read approvals.
Replays
Repeat a finished write with the same Idempotency-Key and body and you get done again with the first run's result.
Replays omit candidate content from output; the replay field carries the ids and codes you need.