Tickets tickets
Admins handle user tickets: list, details, replies, internal notes, closing and reopening.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/ticketsList tickets
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
status | string | Tab: open, replied or closed; omit for all. |
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. |
/api/v2/ticketsCreate a ticket on behalf of a user
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
bodyRequired | string | Body, at most 2000 characters. |
categoryRequired | string | Category: site, cert, security, l4, billing or 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_idRequired | integer | Submitting user (tenant) id. |
titleRequired | string | Title, at most 60 characters. |
urgent | boolean | Whether urgent. |
/api/v2/tickets/{id}Get a ticket
Authentication: Admin only
/api/v2/tickets/{id}Update ticket urgency or category
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
category | string | Category: site, cert, security, l4, billing or other. |
urgent | boolean | Whether urgent. |
/api/v2/tickets/{id}/closeClose a ticket
Authentication: Admin only
Request body application/json
| Field | Type | 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. |
/api/v2/tickets/{id}/notesAdd an internal note
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
bodyRequired | string | Body, at most 2000 characters. |
/api/v2/tickets/{id}/reopenReopen a ticket
Authentication: Admin only
/api/v2/tickets/{id}/repliesStaff reply
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
action | string | wait_user, close or none; default wait_user. |
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. |
Tickets object
| Field | Type | Description |
|---|---|---|
action | string | wait_user, close or none; default wait_user. |
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. |
bodyRequired | string | 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. |
close_reason | string | Close reason: user, staff or timeout; empty while not closed. |
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. |
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. |
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. |
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. |
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. |
reopen_until | string | User side only: when closed, the reopen deadline. |
status | string | open, replied or 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. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}