Skip to main content

Decide Approval Card

POST 
/api/support/agent/approvals/:approval/decide

Records a human decision on a card, at the version the decider saw. The card must still be open (pending or snoozed) and at expected_version; if someone else decided it first, a newer version replaced it, or it was superseded, the request is refused with 409 and data carries the card as it is now — so you can show who decided it and how, rather than deciding twice.

Required scope: support:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Actions

  • approve — go ahead as proposed. A question card is approved with one of its own choice keys, or — when it allows free text — with an answer in text.
  • edit — reply cards only: approve with your own wording in edited_body, which also replaces the ticket's shared reply draft.
  • decline_revise — send it back with a reason in text (at least 5 characters) so the AI agent revises and opens a new version.
  • decline_drop — do not do this at all.
  • take_over — the decider takes the ticket over (as a forced claim) and handles it personally.
  • snooze — hide the card for snooze_hours (1–72). It comes back as pending when the snooze ends, or earlier if the ticket's SLA falls due within the hour.

The card's state becomes approved, edited, declined_revise, declined_drop, taken_over or snoozed. An internal approval_decided event is recorded, and the AI agent picks the decision up from List Approval Cards and acknowledges it with Consume Approval Decision.

Path parameters

  • approval (integer) — the card id.

Request body

  • action (string, required) — one of: approve, edit, decline_revise, decline_drop, take_over, snooze
  • expected_version (integer, required, min 1) — the card version you are deciding
  • choice (string, optional, nullable, max 40) — the choice key when approving a question card
  • text (string, nullable, max 5000) — required for decline_revise (min 5 characters); otherwise an optional note, or the free-text answer to a question card. Stored as the card's reason.
  • edited_body (string, nullable, max 65000) — required for edit
  • snooze_hours (integer, nullable, 1–72) — required for snooze
  • channel (string, optional, nullable) — where the decision was made: console (default), email or local

The response is the decided card (fields as in List Approval Cards).

Authentication: Bearer token with the support:write scope, or an authenticated session, from a caller with an active support role that can work tickets (the viewer role is read-only). No tenant context — this endpoint is central.

Request​

Responses​

OK

Response Headers
    Content-Type