Tickets

Tickets are the core resource in Helpdesk. Each ticket represents a customer support request.

The ticket object

Attribute	Type	Description
id	string	Unique identifier (e.g. tkt_abc123)
subject	string	Ticket subject line
status	string	new, open, pending, resolved, closed
priority	string	low, normal, high, urgent
type	string	question, incident, problem, task
assigneeId	string | null	ID of the assigned agent
requesterEmail	string	Email of the customer who created the ticket
requesterName	string	Name of the customer
tags	array	List of tag strings
customFields	array	Custom field values (see below)
createdAt	string	Creation time (ISO 8601 UTC)
updatedAt	string	Last update time (ISO 8601 UTC)

Custom field values

Each entry in the customFields array has:

Attribute	Type	Description
id	string	The custom field definition ID
value	mixed	The field value, typed according to the field definition

List tickets

GET /helpdesk/api/v1/tickets

Returns a cursor-paginated list of tickets.

Query parameters

Parameter	Type	Required	Description
status	string	no	Filter by status
priority	string	no	Filter by priority
assignee_id	string	no	Filter by assignee
page_size	integer	no	Results per page (default: 25, max: 100)
after	string	no	Cursor for next page
sort_by	string	no	created_at, updated_at, status, priority (default: created_at)
sort_order	string	no	asc or desc (default: desc)

Response

{
  "tickets": [ ... ],
  "meta": { "pageSize": 25, "hasMore": true },
  "links": { "next": "/api/v1/tickets?after=..." }
}

Retrieve a ticket

GET /helpdesk/api/v1/tickets/:id

Response

{
  "ticket": { ... }
}

Create a ticket

POST /helpdesk/api/v1/tickets

Requires write permission.

Request body

{
  "ticket": {
    "subject": "Cannot log in",
    "status": "new",
    "priority": "high",
    "type": "incident",
    "requesterEmail": "customer@example.com",
    "requesterName": "Jane Doe",
    "assigneeId": "usr_abc123",
    "tags": ["billing", "urgent"],
    "customFields": [
      { "id": "cf_abc", "value": "Enterprise" }
    ]
  }
}

Field	Type	Required	Description
subject	string	yes	Subject line
status	string	no	Defaults to new
priority	string	no	Defaults to normal
type	string	no	Defaults to question
requesterEmail	string	no	Customer email
requesterName	string	no	Customer name
assigneeId	string	no	Agent to assign
tags	array	no	Tag strings
customFields	array	no	Custom field values ({ id, value })

Response

Returns 201 Created with the ticket object. Dispatches a ticket.created webhook event.

Update a ticket

PUT /helpdesk/api/v1/tickets/:id

Requires write permission.

Request body

{
  "ticket": {
    "status": "pending",
    "priority": "urgent",
    "assigneeId": "usr_xyz789",
    "tags": ["escalated"],
    "customFields": [
      { "id": "cf_abc", "value": "Pro" }
    ]
  }
}

All fields are optional. Only provided fields are updated. Dispatches ticket.updated (and ticket.assignment.changed if assignee changes) webhook events.

Delete a ticket

DELETE /helpdesk/api/v1/tickets/:id

Requires write permission. Returns 204 No Content. Dispatches a ticket.deleted webhook event.

Error codes

Code	Status	Description
BAD_REQUEST	400	Request body missing ticket object
VALIDATION_ERROR	422	Required field missing or invalid
NOT_FOUND	404	Ticket not found