REST API

List tickets. Scope is applied automatically: staff see tickets assigned to them or their groups; users see only their own tickets. Admins default to their own work queue and can broaden scope with the scope parameter.

Query parameters

Response

A JSON array of tickets. There is no envelope and no total count — page with limit and offset, and stop when a page comes back shorter than limit.

[
  {
    "id":              "9f1c2d84-5b6e-4a10-9c33-1f0e7b2a4d55",
    "tracking_number": "GHD-2026-000001",
    "subject":         "Laptop won't power on",
    "description":     "My ThinkPad X1 stopped...",
    "category_id":     "3a7e...",
    "type_id":         "5c21...",
    "priority":        "high",
    "status_id":       "b0d4...",
    "reporter_user_id":"77aa...",
    "created_at":      "2026-04-05T09:00:00Z",
    "updated_at":      "2026-04-05T09:00:00Z"
  }
]

Optional fields are omitted when unset rather than sent as null: type_id, item_id, assignee_user_id, assignee_group_id, reporter_user_id, guest_email, guest_name, guest_phone, resolution_notes, resolved_at, closed_at.

Names are not expanded. A ticket carries category_id and status_id, not a nested category or status object — resolve them against GET /api/v1/categories and GET /api/v1/statuses.

Create a new ticket. Returns the created ticket with HTTP 201.

Request body

{
  "subject":     "Laptop won't power on",        // required, 200 chars max
  "description": "My ThinkPad X1 stopped...",    // required
  "category_id": "3a7e...",                      // required
  "type_id":     "5c21...",                      // optional
  "item_id":     "8b93...",                      // optional
  "priority":    "high",                         // optional, default "medium"
  "guest_email": "sam@example.com",              // optional; makes this a guest ticket
  "guest_name":  "Sam Ortiz",                    // required when guest_email is set
  "guest_phone": "+1 555 0100",                  // optional
  "custom_fields": { "asset_tag": "X1-4471" }    // optional
}

Priority values are lower-case: critical, high, medium, low. A value that is present but not one of these is a 400.

guest_email must be a single bare address — no display name, one address only. From v1.2.0 it is validated and normalised; anything else is a 400.

Not usable yet. This endpoint requires a session, and an authenticated caller's guest fields are discarded rather than stored, so no guest ticket can currently be created. Tracked as issue #154.

Get a single ticket by UUID or tracking number. The response is the ticket on its own — replies are a separate request.

Response

{
  "id":               "9f1c2d84-5b6e-4a10-9c33-1f0e7b2a4d55",
  "tracking_number":  "GHD-2026-000001",
  "subject":          "Laptop won't power on",
  "description":      "My ThinkPad X1 stopped...",
  "category_id":      "3a7e...",
  "type_id":          "5c21...",
  "priority":         "high",
  "status_id":        "b0d4...",
  "assignee_user_id": "12ab...",
  "reporter_user_id": "77aa...",
  "resolution_notes": "Replaced the power adapter.",
  "resolved_at":      "2026-04-05T10:30:00Z",
  "created_at":       "2026-04-05T09:00:00Z",
  "updated_at":       "2026-04-05T10:30:00Z"
}

There is no sla_deadline on the ticket and no nested category, type, submitter or assignee object — only the ids. tracking_number is always present.

A tracking number works anywhere {id} is accepted, so /api/v1/tickets/GHD-2026-000001 and /api/v1/tickets/<uuid> reach the same ticket. There is no separate lookup endpoint, and no unauthenticated one: the same authentication and the same visibility rules apply either way. A ticket you may not see is reported as not found rather than refused, so tracking numbers cannot be probed for existence.

Update a ticket. All fields are optional — only included fields are modified (partial update).

Request body

{
  "status_id":          "b0d4...",   // change status
  "assignee_user_id":   "12ab...",   // assign to a staff member
  "assignee_group_id":  "44cd...",   // or to a group
  "clear_assignee":     true,        // unassign; see below
  "category_id":        "3a7e...",   // reclassify
  "type_id":            "5c21...",
  "item_id":            "8b93..."
}

Priority is not editable here. It is set when the ticket is created.

clear_assignee exists because an omitted key and an explicit null arrive identically, so there is no way to say "assign this to nobody" with the two assignee fields alone. Send {"clear_assignee": true}.

Mark a ticket Resolved. Requires Staff or Admin role. The ticket transitions to the system Resolved status and the reopen window starts.

{ "notes": "Replaced the power adapter. Confirmed working." }

Manually reopen a Resolved or Closed ticket. Staff and Admin only. The ticket transitions back to New.

{ "reason": "User says the issue has recurred." }  // optional

Permanently close a Resolved ticket. Admin only. Bypasses the reopen window — closes the ticket immediately rather than waiting for the window to expire. Returns the updated ticket.

List all replies on a ticket in chronological order. Internal notes are included only for Staff and Admin. For User or guest access, only public replies are returned.

Response

[
  {
    "id":              "6d2f...",
    "ticket_id":       "9f1c...",
    "author_id":       "12ab...",
    "body":            "I've ordered the replacement part.",
    "internal":        false,
    "notify_customer": true,
    "created_at":      "2026-04-05T11:00:00Z"
  }
]

The flag is internal, not is_internal. author_id is omitted for a reply with no author. There is no edited_at and no nested author object.

Add a reply or internal note to a ticket.

If the ticket is Resolved, the authenticated user is a User or guest, and they are within the reopen window, the ticket is automatically reopened and the reply is saved.

If internal is true, the request requires Staff or Admin. A User receives 403. An internal note never triggers a customer notification, whatever notify_customer says, and its body is not included in the webhook event either.

