nks-osticket-plugin

nks-osticket-plugin is a plugin for the osTicket helpdesk that lets other systems and AI agents read, search and reply to tickets. Anyone who wants to connect another system to a helpdesk on osTicket soon finds that the built-in API can receive tickets but cannot read, search or reply to them. Integrations then get written directly against the database, which bypasses osTicket's logic, or core files get patched, which breaks with the next update. nks-osticket-plugin adds a single JSON endpoint to osTicket, through which integrations and AI agents work with tickets under regular osTicket API keys, without touching the core.

Why what osTicket has is not enough

A key in a stock osTicket installation has only two permissions: create tickets and run cron. The add-on adds permissions for reading, searching, editing, replying, deleting, statistics and child tickets, and provides the actions that use them. Writes go through the documented API of the Ticket class, so threads, alerts and log entries keep working as they do in the admin. Unlike writing to the database directly, nothing is bypassed, and unlike patching the core, osTicket's core files stay untouched. Outside its own directory, the add-on adds only an entry file in api/ and an exception in api/.htaccess. The install script writes the exception only when it is missing from the file, so it can be run again after an osTicket update.

What the add-on does

One endpoint for all actions

Everything goes through POST /api/nks-osticket.php with the key in the X-Api-Key header and a body in the form {"action": …, "params": …}. The actions cover listing, searching, showing, creating, updating, replying to and deleting a ticket, statistics, the list of statuses, parent and child tickets and downloading an attachment. Read-only actions also accept GET with parameters in the URL, so you can try them from a browser or with curl. The response always has the same envelope: {"ok": true, "data": …} or {"ok": false, "error": {"code", "message"}}.

Lists that handle a large database

When osTicket 1.18 loads full ticket objects through an automatically joined QuerySet, it runs tens of thousands of schema queries per row. Listing and search therefore fetch only the columns they need with the ORM projection ->values() and do not build full objects. The ticket list stays usable even in a helpdesk with a long history.

A real agent replies and the customer gets the email

Replies and internal notes are recorded under a specific osTicket agent (staffId, default 1), so osTicket fills in the name, signature, email sender and automatic ticket assignment. The reply is actually sent to the customer; replyTo sets the recipients: everyone, only the requester, or only the other participants. Since version 1.3.0 a reply can carry attachments in base64; they are stored with the thread entry and sent with the email if osTicket has email attachments enabled. A file over the size limit from the osTicket settings returns code 413.

Attachments you can find

For each thread entry, the ticket detail returns a list of attachments with ID, name, type, size, an inline image flag and the cid that matches the cid: references in the message text. The ID is then accepted by the attachments.download action. Without this, attachments were not reachable through the API.

Child tickets without another add-on

Links between tickets use the ticket_pid column that osTicket already has. The add-on can link tickets, remove a link, list children and find the parent, and needs no other third-party add-on for it.

Security and permissions

The add-on has no login of its own; it uses API keys from the osTicket admin (Admin Panel, Manage, API Keys). Each key is bound to a source IP address and each action requires its own permission. A key that may only read statistics cannot change anything. When the IP address does not match, the API returns the address it saw, so the administrator knows which address to bind the key to.

The add-on adds the missing permission columns to the ost_api_key table on the first authenticated request, all set to 0. The osTicket admin does not show them; they are enabled in the database:

UPDATE ost_api_key
SET can_read_tickets = 1, can_search_tickets = 1, can_read_stats = 1
WHERE id = 2;  -- the key id, also returned by meta.ping as keyId

A 403 response names the missing permission and carries in error.hint the exact UPDATE statement that enables it. When the database user is not allowed to alter the table, the API returns code 500 with an ALTER TABLE statement to run manually.

Where it helps

• An AI agent on top of the helpdesk: the add-on is the base for nks-osticket-mcp, an MCP server through which Claude and other agents read tickets and reply to them.
• Connecting your own system: a CRM or billing system pulls a customer's tickets and their status with one request.
• Reports and monitoring: a cron script asks for overdue tickets through tickets.stats and sends an alert when their number grows.

Project status

Version 1.0.0 was released on 5 July 2026; 1.1.0 two days later added attachments in the thread. Version 1.2.0 from 18 August fixed replies that had been saved to the thread but not sent by email, and added recording under an agent's name. Version 1.2.1 from 23 October fixed a state in which every action except meta.ping returned error 403 on an unmodified osTicket, because the permission columns did not exist. The latest, 1.3.0 from 28 October 2026, added attachments to replies. It is developed against osTicket 1.18; older versions have not been tested. The repository has no automated tests; changes are verified by deploying to a test osTicket.

Getting started

git clone https://github.com/nks-hub/nks-osticket-plugin.git
cd nks-osticket-plugin
OSTICKET_WEB=/path/to/osticket/upload ./deploy.sh
curl -H "X-Api-Key: <your osTicket API key>" \
  "https://support.example.com/api/nks-osticket.php?action=meta.ping"

The deploy.sh script copies the add-on code to include/plugins/nks-osticket-api/ and the entry file to api/nks-osticket.php, and adds an exception to api/.htaccess so that the osTicket dispatcher does not catch the request. Then just give the files to the web server user. Activation in the admin is optional; the API works as soon as the files are copied. You need PHP 8.0 or later, access to the osTicket web root and bash.

Source code

The code is on GitHub in the nks-hub/nks-osticket-plugin repository under the MIT licence, written in PHP. There is no package on Packagist; the add-on is installed from the repository. Changes are described in CHANGELOG.md and in the GitHub releases.