Features

What you get

• REST API (OpenAPI 3.0) for tickets, replies, notes, links, attachments, customers, categories, users, knowledgebase, and canned replies
• Staff portal at the API host: sign in with HESK credentials, mint and revoke tokens, open Swagger UI
• Password → token exchange (POST /v1/auth/token) for automation
• Live /openapi.json rewritten for this install’s public URL and branding
• Health check at /health (no auth)

Tickets

• List with filters: status, category, owner, priority, track id, full-text q, archived
• Get / create / update / delete by numeric id or tracking id
• Staff replies and internal notes
• Status, priority, category, owner, due date
• Collaborators and followers
• Related-ticket links (the same bidirectional table the HESK staff UI uses)
• Create and reply with attachments (multipart or JSON base64)
• Attach files to internal notes (staff comments), not only the ticket opening message: POST /v1/tickets/{id}/notes with files, or POST /v1/tickets/{id}/notes/{noteId}/attachments
• Optional customer/staff email notifications via HESK’s own templates (notify: true|false)

Attachments

• Upload to a ticket, an existing reply, or an internal note
• Download and delete
• Limits (size, count, types) follow HESK settings — GET /v1/attachments/limits

Identity and access

• Token = staff user. Admins can mint tokens for any staff account.
• Secrets stored as SHA-256 hashes; only a short prefix is kept for lookup
• Privileges catalog: GET /v1/privileges
• Status and priority maps, including custom HESK statuses
• Per-token / per-IP rate limiting (configurable)

Customers, knowledgebase, canned replies

• List / create / update customers (including product-style routing identities)
• Knowledgebase categories and articles (CRUD where privileged)
• Canned replies

Customization

Every install is meant to be yours:

Area	How
HESK path and public URLs	config.local.php or installer flags
Portal name and vendor footer	branding
REST prefix	api_prefix
Token prefix, TTL, max per user	token
CORS origins	cors
Rate limits	rate_limit
Pagination	pagination
Logging / debug	log, debug
Table prefix	Inherited from HESK db_pfix
TLS / vhost / PHP-FPM	Sample nginx config you copy and edit

Full knob list on the install page →

What it does not do

• It does not change HESK PHP files
• It is not a replacement help-desk UI for customers
• Customer portal users cannot sign in to the API token portal

Typical setup

A second hostname (for example api.help.example.com) with its document root on hesk-api/public, talking to the same MySQL database as HESK. Staff keep using HESK. Automations and other hosts use the API.

Changelog

1.4.0 — 2026-08-14

• Internal notes accept attachments (multipart or JSON attachments[])
• POST /v1/tickets/{id}/notes/{noteId}/attachments adds files to an existing note
• GET /v1/tickets/{id}/notes includes attachments on each note
• OpenAPI / Swagger updated

1.3.0 — 2026-08-14

First public, transportable package.

• Installer writes config.local.php, applies schema with the live HESK table prefix, optional utf8mb4 conversion, optional bootstrap token
• Host overrides isolated from shipped defaults; HESK_PATH / HESK_URL / HESK_API_URL env fallbacks
• Portal branding and OpenAPI contact/server rewritten per install
• Generic nginx example; HESK version reported from hesk_settings