API reference

Approve

POST /v1/agents/approve

Answers a pending approval that has isLinkOnly: false. The task continues as soon as the answer lands.

Request

json

{ "approvalId": "ap_7Qw", "response": "yes" }

For a choice question:

json

{ "approvalId": "ap_9Lm", "response": "yes", "selections": [["desktop"]] }

Field	Type	Required	Notes
`approvalId`	string	yes	From the `data-approval-request` event.
`response`	string	yes	`yes`, `no` or `task`. `task` allows this and the rest of the current task.
`selections`	string[][]	for choices	One inner array per question, in order. Values from `questions[i].options[].value`.

json

{ "ok": true, "status": "approved" }

status is approved, approved_task or denied.

Status	Body
`404`	`{ "error": "Approval request not found." }`
`409`	`{ "error": "link_only", "message": "This approval must be completed in a browser. Open approvalUrl.", "approvalUrl": "https://sai.simular.ai/approval/3fA9kQ2xYz/ap_2Vd?from=api" }` when `isLinkOnly` is `true` and the approval is still pending. Open the URL in a browser instead.
`409`	`{ "error": "Approval request is no longer pending." }` when it was already answered or expired.
`422`	A selection problem: a missing group, more than one pick on a single-select question, or a value that was not offered.
`429`	More than 20 calls in a minute.

A choice approval with response: "yes" and no selections is recorded as a deny. Always send selections for approvalType: "choice".
selections on a non-choice approval returns 422.
Read isLinkOnly before calling. Link-only approvals cannot be answered here.

Note

The 409 link_only body with approvalUrl is available from October 1. Today's staging returns a bare 400.