This documentation always describes the latest published version.
The server provides 12 tools. All names carry the prefix osticket_. Successful calls return JSON as text. Errors come back with the error flag set and a line of the form Error: <action> - <hint>, see Troubleshooting.
| Tool | Purpose | Plugin endpoint | Required API key permission |
|---|---|---|---|
osticket_get_ticket |
Fetch a ticket with its thread | GET /api/tickets-get.php/{number}.json |
can_read_tickets |
osticket_list_tickets |
List tickets with a status filter | GET /api/tickets-search.php |
can_search_tickets or can_read_tickets |
osticket_search_tickets |
Search the subject | GET /api/tickets-search.php |
can_search_tickets or can_read_tickets |
osticket_get_stats |
Fetch statistics | GET /api/tickets-stats.php |
can_read_stats or can_read_tickets |
osticket_create_ticket |
Create a ticket | POST /api/wildcard/tickets.json |
The key's create permission in osTicket |
osticket_update_ticket |
Change a ticket, add a note | PATCH /api/tickets-update.php/{number}.json |
can_update_tickets |
osticket_delete_ticket |
Permanently delete a ticket | DELETE /api/tickets-delete.php/{number}.json |
can_delete_tickets |
osticket_get_parent_ticket |
Fetch the parent ticket | GET /api/tickets-subtickets-parent.php/{number}.json |
can_manage_subtickets |
osticket_get_child_tickets |
Fetch child tickets | GET /api/tickets-subtickets-list.php/{number}.json |
can_manage_subtickets |
osticket_create_subticket_link |
Create a parent-child link | POST /api/tickets-subtickets-create.php/{parentNumber}.json |
can_manage_subtickets |
osticket_unlink_subticket |
Remove the link | DELETE /api/tickets-subtickets-unlink.php/{number}.json |
can_manage_subtickets |
osticket_download_attachment |
Save an attachment to a temporary file | GET /api/tickets-attachment-download.php/{file_id}.json |
can_read_tickets |
In addition, osticket_update_ticket queries the status list through GET /api/tickets-statuses.php when you pass a status name (can_read_stats or can_read_tickets). At startup the server calls GET /api/tickets-stats.php for its health check.
You set the permissions in the osTicket admin panel under Manage → Plugins → API Endpoints → Configure, see the plugin configuration. The subticket tools additionally need the plugin Subticket Manager.
Ticket numbers are strings of 1 to 20 digits in all tools, for example "680284".
Fetches a ticket with thread, user, staff member and attachment metadata.
| Parameter | Type | Required | Description |
|---|---|---|---|
number |
string | One of the two | Public ticket number |
id |
number | One of the two | Internal ticket ID |
If both are given, number wins. Returns { "ticket": { ... } } with the plugin's object.
The server sends an
idas a ticket number. The plugin first looks for a ticket with that number and only then falls back to the internal ID. If another ticket happens to carry that number, you get that one.
Lists ticket summaries without thread.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
status |
string | No | - | open, closed, resolved or archived |
departmentId |
number | No | - | Department ID. Currently has no effect, see the warning below |
limit |
number | No | 20 | 1 to 100 |
offset |
number | No | 0 | Skips results for pagination |
Returns tickets, count, offset, has_more and, when there are more pages, next_offset. has_more is true when exactly limit entries came back. The tool does not return a total count. If the response was shortened because of the character limit, truncated and truncation_message are included.
The parameter
departmentIdexists in the tool but does not filter. The server sends it as the query parameterdepartmentId, while the plugin only readsdepartment. The list therefore comes back unfiltered. Do not rely on this tool to filter by department for now.
The plugin also ignores a
statusname that matches no status of the instance and then does not filter at all. If a list is unexpectedly large, check the numbers withosticket_get_stats.
Searches the ticket subject.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query |
string | Yes | - | 2 to 200 characters |
limit |
number | No | 20 | 1 to 100 |
Returns tickets, count, total, query and has_more. total is the number of returned hits, not the number of all hits in osTicket. The tool has no offset.
No parameters. Returns { "statistics": { ... } } with the plugin's values: total, open, closed, overdue, by_department and by_staff.
Creates a ticket through the endpoint /api/wildcard/tickets.json.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
subject |
string | Yes | - | Subject, up to 255 characters |
message |
string | Yes | - | Message, up to 65535 characters |
projectContext |
string | No | - | Project name, up to 100 characters. Placed before the message as **Projekt:** <value> followed by a blank line |
name |
string | No | OSTICKET_DEFAULT_NAME |
Name of the ticket creator, up to 100 characters |
email |
string | No | OSTICKET_DEFAULT_EMAIL |
Email address |
format |
string | No | markdown |
markdown, html or text |
topicId |
number | No | OSTICKET_DEFAULT_TOPIC_ID |
Help topic ID. If neither this nor the default is set, no help topic is sent |
attachments |
array | No | - | Objects of the form { "path": "/absolute/path" }, 1 to 5 of them |
If both name and OSTICKET_DEFAULT_NAME are missing, the tool aborts with an error message. The same applies to the email address. The server always sends alert=false and autorespond=false: neither the team nor the sender gets a notification from osTicket.
Returns success, ticketNumber, projectContext (or null), attachments with a summary when files were attached, and message.
The tool text instructs Claude to ask for the project when none is given. The code does not enforce this: without
projectContextthe ticket is created without a project line.
Changes ticket properties and can add an internal note.
| Parameter | Type | Required | Description |
|---|---|---|---|
number |
string | Yes | Ticket number |
statusId |
string or number | No | Status ID or status name, for example "Closed" |
departmentId |
string or number | No | Department ID |
topicId |
string or number | No | Help topic ID |
staffId |
string or number | No | Staff member ID |
slaId |
string or number | No | SLA plan ID |
dueDate |
string or null | No | YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS. null removes the date |
parentTicketNumber |
string | No | Number of the parent ticket |
note |
string | No | Internal note, visible to staff only, up to 65535 characters |
noteTitle |
string | No | Note title, up to 100 characters. The plugin uses API Update when it is missing |
noteFormat |
string | No | markdown (default), html or text |
attachments |
array | No | Files for the note, 1 to 5 of them. Without note the tool rejects them |
Only the status is resolved in the server: a name is compared against the osTicket status list, ignoring case, and the list is cached for 5 minutes. A string that starts with a number is treated as an ID. Department, help topic, staff member and SLA must be passed as a number or a numeric string. A name leads to an error.
The schema requires
numberplus at least one more field, butnoteFormathas a default value and therefore always counts as set. A call with onlynumberis not rejected and changes nothing on the ticket.
Returns success, ticket (osTicket's response, which according to the plugin documentation is the ticket number), attachments when files were attached, and message.
| Parameter | Type | Required | Description |
|---|---|---|---|
number |
string | Yes | Ticket number |
Deletion is permanent. The ticket and its thread disappear from the database. The permission
can_delete_ticketsis off by default for every key in the plugin. Moving the ticket to a closed status withosticket_update_ticketis usually the better choice.
Returns success and message.
| Parameter | Type | Required | Description |
|---|---|---|---|
number |
string | Yes | Number of the child ticket |
Returns success, parent (with ticket_id, number, subject, status, or null without a parent) and message.
| Parameter | Type | Required | Description |
|---|---|---|---|
number |
string | Yes | Number of the parent ticket |
Returns success, children (list with ticket_id, number, subject, status), total and message.
Makes an existing ticket the child of another. The server sends the child number as childId.
| Parameter | Type | Required | Description |
|---|---|---|---|
parentNumber |
string | Yes | Number of the parent ticket |
childNumber |
string | Yes | Number of the child ticket |
Returns success, parent, child and message. The plugin rejects linking a ticket to itself with 400, and an existing link or a child with a different parent with 422.
| Parameter | Type | Required | Description |
|---|---|---|---|
number |
string | Yes | Number of the child ticket |
Returns success, child and message. If the ticket has no parent, the plugin answers with 404.
Downloads an attachment and saves it to the operating system's temporary directory.
| Parameter | Type | Required | Description |
|---|---|---|---|
file_id |
number | Yes | The file_id value from the attachment metadata of a thread entry returned by osticket_get_ticket |
Returns success, filePath, filename, size and mime_type. The file name is <8 hex characters>_<file name>, with every character other than letters, digits, dot, underscore and hyphen replaced by _. The server does not delete the file again. osTicket's response contains the file Base64-encoded and may be at most 10 MB, so files from roughly 7.5 MB fail.