{
  "body":            "The replacement arrives Thursday morning.",
  "internal":        false,
  "notify_customer": true       // optional, defaults to true
}

List the canned responses in scope for this ticket — global templates, plus any scoped to the ticket's category, or category and type. Requires Staff or Admin role; returns 403 for a User or guest, since only staff compose replies with canned responses.

List all linked tickets for the given ticket.

[
  {
    "source_id": "9f1c...",
    "target_id": "4e77...",
    "link_type": "related_to"
  }
]

A link carries ids only; fetch the target ticket separately for its subject or status.

Create a link between two tickets. The reverse link is created automatically. Requires Staff or Admin role.

{
  "target_id": "4e77...",
  "link_type": "related_to"
}

Valid link_type values: related_to, parent_child (the source is the parent), caused_by (the source was caused by the target), duplicate_of. There is no parent_of or child_of — direction is carried by which ticket is the source.

Returns HTTP 201 with both the forward and reverse link objects.

Remove a link. The reverse link on the target ticket is also removed. Requires Staff or Admin role.

List all categories. Returns a flat list; types and items are not nested.

[ { "id": "3a7e...", "name": "Hardware", "sort_order": 1, "active": true } ]

List types for a category. Returns an empty array if the category has no types.

List items for a type. Returns an empty array if the type has no items.

List all ticket statuses, including system and custom statuses, in their configured sort order.

[
  { "id": "b0d4...", "name": "New",         "kind": "system", "color": "#64748b", "sort_order": 1, "active": true, "ticket_count": 12 },
  { "id": "c1e5...", "name": "In Progress", "kind": "custom", "color": "#2563eb", "sort_order": 2, "active": true, "ticket_count": 4  },
  { "id": "d2f6...", "name": "Resolved",    "kind": "system", "color": "#16a34a", "sort_order": 3, "active": true, "ticket_count": 31 },
  { "id": "e3a7...", "name": "Closed",      "kind": "system", "color": "#475569", "sort_order": 4, "active": true, "ticket_count": 88 }
]

The field is kind — system or custom — not is_system.

Authenticate with email and password. Sets an HttpOnly session cookie on success.

If MFA is enrolled, the session is created in a pending state and the response body includes "mfa_required": true. The session is not fully authenticated until POST /api/v1/auth/local/mfa/verify succeeds.

// Request
{ "email": "alex@example.com", "password": "hunter2" }

// Response — no MFA
{ "user": { "id": "...", "name": "Alex Chen", "role": "staff", "mfa_enrolled": false } }

// Response — MFA enrolled
{ "mfa_required": true }

Complete MFA verification after a successful password login. Accepts a 6-digit TOTP code or a recovery code. On success, the session is promoted to fully authenticated.

// TOTP code
{ "code": "123456" }

// Recovery code
{ "code": "AAAA-BBBB" }

Destroy the current session. The session cookie is cleared. Returns HTTP 204 with no body.

OAuth2 client credentials flow. Exchange a client_id and client_secret for a short-lived JWT (1 hour).

// Request
{ "grant_type": "client_credentials", "client_id": "...", "client_secret": "..." }

// Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type":   "Bearer",
  "expires_in":   3600
}

Use the token as Authorization: Bearer <access_token>. Create OAuth2 client credentials from Admin → Settings → OAuth2 Clients.

Returns SAML Service Provider metadata XML. No authentication required. Import this URL into your IdP. Only available when SAML_ENABLED=true.

Get the currently authenticated user's profile.

{
  "id":           "12ab...",
  "email":        "alex@example.com",
  "display_name": "Alex Chen",
  "role":         "staff",
  "mfa_enabled":  true,
  "disabled":     false,
  "created_at":   "2026-01-15T08:00:00Z",
  "updated_at":   "2026-03-02T11:20:00Z"
}

The name field is display_name, and the MFA flag is mfa_enabled.

Change the authenticated user's password. Minimum 8 characters. Returns 204.

Every other session for this user is destroyed and the calling session is re-issued — changing your password is how you evict someone holding the old one, so the other sessions have to die, but signing yourself out of the tab you just used would be a bug. The current password is not required, because reaching this endpoint already means holding a valid session for the account.

{ "password": "a-new-password" }

Begin MFA enrollment. Returns a TOTP provisioning URI and a base64-encoded QR code PNG. Enrollment is not active until confirmed with POST /api/v1/me/mfa/enroll/confirm.

{
  "totp_uri": "otpauth://totp/Open%20Help%20Desk:alex%40example.com?secret=BASE32SECRET&issuer=...",
  "qr_code":  "data:image/png;base64,..."
}

Confirm MFA enrollment by submitting the first TOTP code from the authenticator app. On success, MFA is activated and recovery codes are returned. Store the recovery codes immediately.

// Request
{ "code": "123456" }

// Response
{ "recovery_codes": ["AAAA-BBBB", "CCCC-DDDD", "EEEE-FFFF", "GGGG-HHHH", "IIII-JJJJ",
                     "KKKK-LLLL", "MMMM-NNNN", "OOOO-PPPP"] }

List the current user's API keys. The key value is never returned after creation — only the name and metadata.

{
  "data": [
    { "id": "9f1c...", "name": "monitoring-script", "created_at": "2026-03-01T00:00:00Z", "last_used_at": "2026-04-05T08:00:00Z" }
  ]
}

Create a new API key. The token field in the response is the plaintext token and is returned only once. Store it immediately.

// Request
{ "name": "monitoring-script" }

// Response — HTTP 201
{ "id": "9f1c…", "name": "monitoring-script", "token": "3f8a…" }

Revoke an API key immediately. Returns HTTP 204. Any in-flight requests using this key will receive 401 Unauthorized after revocation.