## Tickets (`tickets`)

Admins handle user tickets: list, details, replies, internal notes, closing and reopening.

Authentication: Admin only · Docs: https://www-sa2.kuxitong.com/en/docs/api/tickets

### GET `/api/v2/tickets`

List tickets · Authentication: Admin only

Query parameters:

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer |  | Page number, starting from 1 Default: 1 |
| `page_size` | integer |  | Items per page Default: 20 |
| `status` | string |  | Tab: open, replied or closed; omit for all. Values: ["open","replied","closed"] |
| `tenant_id` | integer |  | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
| `q` | string |  | Search: digits match the ticket number exactly, otherwise a title substring. |
| `urgent` | boolean |  | Only urgent (true) or only normal (false). |
| `category` | string |  | Filter by category (site, cert, security, l4, billing, other); comma-separated for several. |
| `site_id` | integer |  | Filter by the related site or forwarding rule id. |
| `created_from` | string |  | Created at or after. |
| `created_to` | string |  | Created before. |

```sh
curl "https://panel.example.com/api/v2/tickets" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/tickets`

Create a ticket on behalf of a user · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `body` | string | Yes | Body, at most 2000 characters. |
| `category` | string | Yes | Category: site, cert, security, l4, billing or other. Values: ["site","cert","security","l4","billing","other"] |
| `image_ids` | integer[] |  | Image ids uploaded via POST /ticket-images, at most 5, unused and uploaded by the caller. |
| `notify` | boolean |  | Whether to notify the user (in-site message plus subscriptions per reminder settings); default true, false creates silently. |
| `rel_id` | integer |  | Related object id; 0 for none. |
| `tenant_id` | integer | Yes | Submitting user (tenant) id. |
| `title` | string | Yes | Title, at most 60 characters. |
| `urgent` | boolean |  | Whether urgent. |

```sh
curl -X POST "https://panel.example.com/api/v2/tickets" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/tickets/{id}`

Get a ticket · Authentication: Admin only

```sh
curl "https://panel.example.com/api/v2/tickets/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PATCH `/api/v2/tickets/{id}`

Update ticket urgency or category · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `category` | string |  | Category: site, cert, security, l4, billing or other. Values: ["site","cert","security","l4","billing","other"] |
| `urgent` | boolean |  | Whether urgent. |

```sh
curl -X PATCH "https://panel.example.com/api/v2/tickets/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/tickets/{id}/close`

Close a ticket · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `note` | string |  | Optional last staff reply, at most 2000 characters. |
| `notify` | boolean |  | Whether to notify the user (in-site message plus subscriptions per reminder settings); default true, false creates silently. |

```sh
curl -X POST "https://panel.example.com/api/v2/tickets/{id}/close" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/tickets/{id}/notes`

Add an internal note · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `body` | string | Yes | Body, at most 2000 characters. |

```sh
curl -X POST "https://panel.example.com/api/v2/tickets/{id}/notes" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/tickets/{id}/reopen`

Reopen a ticket · Authentication: Admin only

```sh
curl -X POST "https://panel.example.com/api/v2/tickets/{id}/reopen" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/tickets/{id}/replies`

Staff reply · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | string |  | wait_user, close or none; default wait_user. Values: ["wait_user","close","none"] |
| `body` | string |  | Body, at most 2000 characters. |
| `image_ids` | integer[] |  | Image ids uploaded via POST /ticket-images, at most 5, unused and uploaded by the caller. |

