Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.
Der Server stellt 12 Tools bereit. Alle Namen tragen das Präfix osticket_. Erfolgreiche Aufrufe liefern JSON als Text, Fehler kommen mit gesetztem Fehlerflag und einer Zeile der Form Error: <Aktion> - <Hinweis> zurück, siehe Fehlerbehebung.
| Tool | Zweck | Endpunkt des Plugins | Nötige API-Key-Berechtigung |
|---|---|---|---|
osticket_get_ticket |
Ticket mit Thread abrufen | GET /api/tickets-get.php/{number}.json |
can_read_tickets |
osticket_list_tickets |
Tickets mit Statusfilter auflisten | GET /api/tickets-search.php |
can_search_tickets oder can_read_tickets |
osticket_search_tickets |
Im Betreff suchen | GET /api/tickets-search.php |
can_search_tickets oder can_read_tickets |
osticket_get_stats |
Statistik abrufen | GET /api/tickets-stats.php |
can_read_stats oder can_read_tickets |
osticket_create_ticket |
Ticket erstellen | POST /api/wildcard/tickets.json |
Create-Berechtigung des Keys in osTicket |
osticket_update_ticket |
Ticket ändern, Notiz hinzufügen | PATCH /api/tickets-update.php/{number}.json |
can_update_tickets |
osticket_delete_ticket |
Ticket endgültig löschen | DELETE /api/tickets-delete.php/{number}.json |
can_delete_tickets |
osticket_get_parent_ticket |
Elternticket abrufen | GET /api/tickets-subtickets-parent.php/{number}.json |
can_manage_subtickets |
osticket_get_child_tickets |
Kindtickets abrufen | GET /api/tickets-subtickets-list.php/{number}.json |
can_manage_subtickets |
osticket_create_subticket_link |
Eltern-Kind-Verknüpfung erstellen | POST /api/tickets-subtickets-create.php/{parentNumber}.json |
can_manage_subtickets |
osticket_unlink_subticket |
Verknüpfung lösen | DELETE /api/tickets-subtickets-unlink.php/{number}.json |
can_manage_subtickets |
osticket_download_attachment |
Anhang in eine temporäre Datei laden | GET /api/tickets-attachment-download.php/{file_id}.json |
can_read_tickets |
Zusätzlich fragt osticket_update_ticket mit einem Statusnamen die Statusliste über GET /api/tickets-statuses.php ab (can_read_stats oder can_read_tickets). Beim Start ruft der Server GET /api/tickets-stats.php für die Zustandsprüfung auf.
Die Berechtigungen setzt du im osTicket-Admin-Panel unter Verwalten → Plugins → API Endpoints → Configure, siehe die Konfiguration des Plugins. Die Subticket-Tools brauchen außerdem das Plugin Subticket Manager.
Ticketnummern sind in allen Tools Strings aus 1 bis 20 Ziffern, zum Beispiel "680284".
Ruft ein Ticket mit Thread, Benutzer, Mitarbeiter und Anhang-Metadaten ab.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
number |
string | Eins von beiden | Öffentliche Ticketnummer |
id |
number | Eins von beiden | Interne Ticket-ID |
Sind beide angegeben, gilt number. Rückgabe: { "ticket": { ... } } mit dem Objekt des Plugins.
Eine
idsendet der Server als Ticketnummer. Das Plugin sucht zuerst ein Ticket mit dieser Nummer und nimmt erst danach die interne ID. Trägt ein anderes Ticket zufällig diese Nummer, bekommst du dieses.
Listet Ticket-Zusammenfassungen ohne Thread.
| Parameter | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
status |
string | Nein | - | open, closed, resolved oder archived |
departmentId |
number | Nein | - | ID der Abteilung. Hat derzeit keine Wirkung, siehe die Warnung unten |
limit |
number | Nein | 20 | 1 bis 100 |
offset |
number | Nein | 0 | Überspringt Treffer für die Paginierung |
Rückgabe: tickets, count, offset, has_more und bei weiteren Seiten next_offset. has_more ist wahr, wenn genau limit Einträge zurückkamen. Eine Gesamtzahl liefert das Tool nicht. Wurde die Antwort wegen der Zeichengrenze gekürzt, stehen truncated und truncation_message dabei.
Der Parameter
departmentIdexistiert im Tool, filtert aber nicht. Der Server sendet ihn als AbfrageparameterdepartmentId, das Plugin liest jedoch nurdepartment. Die Liste kommt deshalb ungefiltert zurück. Filtere nach Abteilung bis auf Weiteres nicht über dieses Tool.
Das Plugin ignoriert außerdem einen
status-Namen, der keinem Status der Instanz entspricht, und filtert dann gar nicht. Prüfe mitosticket_get_stats, ob die Zahlen plausibel sind, wenn eine Liste unerwartet groß ausfällt.
Sucht im Betreff der Tickets.
| Parameter | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
query |
string | Ja | - | 2 bis 200 Zeichen |
limit |
number | Nein | 20 | 1 bis 100 |
Rückgabe: tickets, count, total, query und has_more. total ist die Zahl der zurückgegebenen Treffer, nicht die Zahl aller Treffer in osTicket. Das Tool hat keinen offset.
Keine Parameter. Rückgabe: { "statistics": { ... } } mit den Werten des Plugins: total, open, closed, overdue, by_department und by_staff.
Erstellt ein Ticket über den Endpunkt /api/wildcard/tickets.json.
| Parameter | Typ | Pflicht | Standard | Beschreibung |
|---|---|---|---|---|
subject |
string | Ja | - | Betreff, bis 255 Zeichen |
message |
string | Ja | - | Nachricht, bis 65535 Zeichen |
projectContext |
string | Nein | - | Projektname, bis 100 Zeichen. Wird als **Projekt:** <Wert> und Leerzeile vor die Nachricht gesetzt |
name |
string | Nein | OSTICKET_DEFAULT_NAME |
Name des Ticket-Erstellers, bis 100 Zeichen |
email |
string | Nein | OSTICKET_DEFAULT_EMAIL |
E-Mail-Adresse |
format |
string | Nein | markdown |
markdown, html oder text |
topicId |
number | Nein | OSTICKET_DEFAULT_TOPIC_ID |
Hilfethema-ID. Ist weder dies noch der Standardwert gesetzt, wird kein Hilfethema gesendet |
attachments |
array | Nein | - | Objekte der Form { "path": "/absoluter/pfad" }, 1 bis 5 Stück |
Fehlen sowohl name als auch OSTICKET_DEFAULT_NAME, bricht das Tool mit einer Fehlermeldung ab. Dasselbe gilt für die E-Mail-Adresse. Der Server sendet immer alert=false und autorespond=false: Weder das Team noch der Absender bekommen eine Benachrichtigung durch osTicket.
Rückgabe: success, ticketNumber, projectContext (oder null), bei Anhängen attachments mit einer Zusammenfassung, und message.
Der Tool-Text weist Claude an, bei fehlender Projektangabe nach dem Projekt zu fragen. Der Code erzwingt das nicht: Ohne
projectContextwird das Ticket ohne Projektzeile erstellt.
Ändert Eigenschaften eines Tickets und kann eine interne Notiz anlegen.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
number |
string | Ja | Ticketnummer |
statusId |
string oder number | Nein | Status-ID oder Statusname, zum Beispiel "Closed" |
departmentId |
string oder number | Nein | Abteilungs-ID |
topicId |
string oder number | Nein | Hilfethema-ID |
staffId |
string oder number | Nein | Mitarbeiter-ID |
slaId |
string oder number | Nein | SLA-Plan-ID |
dueDate |
string oder null | Nein | YYYY-MM-DD oder YYYY-MM-DDTHH:MM:SS. null entfernt das Datum |
parentTicketNumber |
string | Nein | Nummer des Elterntickets |
note |
string | Nein | Interne Notiz, nur für Mitarbeiter sichtbar, bis 65535 Zeichen |
noteTitle |
string | Nein | Titel der Notiz, bis 100 Zeichen. Das Plugin nutzt API Update, wenn er fehlt |
noteFormat |
string | Nein | markdown (Standard), html oder text |
attachments |
array | Nein | Dateien für die Notiz, 1 bis 5 Stück. Ohne note lehnt das Tool sie ab |
Nur der Status wird im Server aufgelöst: Ein Name wird gegen die Statusliste von osTicket verglichen, ohne Beachtung der Groß-/Kleinschreibung, und die Liste wird 5 Minuten zwischengespeichert. Eine Zeichenkette, die mit einer Zahl beginnt, gilt als ID. Abteilung, Hilfethema, Mitarbeiter und SLA müssen als Zahl oder Zifferstring übergeben werden. Ein Name führt zu einem Fehler.
Das Schema verlangt
numberplus mindestens ein weiteres Feld, abernoteFormathat einen Standardwert und zählt deshalb immer als gesetzt. Ein Aufruf nur mitnumberwird deshalb nicht abgelehnt und ändert nichts am Ticket.
Rückgabe: success, ticket (die Antwort von osTicket, laut Plugin-Dokumentation die Ticketnummer), bei Anhängen attachments und message.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
number |
string | Ja | Ticketnummer |
Das Löschen ist endgültig. Ticket und Thread verschwinden aus der Datenbank. Die Berechtigung
can_delete_ticketsist im Plugin standardmäßig für jeden Key aus. Ein Wechsel auf einen geschlossenen Status mitosticket_update_ticketist meist die bessere Wahl.
Rückgabe: success und message.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
number |
string | Ja | Nummer des Kindtickets |
Rückgabe: success, parent (mit ticket_id, number, subject, status, oder null ohne Elternticket) und message.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
number |
string | Ja | Nummer des Elterntickets |
Rückgabe: success, children (Liste mit ticket_id, number, subject, status), total und message.
Macht ein bestehendes Ticket zum Kind eines anderen. Der Server sendet die Kindnummer als childId.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
parentNumber |
string | Ja | Nummer des Elterntickets |
childNumber |
string | Ja | Nummer des Kindtickets |
Rückgabe: success, parent, child und message. Das Plugin lehnt eine Verknüpfung mit sich selbst mit 400 ab, eine bestehende Verknüpfung oder ein Kind mit anderem Elternticket mit 422.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
number |
string | Ja | Nummer des Kindtickets |
Rückgabe: success, child und message. Hat das Ticket kein Elternticket, antwortet das Plugin mit 404.
Lädt einen Anhang und speichert ihn im temporären Verzeichnis des Betriebssystems.
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
file_id |
number | Ja | Wert file_id aus den Anhang-Metadaten eines Thread-Eintrags von osticket_get_ticket |
Rückgabe: success, filePath, filename, size und mime_type. Der Dateiname lautet <8 Hex-Zeichen>_<Dateiname>, wobei alle Zeichen außer Buchstaben, Ziffern, Punkt, Unterstrich und Bindestrich durch _ ersetzt werden. Der Server löscht die Datei nicht wieder. Die Antwort von osTicket enthält die Datei Base64-kodiert und darf höchstens 10 MB groß sein, daher scheitern Dateien ab etwa 7,5 MB.