Tickets API

The Tickets API manages Eos tickets, assignment, replies, notes, and lifecycle transitions. It replaces specialized internal screen operations with stable resources.

Roles

Member and Manager clients may read tickets where the ticket module and Role permit. Manager clients may create, assign, reply, and transition tickets. Finance and HR receive access only when their configured Role policy permits the ticket object.

Ticket object

{
  "object": "ticket",
  "id": "tkt_01J8QC5XGHVWM1ZD1P7MT0JT5H",
  "number": "TKT-1042",
  "subject": "Invoice export failed",
  "description": "The accounting export stopped after authentication.",
  "status": "open",
  "priority": "high",
  "requester": {
    "name": "Alex Customer",
    "email": "alex@example.com"
  },
  "assignee_member_id": "alice@example.com",
  "project_id": "prj_01J8Q8QFXT2Y3QAD6M0MPB75GC",
  "tags": ["accounting", "export"],
  "created_at": "2026-08-22T06:00:00Z",
  "updated_at": "2026-08-22T08:30:00Z"
}

Endpoints

Method and path	Operation ID	Role	Notes
`GET /v1/tickets`	`listTickets`	Permitted Role	Filters and cursor pagination
`POST /v1/tickets`	`createTicket`	Manager	Idempotent
`GET /v1/tickets/{ticket_id}`	`getTicket`	Permitted Role	Returns ETag
`PATCH /v1/tickets/{ticket_id}`	`updateTicket`	Manager	Requires If-Match
`GET /v1/tickets/{ticket_id}/messages`	`listTicketMessages`	Permitted Role	Public replies and internal notes are typed
`POST /v1/tickets/{ticket_id}/messages`	`createTicketMessage`	Manager	Idempotent
`POST /v1/tickets/{ticket_id}/transitions`	`transitionTicket`	Manager	Workflow-aware

List tickets

Filters: status, priority, assignee_member_id, project_id, requester_email, tag, updated_since, search, limit, and after.

Create a ticket

{
  "subject": "Invoice export failed",
  "description": "The accounting export stopped after authentication.",
  "priority": "high",
  "requester": {
    "name": "Alex Customer",
    "email": "alex@example.com"
  },
  "external_id": "support-8891",
  "tags": ["accounting", "export"]
}

Required header: Idempotency-Key. external_id is unique per API Client.

Add a reply or internal note

{
  "type": "reply",
  "body": "We reconnected the accounting provider and restarted the export.",
  "attachments": ["file_01J8QCKAFBV4QW33KX7D3WMS0A"]
}

type is reply or internal_note. Eos validates attachment access and preserves the API Client as author.

Transition status

{
  "transition": "resolve",
  "resolution": "Provider connection restored"
}

Supported transitions come from the ticket workflow. Unsupported direct status assignments return INVALID_TRANSITION.

Common errors

TICKET_NOT_FOUND, EXTERNAL_ID_CONFLICT, INVALID_ASSIGNEE, INVALID_TRANSITION, ATTACHMENT_NOT_AVAILABLE, and STALE_RESOURCE.

Next: Invoicing API.