Agent Console
List Agent Queue Tickets
Lists tickets across every tenant for the agent console. `queue` selects which slice to return:
Queue counts
The numbers on the console's queue tabs and the sidebar badges: how many tickets sit in each queue for the calling agent right now, plus the size of the inbound-mail quarantine. Counted with the queues' own definitions and no filters, so `unassigned: 6` is exactly the six rows the Unassigned tab shows.
Get Agent Ticket
Returns one ticket for the agent console: everything a customer sees, plus the internal fields and every link (including agent-only kinds like a bug tracker reference).
Update Agent Ticket
Partially updates a ticket from the agent console — status, priority, type, visibility, group, assignee, tenant, tags, or the follow-up reminder. Only the fields present in the request are changed; each change is recorded on the ticket's timeline (see List Agent Ticket Events) and, when anything changed, the `ticket_updated` automation rules run. Changing `priority` recomputes the SLA due dates.
Assign Ticket to Me
Claims the ticket for the calling agent and takes it over from whoever held it — including the AI agent. This is Claim Agent Ticket with `force` always on: the caller becomes the owner (`assignee` and `work.owner`), the first claim ever stamps `work.picked_up_at` / `work.picked_up_by_user_id` and records a customer-visible `picked_up` event, a ticket still at the `received` stage moves to `picked_up`, an `open` ticket moves to `in_progress`, and the ticket leaves the triage queue. Taking a ticket over from the AI agent also records a `released` event (reason `take_over`). A no-op (still 200) if the ticket is already assigned to the caller. The response is the updated ticket.
Claim Agent Ticket
Makes the caller the ticket's single owner. A ticket has one owner at a time — a human agent or the AI agent — and a claim is the lock: claiming a ticket someone else owns is refused with **409** `owned_by_another_agent` (naming the current `owner`) unless `force` is sent, which takes the ticket over. The AI agent can never force; for it a 409 means 'someone else is on this — leave it'. Claiming a ticket you already own is a no-op (still 200).
Release Agent Ticket
Drops ownership: `assignee` and `work.owner` become `null`, the working state (`work.phase`, `work.active_until`) is cleared, and the ticket returns to the unassigned queue. The status and the stage are left alone. An internal `released` event is recorded with the reason. Releasing an unowned ticket is a no-op (still 200).
Send Agent Ticket Heartbeat
The owner's sign of life: marks the ticket as being worked right now (`work.working_now`) for `ttl_seconds`, and records the owner's current working phase. Send it every couple of minutes while working; when heartbeats stop, `working_now` turns false once `active_until` passes. An AI-owned ticket with no heartbeat, progress or claim for 4 hours is reported as `stale`, and released automatically after 24 hours.
Post Agent Ticket Progress
Sets the ticket's work stage and, optionally, the one-line progress update the customer sees on their ticket. A changed stage records a customer-visible `stage_changed` event ('Now: Investigating'); a progress line records a customer-visible `progress_posted` event. Any progress also counts as a sign of life for the stale check.
Hand Back Ticket to AI Agent
A human agent gives the ticket back to the AI agent with an instruction — the AI agent's next input. The AI agent becomes the owner (`assignee`, `work.owner` with `is_bot: true`), its working state starts fresh, and a ticket still at the `received` stage moves to `picked_up`. An internal `handed_back` event records the instruction; if the ticket has a shared reply draft, the draft is kept and travels with the instruction so the AI agent can build on it. The latest hand-back is returned as `work.hand_back`. The instruction is also queued for the AI agent as a `hand_back` instruction (see AI Control → Get AI Control Feed), which it picks up exactly once; `work.pending_instructions` counts it until then.
List Approval Cards
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.
List Ticket Approval Cards
Every approval card on one ticket — each version and its decision — newest version first, as a plain array (no pagination). Use it to follow how a proposal was revised: a card opened after a `decline_revise` names the card it revises in `diff_from_id`.
Open Approval Card
Opens an approval card on a ticket: a proposal a human must decide before the AI agent acts. A ticket has at most one open card — any card still pending or snoozed on the ticket is marked `superseded` (reason `new_card`). The new card gets the next per-ticket `version`. The ticket's owner gets a portal alert (and a push notification on their installed app) when they are a human; otherwise every agent who can decide cards does. No email is sent. Once the card is decided or superseded, its alerts are marked read for everyone. An internal `approval_requested` event is recorded.
Decide Approval Card
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.
Batch Decide Approval Cards
Approves several `status` cards in one go — the low-risk 'mark this resolved / close this duplicate' proposals. All or nothing: if any card is not a status card the request is refused with a 422 and nothing is decided; if any card is no longer open (already decided or superseded) it is refused with **409**, `data` carries that card, and nothing is decided. Every other kind of card must be decided one at a time with Decide Approval Card.
Consume Approval Decision
The AI agent acknowledges that it picked up a decision and is acting on it: stamps `consumed_at` on a decided card. Exactly once — a second consume is refused with **409**, so an agent that crashes and retries never acts on the same decision twice. Consuming a card nobody has decided yet (pending, snoozed or superseded) is also a 409. `data` on a 409 carries the card as it is now.
Get Approval Card File
Streams one of the files attached to an approval card — a root-cause report, an HTML mockup, a screenshot, a PDF. Use the `download_url` on the card's evidence entry, or build the path from the card id and the entry's `attachment_id`.
List Alerts
The caller's own alerts, newest first. Alerts are how the support desk tells an agent that the AI agent needs them: an approval card waiting for a decision, a reminder when it is still waiting a day later, a problem the autopilot runner reported, or an AI-owned ticket that has gone quiet. Every alert is also sent as a push notification to the agent's installed app (approval alerts respect the agent's `approval` notification switch); nothing is emailed.
Raise Alert
The AI agent's autopilot runner raises an alert for the humans: a problem with the runner itself (`runner`, e.g. its health check failed and it stopped picking up tickets) or an error on a ticket (`ai_error`). One alert is written for every active agent who can work tickets (admins and agents, never viewers), announced in real time and pushed to their installed apps.
Get Unread Alert Count
How many of the caller's alerts are unread — the number on the alert badge and the installed app's icon badge.
Mark Alert Read
Marks one of the caller's alerts read. Marking an alert that is already read changes nothing. The caller's other open sessions receive the new unread count in real time.
Mark All Alerts Read
Marks every unread alert of the caller read.
Pause AI Agent on Ticket
Pause the AI agent on one ticket. It keeps its claim but does no work on the ticket — no runs, no heartbeats, no approval cards — from its next check-in (within about two minutes) until the ticket is resumed. Instructions sent while paused are stored and run after resume. Records an internal `ai_paused` event; pausing an already paused ticket changes nothing.
Resume AI Agent on Ticket
Lift a pause: the AI agent goes back to handling the ticket normally on its next check-in, starting with any instructions queued while it was paused. Records an internal `ai_resumed` event; resuming a ticket that is not paused changes nothing.
Stop AI Agent Run
Ask the AI agent to stop the session it is running on this ticket. The agent ends the session on its next check-in, leaves an internal note saying who stopped it, and confirms with Acknowledge AI Agent Stop, which clears `work.stop_requested_at`. The ticket stays with the AI agent — pause it, take it over or turn the AI off to keep it from starting again. Records an internal `ai_stop_requested` event; a stop already waiting for the agent's confirmation is not requested twice.
Acknowledge AI Agent Stop
The AI agent confirms that the session a human stopped is gone: clears `work.stop_requested_at` and `work.stop_requested_by` and records an internal `ai_stopped` event. Does not require the AI agent to still own the ticket (it may have been released since the stop was requested). Acknowledging when no stop is pending changes nothing.
Send Instruction to AI Agent
Send the AI agent an instruction for this ticket. The agent picks it up on its next check-in (within about two minutes) and runs the ticket with the text as authoritative human input — the same weight as a reply from the customer's account manager. On a paused ticket the instruction is stored and runs after resume. Records an internal `ai_instructed` event; `work.pending_instructions` counts it until the agent picks it up.
Turn AI Agent Off for Ticket
Turn the AI agent off for one ticket: it never claims the ticket or acts on it until it is turned back on. If the AI agent owns the ticket, its claim is released (an internal `released` event with reason `ai_disabled`) and the ticket goes back to the unassigned queue; a ticket a human owns stays with them. Records an internal `ai_disabled` event; turning it off twice changes nothing. Works on any ticket.
Turn AI Agent Back On for Ticket
Make the ticket eligible for the AI agent again. It does not reassign the ticket — the agent claims it on its own if it is still unowned, or hand it back explicitly. Records an internal `ai_enabled` event; turning it on when it is already on changes nothing.
Get AI Agent Status
The AI agent's overall state: whether all AI work is paused, and what the AI agent's runner last reported.
Update AI Agent Settings
Pause or resume all AI work across the desk. While paused, the AI agent claims nothing new and starts no runs, but still honours stop requests and keeps reporting in. Resuming clears `paused_by`, `paused_at` and `reason`. No ticket event is recorded; the change is pushed on `support.agents` as `support.ai.changed`.
Send AI Runner Heartbeat
The AI agent's runner reports in: its version, the host it runs on, the sessions it is running, the size of its local queue and how much room it has. Sent on every check-in; the status reads as online for 5 minutes after the last one. A `support.ai.changed` push goes out only when the runner comes back online or its set of running sessions changes.
Get AI Control Feed
Everything the AI agent must obey on its next check-in.
Consume AI Instruction
The AI agent takes an instruction: stamps `consumed_at`. Exactly once — a second consume is refused with a **409** (`error: already_consumed`) carrying the instruction as it is now, so a runner that crashes and retries never acts on the same instruction twice.
List Autopilot Runs
Lists the AI agent's autopilot sessions on a ticket, newest first (at most 50). The AI agent reads this after a cold start to pick up its run count and the last run's outcome; the console shows it as the run history. Triage and draft suggestions are not included.
Start Autopilot Run
Records the start of an AI agent session on a ticket it owns. The run is created with `status` pending. Cite its `id` as `run_id` on any approval card the session opens, and finish it with Finish Autopilot Run.
Finish Autopilot Run
Records how an AI agent session ended. A run is finished exactly once: finishing a run that is no longer pending, or a run that is not an autopilot run on this ticket, is a **422** on `run`. Unlike starting a run, finishing does not require the AI agent to still own the ticket — a session that was running when a human took the ticket over is still recorded.
Get AI Runner Feed
The calling runner's queue: the agent ticket queue narrowed to the tickets this runner already holds or may claim under the desk's routing rules — tickets assigned to its person (unless that person picked the ticket up themselves), and, when the runner takes unassigned work and is not paused, unassigned tickets. A runner that is turned off sees only the tickets it already holds. Claiming any other ticket returns 409 (see Claim Agent Ticket), so the feed and the claim always agree.
List AI Runners
The AI routing settings page. `me` is the caller's own runner (unsaved defaults — on, assigned + unassigned — when they have never saved settings). `runners` is every runner on the team for a support admin, and just the caller's own (once saved) for anyone else.
Get My AI Runner
The caller's own runner: for a person, the runner that works for them (defaults when never saved); for an AI runner account, the runner signed in with that token — a runner uses this to check which person its token works for.
Update My AI Runner
Save the caller's own runner routing settings (the runner row is created the first time).
Update AI Runner
A support admin changes any runner's routing settings.
Triage Agent Ticket
Takes one ticket out of the triage pile. `accept` assigns it to the caller and sets it to `open`; `decline` closes it with the reason recorded on the ticket timeline, optionally sending that reason to the customer as a public reply.
Snooze Agent Ticket
Hides a ticket from every agent queue except `snoozed` (and `all`) until a moment in the future. When that moment passes the ticket is brought back automatically and an `unsnoozed` event is recorded; an agent can also bring it back early with Unsnooze Agent Ticket. Snoozing does not change the ticket's status, assignee or SLA clocks, and the hourly automation rules leave a snoozed ticket alone.
Unsnooze Agent Ticket
Brings a snoozed ticket back into the queues now: `snoozed_until` is cleared and an `unsnoozed` event is recorded on the timeline (from the previous `snoozed_until`). Nothing else on the ticket changes. Calling this on a ticket that is not snoozed is harmless — nothing is recorded and the ticket is returned unchanged.
Merge Agent Ticket
Folds this ticket (the source) into another ticket (the target) and returns the target. Everything moves to the target and the source is closed:
Split Agent Ticket
Moves some of this ticket's messages into a brand-new ticket for the same requester and tenant, and returns the new ticket. Use it when one thread turns out to hold two separate problems.
List Agent Ticket Categories
Lists the values a ticket's category can take — the same list as List Support Ticket Categories, readable without a tenant context.
Update Agent Ticket Category
Sets a ticket's category as SKU.io Support. Precedence is agent > customer > automatic: an agent's category is never overwritten by triage, and it locks the category against the customer (`locked: true`).
List Agent Ticket Messages
Returns the full thread for a ticket, oldest first, including internal notes — the customer-facing List Support Ticket Messages endpoint omits those. `kind` is `public`, `note` or `system`; `via` is one of app, email, api, automation, ai, import, agent. `mentions` lists the user ids of agents @mentioned in an internal note and is empty on every other message.
Reply to Ticket as Agent
Adds a public reply as an agent, emailed to the requester and CCs. The reply stamps `first_responded_at` when it is the first agent reply, and the built-in 'Assign first responder' automation rule assigns the ticket to the replying agent when it is unassigned (a support admin can change that rule).
List Agent Ticket Events
Returns the ticket's audit timeline, oldest first. `event` is one of: created, status_changed, priority_changed, type_changed, visibility_changed, group_changed, assigned, unassigned, replied, noted, watcher_added, watcher_removed, linked, unlinked, reopened, rated, tags_changed, tenant_changed, sla_breached, sla_warning, sla_paused, sla_resumed, ai_triaged, snoozed, unsnoozed, merged, split, mentioned, follow_up_changed, notified, rule_applied, message_deleted, picked_up, released, stage_changed, progress_posted, human_requested, requester_linked, approval_requested, approval_decided, handed_back. Each event carries the actor (null for system-generated events, with `actor_label` naming the automation, e.g. `ai` or a rule), the from/to values, and any extra metadata.
Add Internal Note
Adds an internal note to the ticket — never visible to the customer. Any active support role may leave a note, including viewers who cannot reply or change the ticket.
List Ticket Drafts
Lists every ticket that currently holds an unsent shared draft, most recently saved first — one call, so a queue can mark the tickets somebody is already writing on without asking ticket by ticket.
Get Ticket Draft
Returns the ticket's shared draft, or `{'data': null}` when the ticket has none.
Create or Replace Ticket Draft
Creates the ticket's shared draft, or replaces it — the endpoint for agents and automation writing a draft over the API. No version bookkeeping is needed: the caller may replace a draft it already holds, and the draft is attributed to the token's agent (it lights the ticket's Draft chip in the desk inbox and opens in the composer).
Save Ticket Draft
The desk composer's versioned autosave of the ticket's one shared draft, creating it when the ticket has none. Integrations and scripts should use **Create or Replace Ticket Draft** (`POST`) instead, which needs no version. The caller becomes the holder: the draft is team property, and everyone else sees who wrote it last.
Discard Ticket Draft
Discards the ticket's shared draft — it was emptied, or the agent gave up on it. The draft is shared, so this removes it for everyone. Returns 204 with no body, and is a no-op when the ticket has no draft.
Add Ticket Link
Links the ticket to an external reference — a Dev HQ issue, an error tracker event, another ticket, an internal record, or an arbitrary URL (a PR or deploy is `url`). Linking the same (kind, ref) pair again is a no-op update rather than a duplicate. Only `record` links are shown to the customer; the rest (`devhq`, `sentry`, `ticket`, `url`) are agent-only.
Remove Ticket Link
Removes a link from the ticket.
Flag Ticket as Important to Customer
Flags (or unflags) a ticket as important to the tenant that raised it. The flag weights the customer-demand count behind a linked issue (see List Issue Requesters), can be filtered and sorted on in the agent queue, and every change is recorded on the ticket timeline with the agent who made it.
List Issue Requesters
Lists every ticket linked to one Dev HQ issue key (link kind `devhq`), with the tenant and requester behind each — how much customer demand is waiting on a single piece of engineering work.
Get Ticket Customer Context
Returns who the customer behind a ticket is: the tenant (account), the requester, the people who can speak for the account, how much the account has open, its most recently touched tickets, and links out to the tenant's app and the record the ticket was raised from.
Get Customer Timeline
One customer, every ticket they raised, and a single merged history of the messages, timeline events and links on all of them — newest first. The history spans every tenant: a person who works for two accounts has one history here, matched on their user id or the requester email on the ticket. Internal notes are included and marked `internal: true`.
Search Users
Finds SKU.io users by name or email fragment, with the tenants each one belongs to — the lookup behind linking a ticket's requester to their account (Link Ticket Requester to User). Deleted users are left out. Results are sorted by name; no pagination.
Link Ticket Requester to User
Links the ticket's requester — typically someone who wrote in from another environment (beta, demo, dev) and was matched only by email — to a SKU.io user. This only sets who the requester is on this ticket; it never merges or changes user accounts. An internal `requester_linked` event is recorded.
List Saved Views
Lists the saved queue views the caller can see: their own views plus every view a colleague shared, ordered by `position` then `name`. A saved view is a named set of agent-queue filters; to run one, send its `filters` as the query parameters of List Agent Queue Tickets. No filters or pagination.
Create Saved View
Saves a set of agent-queue filters as a named view owned by the caller. Private by default; a shared view is visible to every agent but can still only be edited by its owner.
Update Saved View
Updates a saved view. Only the owner may edit a view — a shared view belonging to a colleague is visible but read-only. Every field is optional; only the fields present are changed. When `filters` is sent it replaces the whole saved filter object.
Delete Saved View
Deletes a saved view. The owner may delete any of their views; a support admin may also delete a shared view that belongs to someone else (so a departed colleague's shared views can be tidied up). A private view owned by someone else is reported as not found.
List Agent Macros
Lists the macros the calling agent may use: every shared macro plus the caller's own private ones, sorted by name. No filters or pagination. The bodies are returned with their `{{placeholder}}` tokens still in place — call Render Agent Macro to get them filled in for a specific ticket.
Render Agent Macro
Renders a macro for one ticket as the calling agent: every `{{placeholder}}` in the macro body is replaced with the ticket's, requester's, agent's and tenant's current values. Values substituted into `body_html` are HTML-escaped; `body_text` is substituted raw. The macro's `actions` are handed back untouched — rendering changes nothing on the ticket; apply the actions (and send the reply) through the normal ticket endpoints.
List Agent Directory
Lists the support agents another agent can choose from — when assigning a ticket or @mentioning someone in an internal note. By default only active seats held by super-admin users who still exist are returned; pass `include_inactive=1` to also get revoked seats, seats whose user is no longer a super admin, and seats whose user has been deleted from sku.io — all reported with `is_active: false`, since `is_active` here means the seat can actually be assigned work (active AND super admin AND not deleted). Entries are sorted by display name, case-insensitively. No pagination.
Rerun AI Triage
Re-runs the AI triage and drafted reply for a ticket from the current thread. Each call starts a new pass and does not overwrite earlier runs; the response is the latest completed run of each kind (`triage`, `draft`). A run can finish as `done`, `skipped` (a prompt-injection screen matched the ticket text and it was left for a human), `failed` — only `done` runs are returned. Nothing here reaches the customer; a drafted reply is only sent if an agent sends it.
Record AI Feedback
Records whether an agent used an AI triage or drafted reply, for the AI draft acceptance rate shown on the dashboard (see Get Agent Dashboard Metrics).
Get Ticket AI Insights
Returns the latest AI state of a ticket in one object: the triage (classification, suggested type and priority, product area, summary, questions to ask, whether the text proves a bug), the documentation sections that may answer it, and the drafted reply. A drafted reply is only ever a suggestion — it reaches the customer only when an agent sends it. Compare Rerun AI Triage, which starts a new pass; this endpoint only reads.
Search Help Docs
Searches the published help documentation for sections an agent can quote or link in a reply. The agent-side twin of Get Support Deflection Suggestions: the same search, but central (no tenant context) and documentation only — it never looks at other customers' tickets.
Get Agent Dashboard Metrics
Returns the agent dashboard numbers for a trailing window: ticket volume by source/type/priority/tenant, first-response and resolution times (median and p90) with SLA attainment, backlog age buckets and current breaches, quality (reopen rate, CSAT, AI draft share / acceptance), email quarantine and bounce counts, load (active users and open tickets per active user), per-agent open-ticket counts, and a daily trend series.
Get Daily Support Metrics
Returns the per-day metrics snapshot for one slice of the support desk over a date range — the series behind the dashboard trend charts. One point per day, oldest first; days with no snapshot are simply absent (there is no zero-filling). The snapshot is written once a night, so today's point normally appears tomorrow. For the live, windowed numbers use Get Agent Dashboard Metrics.
Get Agent Insights Pack
Builds the Support Insights evidence pack for one tenant and date range on demand — the same fixed rules, the same numbers and the same findings as the tenant's own report, without storing anything or creating a report. No AI or third-party call is made, and the same data and range always give the same `pack_sha256`.
Get Insights Redaction Rules
Returns the redaction rules that every customer-visible Support Insights text is checked against before it is shown — report findings, rendered files and outage summaries. Use them to check your own text the same way before publishing it to a tenant.
Update Pod Incident Summary
Sets or clears the summary of an outage. Every tenant hosted on the affected server sees the summary next to the outage in their Support Insights report, so it is checked against the redaction rules (see Get Insights Redaction Rules) — a match is refused with 422 naming the rule, never quoting the matched text.
List Agent Webhooks
Lists every outbound support webhook endpoint across every tenant, plus the global ones (`tenant_id` null) that receive every tenant's ticket events. Read-only: endpoints are registered and edited by the tenant through the customer webhook endpoints. The signing secret is never returned here.
List Agent Webhook Deliveries
Lists the delivery log of one outbound support webhook — every event that was (or is about to be) POSTed to it, with the exact body sent, how many attempts were made and what came back. Newest first by default. A delivery is tried up to 3 times (retries after 30 seconds, then 5 minutes) before it is marked `failed`; `ping` rows are the tenant's 'send test' deliveries and are tried once.
List Quarantined Inbound Mail
Lists the email quarantine: messages that reached the support intake but did not become a ticket or a reply. Newest first.