Skip to main content

Claim Agent Ticket

POST 
/api/support/agent/tickets/:ticket/claim

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).

Required scope: support:write

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

What a claim does: sets assignee / work.owner to the caller and starts a fresh working state (work.phase cleared, work.active_until set to now); the very first claim stamps work.picked_up_at and work.picked_up_by_user_id, which never move afterwards; a ticket still at the received stage moves to picked_up; an open ticket moves to in_progress; the ticket counts as triaged. A customer-visible picked_up event is recorded ("Picked up by Priya", or "Picked up by SKU.io Support (AI-assisted)" for the AI agent). Taking a ticket over from the AI agent also records a released event with reason take_over. Any approval card the AI agent left pending stays open for the new owner to decide.

Path parameters

  • ticket (integer) — the ticket id.

Request body (all optional)

  • force (boolean, nullable) — take the ticket over from its current owner. Ignored when the caller is the AI agent.
  • reason (string, nullable, max 500) — why it was claimed; stored on the picked_up event.

The response is the updated ticket in the agent shape (see Get Agent Ticket for every field, including work).

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.

If this ticket was merged into another ticket, the request is refused with a 422 whose merged_into (id, number) names the live ticket — send the action there instead.

Request​

Responses​

OK

Response Headers
    Content-Type