REST API

Helpdesk Pro adds its routes to the Grav API plugin, under /api/v1/helpdesk-pro/. The staff desk is built entirely on these routes, so anything it does, a script or an AI client can do too (see MCP). Paths below leave out the /api/v1 prefix.

Authenticate

Use any credential the API plugin accepts:

• An API key, sent as X-API-Key. Create one in Admin Next (your account, then API Keys) or on the server with bin/plugin api keys:generate --user=<username>. A key created with scopes is limited to them: give it helpdesk-pro.desk and any other helpdesk-pro.* action it needs. A key without the desk scope cannot reach any Helpdesk Pro route, even when its owner is an admin.
• A JWT from POST /auth/token, sent as X-API-Token (Admin Next does this).

Tickets created and replies written with an API key record the channel api; the same done from Admin Next record staff.

curl -k "https://example.test/api/v1/helpdesk-pro/tickets?assignee=me" \
  -H "X-API-Key: $KEY"

Who may call what

Every route needs api.access plus the permission in its row (Projects and permissions). api.super counts as every Helpdesk Pro permission.

The ticket routes marked client also answer an account that has api.access but no Helpdesk Pro permission. Such an account is a client, and gets exactly what the portal would show it: the tickets it requested or is cc'd on (and the shared tickets of projects it belongs to), public replies and public activity only, no notes, no labels and no email addresses. It may reply, mute, and mark its own request solved or reopen it. A ticket it cannot read answers 404, the same as one that does not exist.

Staff see a ticket's notes and internal activity only in projects they work. A ticket outside those projects is 404 for them too.

Conventions

• Responses wrap their payload in data. Lists are paginated with page and per_page (at most 100) and carry meta.pagination and links.
• Errors are problem details (application/problem+json) with status, title and detail. Validation errors (422) add errors: [{field, message}].
• Times are epoch seconds.
• People appear as {id, name, kind}, plus email when the caller is staff on that ticket.
• Writes send an X-Invalidates header (helpdesk-pro:tickets, helpdesk-pro:ticket:<id>, helpdesk-pro:projects, …) so Admin Next refetches what changed.
• GET /helpdesk-pro/tickets/{id} sends an ETag of the ticket's editable fields. Send it back as If-Match on PATCH to be refused with 409 when someone changed one of those fields meanwhile. New replies and notes do not change it. People and organizations work the same way.

The ticket

List rows and the detail share one form:

{
  "id": 1042, "subject": "Can't reset my password", "kind": "support",
  "project": {"id": 1, "slug": "support", "name": "Support"},
  "status": {"id": 2, "name": "Open", "category": "open", "color": "#22c55e"},
  "priority": 1, "visibility_scope": "requester", "channel": "email", "triage_state": "accepted",
  "requester": {"id": 55, "name": "Ada Lovelace", "kind": "client", "email": "[email protected]"},
  "assignee": {"id": 3, "name": "Anna", "kind": "staff"},
  "labels": [{"id": 4, "name": "billing", "color": "#f59e0b"}],
  "first_message_id": 7001, "last_public_message_id": 7010,
  "counts": {"public": 3, "attachments": 2, "notes": 1},
  "times": {"created_at": 0, "last_public_at": 0, "resolved_at": null, "closed_at": null,
            "updated_at": 0, "last_activity_at": 0, "last_requester_at": 0, "last_staff_reply_at": 0,
            "first_response_at": 0, "status_changed_at": 0, "waiting_since": null},
  "me": {"watching": true, "muted": false, "unread": true},
  "duplicate_of_id": null, "merged_into_id": null, "reopen_count": 0, "deleted": false,
  "extra": {}
}

triage_state, labels, counts.notes, the staff times, duplicate_of_id, merged_into_id, reopen_count and deleted are only there for staff who work the ticket's project. The detail adds participants and etag, and timeline when asked for.

extra carries what features and add-ons attach:

The timeline

GET /helpdesk-pro/tickets/{id}/timeline returns messages and activity interleaved, oldest first:

[
  {"type": "message", "id": 7001, "ticket_id": 1042, "visibility": "public",
   "author": {"id": 55, "name": "Ada Lovelace", "kind": "client"}, "source": "email",
   "body_html": "<p>…</p>", "body_md": "…", "stripped": false, "has_original": true,
   "edited_at": null, "created_at": 0, "attachments": []},
  {"type": "activity", "id": 301, "action": "status", "actor": {"id": 3, "name": "Anna", "kind": "staff"},
   "before": {"status_id": 1, "category": "new", "name": "New"},
   "after": {"status_id": 2, "category": "open", "name": "Open"},
   "visibility": "public", "created_at": 0}
]

visibility is public for replies and internal for notes. body_md and has_original are staff-only. attachments lists the message's files; a client gets the public files of public messages only, without api_path.

Activity action is one of created, status, priority, kind, subject, assignee, labels, project, visibility_scope, triage, merged, merged_from, participant, message_edited, message_deleted, deleted, restored, erased or fields. Clients see public activity only: resolving, closing, reopening, declining and merging.

The collision guard

When the desk sends a reply it passes based_on_message_id, the newest public message it has shown. If a newer public message exists (the client wrote in meanwhile), POST /helpdesk-pro/tickets/{id}/messages answers 409 and nothing is posted:

{"status": 409, "title": "Conflict", "detail": "The conversation has new messages since you started writing",
 "code": "thread_changed", "messages": [{"type": "message", "id": 7011, "visibility": "public", "…": "…"}]}

messages holds the new public messages in timeline form. Send again with force: true to post anyway.

Routes

Desk

The counts: triage is tickets waiting in Triage (zero unless you hold helpdesk-pro.triage); mine_needing_reply is accepted tickets assigned to you in new, open or waiting_us whose last public message came from the client; unassigned is accepted tickets in those categories with nobody assigned; by_category is live tickets per status category.

Tickets

List filters, each one value or a comma-separated "any of":

Sort by updated (default), created, priority, waiting, id or (staff, with SLA) due; order is desc (default) or asc. meta.facets counts the whole filtered set per category, assignee, project, priority, kind, label and sla; each facet ignores its own filter.

curl -k "https://example.test/api/v1/helpdesk-pro/tickets?category=new,open&assignee=me&per_page=50" -H "X-API-Key: $KEY"

Messages

visibility: public (the default) is a reply: the requester and cc'd clients read it and are emailed it. visibility: internal is a note: staff only. Clients can only reply.

curl -k -X POST https://example.test/api/v1/helpdesk-pro/tickets/1042/messages \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"body": "Fixed in 2.1.3, please update.", "status_after_id": 5}'

curl -k -X POST https://example.test/api/v1/helpdesk-pro/tickets/1042/messages \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"body": "Customer is on the legacy plan.", "visibility": "internal"}'

Participants

People

Merging, erasure, legal holds and account links are in People and privacy.

Projects

Custom fields

Routes on other pages

A quick check with curl

KEY=...   # an API key of a staff account
BASE=https://example.test/api/v1/helpdesk-pro

curl -k "$BASE/bootstrap" -H "X-API-Key: $KEY"

curl -k -X POST "$BASE/tickets" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"project_id": 1, "subject": "Printer on fire", "body": "It is hot.", "requester": {"email": "[email protected]"}}'

curl -k -X PATCH "$BASE/tickets/1" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"status_id": 2, "priority": 3}'

Related

• MCP
• Extending
• Projects and permissions