```sh
curl -X POST "https://panel.example.com/api/v2/tickets/{id}/replies" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

Tickets object:

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | string |  | wait_user, close or none; default wait_user. Values: ["wait_user","close","none"] |
| `author_avatar_ver` | integer |  | The author's avatar version, increases on every upload; omitted when there is no avatar or no author_id. |
| `author_id` | integer |  | The author's user id, used to fetch the avatar. Admin side: set on user / staff / note messages; user side: only on the user's own messages (staff and system rows never carry it, so no admin identity leaks). |
| `author_name` | string |  | Author name. Admin side: the user or admin name; user side: always the generic support name for staff and system rows. |
| `auto_close_at` | string |  | When the ticket will be auto-closed: set only while waiting for the user and auto-close is on (reply time plus the configured days, recomputed after settings change); otherwise empty. |
| `body` | string | Yes | Body, at most 2000 characters. |
| `can_rate` | boolean |  | User side only: closed or awaiting confirmation, not rated and rating enabled (decides whether the resolve dialog shows the rating section). |
| `can_reopen` | boolean |  | User side only: closed and still within the reopen window. |
| `category` | string |  | Category: site, cert, security, l4, billing or other. Values: ["site","cert","security","l4","billing","other"] |
| `close_reason` | string |  | Close reason: user, staff or timeout; empty while not closed. Values: ["","user","staff","timeout"] |
| `closed_at` | string |  | Time the ticket was closed; empty while open. |
| `created_at` | string |  | Created at |
| `created_by_admin` | boolean |  | Submitted by an admin on the user's behalf; admin side only. |
| `event` | string |  | Event of a system row: urgent, category, closed, reopened, timeout, reply (a reply changed the status; from/to are the old/new status), submitted, submitted_for (submitted by an admin on behalf of the user; to is the user name); empty otherwise. Values: ["","urgent","category","closed","reopened","timeout","reply","submitted","submitted_for"] |
| `from` | string |  | Previous value of a system row. |
| `id` | integer |  | Ticket number. |
| `image_ids` | integer[] |  | Image ids uploaded via POST /ticket-images, at most 5, unused and uploaded by the caller. |
| `images` | TicketImage[] |  | Attached images. |
| `kind` | string |  | user, staff, note (admin only) or system. Values: ["user","staff","note","system"] |
| `last_at` | string |  | Time of the last message or status change. |
| `last_kind` | string |  | Sender of the last message: user, staff, or empty when none. The user-side list prefixes staff messages with a label. Values: ["","user","staff"] |
| `last_snippet` | string |  | Snippet of the last user or staff message (whitespace collapsed, at most 80 characters, ellipsis when cut); internal notes and system rows excluded; empty when none. |
| `messages` | TicketMessage[] |  | Messages by id ascending; the user side has no notes. |
| `msg_count` | integer |  | Number of user and staff messages (including the initial description; internal notes and system rows excluded). |
| `new_count` | integer |  | Messages from the other side after read_pos. |
| `note` | string |  | Optional last staff reply, at most 2000 characters. |
| `notify` | boolean |  | Whether to notify the user (in-site message plus subscriptions per reminder settings); default true, false creates silently. |
| `rating` | string |  | Rating: good, normal, bad, or empty if not rated. Values: ["","good","normal","bad"] |
| `rating_enabled` | boolean |  | User side only: the rating switch from ticket settings (when off, the resolve dialog hides the rating area). |
| `rating_note` | string |  | Rating note. |
| `read_pos` | integer |  | This side's read position before opening (a message id). |
| `rel_id` | integer |  | Related object id; 0 for none. |
| `rel_name` | string |  | Related object name (snapshot at submit time). |
| `rel_type` | string |  | Related object type: site, stream or empty. Values: ["","site","stream"] |
| `reopen_until` | string |  | User side only: when closed, the reopen deadline. |
| `status` | string |  | open, replied or closed. Values: ["open","replied","closed"] |
| `tenant_id` | integer |  | Submitting user (tenant) id. |
| `title` | string |  | Title, at most 60 characters. |
| `to` | string |  | New value of a system row. |
| `unread` | integer |  | Messages from the other side not read yet. |
| `urgent` | boolean |  | Whether urgent. |
| `user` | object |  | Submitting user; admin side only. |
| `user_name` | string |  | Submitting user's name; admin side only. |
