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

Answer an approval

curl -s "$SAI_API_URL/v1/agents/approve" \
  -H "Authorization: Bearer $SAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "approvalId": "ap_7Qw", "response": "yes" }'

For a choice question:

Answer a choice question

curl -s "$SAI_API_URL/v1/agents/approve" \
  -H "Authorization: Bearer $SAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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`.

Response

200 OK · Approval answeredJSON

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

status is approved, approved_task or denied.

Errors

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.

Gotchas

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.