# 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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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](invoicing.html).