Skip to main content

Send Instruction to AI Agent

POST 
/api/support/agent/tickets/:ticket/ai/instructions

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.

Required scope: support:write

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

Path parameters

  • ticket (integer) — the ticket id.

Request body

  • text (string, required, max 5000) — what the agent should do.

Response data (201)

  • id (integer)
  • ticket_id (integer)
  • kind (string) — instruct here; hand_back for an instruction written when handing the ticket back
  • text (string)
  • created_by ({id, name}, nullable)
  • created_at (ISO 8601)
  • consumed_at (ISO 8601, nullable) — when the AI agent picked it up

Refused with a 422 (error: not_ai_owned) when the AI agent does not own the ticket — use Hand Back Ticket to AI Agent instead.

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​

Created

Response Headers
    Content-Type