Skip to main content

List Approval Cards

GET 
/api/support/agent/approvals

The approval cards across every ticket and tenant — the work waiting on a human decision — and the AI agent's decision poll. An approval card is how the AI agent (or any agent) asks a person before acting on a ticket: send this reply, which of these options, apply this fix, change this status, or "the customer wants a person". Each ticket has at most one open card; opening a new one supersedes the last.

Required scope: support:read

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

By default the list is the cards a human still has to decide (state=pending), soonest SLA deadline first. Tickets in the trash are left out.

Filters (each also accepted as filter[<name>]):

  • state — pending (default: pending cards plus snoozed cards that are due back), decided (approved, edited, declined_revise, declined_drop, taken_over), open (pending + snoozed), all, or any state value / comma-separated list
  • kind — reply, question, fix, merge, repair, status, escalate, error; one value or a comma-separated list
  • ticket_id — cards on one ticket
  • requested_by — me or a user id
  • consumed — true / false: whether the AI agent has acknowledged the decision

Sort: sort — sla_due_at (default, ascending) or created_at; prefix with - for descending. Card id always breaks ties.

Pagination: standard pagination envelope — data plus current_page, last_page, per_page, total, from, to and the page links. per_page defaults to 10, maximum 100.

Card fields (each card in data):

  • id (integer), ticket_id (integer), ticket_number (string, e.g. #3521)
  • version (integer) — the card's per-ticket version, starting at 1. Send it back as expected_version when deciding.
  • kind (string) — one of: reply, question, fix, merge, repair, status, escalate, error; kind_label (string) — e.g. Reply ready, Needs your decision, Status change, Needs a person
  • state (string) — one of: pending, approved, edited, declined_revise, declined_drop, taken_over, snoozed, superseded
  • title (string), body (string) — what the AI agent (or an agent) is asking for, in plain text
  • confidence (string, nullable) — high, medium or low
  • payload (object) — what the card proposes: draft_body, status_after and cc[] on a reply card; choices[] ({key, label, recommended}) and allow_text on a question card; status on a status card. {} when the card carries nothing extra.
  • evidence[] — {label, url (nullable), attachment_id (nullable)}, in the order given. A file attached with the card (see Open Approval Card files[]) is an entry {label, attachment_id, filename, content_type, size (bytes), kind (html, image, pdf, text or file)}. Every entry that names an attachment also carries download_url — the relative path of Get Approval Card File (/api/support/agent/approvals/{approval}/files/{attachment}).
  • requested_by ({id, name, is_bot}) — who opened the card; decided_by ({id, name, is_bot}, nullable), decided_at (ISO-8601, nullable), decision_channel (console, email or local, nullable)
  • reason (string, nullable) — the decider's note (required on decline_revise), or why the card was superseded (new_card)
  • choice (string, nullable) — the choice key a question card was approved with; edited_body (string, nullable) — the reply the decider wrote on an edit
  • consumed_at (ISO-8601, nullable) — when the AI agent acknowledged the decision; snoozed_until (ISO-8601, nullable)
  • diff_from_id (integer, nullable) — the earlier card on the same ticket this version revises; run_id (integer, nullable) — the AI run that produced it
  • sla_due_at (ISO-8601, nullable) — the ticket's next SLA deadline: the first-response due date until the first response is sent, then the resolution due date
  • new_customer_message (boolean) — the customer wrote again after the card was opened, so it may be out of date
  • ticket ({id, number, subject, status, priority, tenant_id, requester_name, assignee_user_id}, nullable)
  • created_at, updated_at (ISO-8601)

Authentication: Bearer token with the support:read scope, or an authenticated session, from a caller with an active support role (any role, including viewer). No tenant context — this endpoint is central.

Request​

Responses​

OK

Response Headers
    Content-Type