English Version

Zurück zur Übersicht

API Endpoints: API-Dokumentation

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Diese Seite beschreibt alle 12 Endpunkte des Plugins: Pfade, Methoden, Parameter, nötige API-Key-Berechtigungen, Antworten und Fehlercodes. Installation und Webserver-Einrichtung stehen auf Installation, die Berechtigungen auf Konfiguration.

Überblick

{format} ist json oder xml. Die Berechtigungsnamen sind die Spalten der API-Key-Tabelle, siehe Konfiguration.

Authentifizierung

Jede Anfrage trägt den API-Key im Header X-API-Key.

X-API-Key: YOUR_API_KEY

Die eigenständigen Endpunkte (2 bis 12) lehnen einen fehlenden oder ungültigen Key mit 401 ab. Ein API-Key ohne die für den Endpunkt nötige Berechtigung erhält 401 mit einer Meldung wie API key not authorized to read tickets. Nur die Subticket-Endpunkte und der Attachment-Download antworten in bestimmten Fällen mit 403, siehe Statuscodes. Endpunkt 1 wird anders behandelt, siehe den zugehörigen Abschnitt.

can_read_tickets gewährt auch Suche, Statistiken und die Statusliste. Ein Key, der nur can_search_tickets oder can_read_stats hat, kann nur genau diesen einen Endpunkt nutzen. Alle anderen Berechtigungen haben keinen Fallback: Eine fehlende oder deaktivierte Berechtigung bedeutet verweigerten Zugriff.

Basis-URL

https://your-domain.com/api

Antwortformate

XML-Antworten haben response als Wurzelelement, Listeneinträge heißen item. Fehler, die das Plugin selbst auslöst, sind immer JSON, auch bei .xml-Anfragen:

{
  "error": true,
  "message": "Description of what went wrong"
}

Fehler der API-Key-Prüfung (fehlender oder ungültiger Key, IP-Beschränkung) stammen aus dem osTicket-Core oder dem Plugin API Key Wildcard und haben deren Format.

Fehler der beiden über das Signal registrierten Routen (Erstellen und PATCH /api/tickets/{number}.{format}) kommen als Klartext, der nur die Meldung enthält.

Statuscodes

Auflösung über Namen

departmentId, statusId, topicId und slaId akzeptieren einen Namen oder eine ID. Ein nicht numerischer Wert wird als Name gesucht (ohne Beachtung der Groß-/Kleinschreibung) und liefert 404, wenn nichts passt. Ein numerischer Wert, auch als String gesendet, wird immer als ID verwendet. staffId akzeptiert die Mitarbeiter-ID, den Benutzernamen oder die E-Mail-Adresse, nicht den Anzeigenamen.

1. POST Ticket erstellen

Erstellt ein Ticket. Das Plugin ergänzt die Erstellungsparameter von osTicket um format, departmentId und parentTicketNumber.

Endpunkt

POST /api/tickets.json

Berechtigung: Für diese Signal-Route prüft das Plugin selbst weder den API-Key noch die Berechtigung can_create_tickets. Ob der osTicket-Core den Key prüft, bevor er das Signal auslöst, lässt sich aus dem Code dieses Plugins nicht ableiten.

Sende den Body als JSON mit Content-Type: application/json.

Vom Plugin verarbeitete Parameter

Von osTicket verarbeitete Parameter

Alle anderen Felder verarbeitet die Ticketerstellung von osTicket selbst, zum Beispiel name, email, subject, message, topicId und attachments. Welche davon Pflicht sind, hängt vom Ticketformular deiner osTicket-Installation ab.

Anhänge werden als Array von Objekten übergeben, jeweils mit dem Dateinamen als Schlüssel und einer Base64-Data-URI als Wert:

{
  "attachments": [
    {"screenshot.png": "data:image/png;base64,iVBORw0KGgo..."},
    {"report.pdf": "data:application/pdf;base64,JVBERi0xLjQ..."}
  ]
}

Antwort

201 Created: die Ticketnummer als Klartext.

781258

Beispiele

# Einfaches Ticket
curl -X POST "https://osticket.local/api/tickets.json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "subject": "Login Issue",
    "message": "I cannot access my account"
  }'

# Markdown-Nachricht, in eine Abteilung geroutet
curl -X POST "https://osticket.local/api/tickets.json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "subject": "Bug Report: Payment Failed",
    "message": "## Problem\n\nPayment fails with error CARD_DECLINED.",
    "format": "markdown",
    "departmentId": "Billing"
  }'

# Als Subticket eines bestehenden Tickets erstellen
curl -X POST "https://osticket.local/api/tickets.json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Developer",
    "email": "dev@example.com",
    "subject": "Subtask: Database Migration",
    "message": "Migrate the production database",
    "parentTicketNumber": "181752",
    "departmentId": "Development"
  }'

Hinweise

• Fehler: Validierungsfehler der Plugin-Parameter (ungültiges format, unbekannte oder inaktive Abteilung, unbekanntes Elternticket) kommen als 400 mit einer Klartext-Meldung zurück, auch Fälle, die anderswo 404 wären.
• Reihenfolge: Zuerst wird das Ticket erstellt, danach werden Abteilung und Eltern-Verknüpfung gesetzt. So überschreiben die eigenen Routing-Regeln von osTicket die Abteilung nicht. Scheitert das Setzen im Nachgang, existiert das Ticket trotzdem und es kommt 201.
• Markdown: Ist die Einstellung Require Markdown Plugin aktiv, liefert format=markdown ein 400 (Markdown Support plugin is required but not active), solange das Plugin Markdown Support nicht aktiv ist. Ist die Einstellung aus, wird der Wert ohne diese Prüfung durchgereicht.
• Subtickets: parentTicketNumber setzt nur den Verweis auf das Elternticket. Die eigenen Subticket-Endpunkte prüfen zusätzlich die Berechtigung can_manage_subtickets.

2. GET Ticket abrufen

Liefert ein Ticket samt Thread.

GET /api/tickets-get.php/{number}.{format}

Berechtigung: can_read_tickets

Antwort

{
  "id": 123,
  "number": "781258",
  "subject": "Login Issue",
  "statusId": 1,
  "status": "Open",
  "priorityId": 2,
  "priority": "Normal",
  "departmentId": 5,
  "department": "IT Support",
  "topicId": 10,
  "topic": "Technical Support",
  "userId": 45,
  "user": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "staffId": 3,
  "staff": "Jane Smith",
  "teamId": 2,
  "team": "Level 1 Support",
  "slaId": 1,
  "sla": "Standard SLA",
  "created": "2025-11-08 10:30:00",
  "updated": "2025-11-08 14:20:00",
  "duedate": "2025-11-15 10:30:00",
  "closed": null,
  "isOverdue": false,
  "isAnswered": true,
  "source": "API",
  "ip": "192.168.1.100",
  "children": [124, 125],
  "thread": [
    {
      "id": 456,
      "type": "M",
      "poster": "John Doe",
      "timestamp": "2025-11-08 10:30:00",
      "body": "I cannot access my account",
      "userId": 45,
      "attachments": [
        {
          "id": 12,
          "file_id": 29,
          "filename": "screenshot.png",
          "size": 45320,
          "mime_type": "image/png",
          "inline": false
        }
      ],
      "attachment_count": 1
    }
  ]
}

Beispiel

curl "https://osticket.local/api/tickets-get.php/781258.json" \
  -H "X-API-Key: YOUR_API_KEY"

3. PATCH Ticket aktualisieren

Ändert Eigenschaften eines Tickets und fügt optional eine interne Notiz mit Anhängen hinzu.

PATCH /api/tickets-update.php/{number}.{format}
PUT   /api/tickets-update.php/{number}.{format}

Dasselbe Update steht über die Route PATCH /api/tickets/{number}.json zur Verfügung (auch PUT, .xml wird akzeptiert). Diese Route antwortet bei Fehlern mit Klartext statt JSON.

Berechtigung: can_update_tickets

Sende den Body als JSON mit Content-Type: application/json. Gib nur die Felder an, die sich ändern sollen.

Andere Felder, auch priority, werden ohne Fehlermeldung ignoriert.

Antwort

200 OK: die Ticketnummer als Klartext.

Beispiele

# Status ändern
curl -X PATCH "https://osticket.local/api/tickets-update.php/781258.json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"statusId": "Resolved"}'

# Einem Mitarbeiter zuweisen, mit Notiz
curl -X PATCH "https://osticket.local/api/tickets-update.php/781258.json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"staffId": "john.doe", "note": "Assigned to John for follow-up"}'

# Fälligkeitsdatum entfernen
curl -X PATCH "https://osticket.local/api/tickets-update.php/781258.json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dueDate": null}'

Hinweise

• Nicht atomar: Die Felder werden nacheinander in der Reihenfolge Abteilung, Hilfethema, Elternticket, Status, SLA, Mitarbeiter, Fälligkeitsdatum, Notiz angewendet. Scheitert ein späterer Wert an der Validierung, sind die früheren Änderungen schon gespeichert.
• Fälligkeitsdatum: Ein Datum in der Zukunft setzt das Überfällig-Flag zurück.
• Fehler: Eine Anfrage ohne Body liefert 400. Ein Elternticket, das selbst ein Kind ist, liefert 400 (Parent ticket cannot be a child of another ticket).

4. GET Tickets suchen

GET /api/tickets-search.php

Berechtigung: can_search_tickets oder can_read_tickets

Ein status- oder department-Name, der nichts trifft, wird ignoriert und filtert nicht.

Antwort

Ein JSON-Array, nicht in ein Objekt verpackt. Die Einträge enthalten keinen Thread:

[
  {
    "id": 123,
    "number": "781258",
    "subject": "Login Issue",
    "statusId": 1,
    "status": "Open",
    "priorityId": 2,
    "priority": "Normal",
    "departmentId": 5,
    "department": "IT Support",
    "topicId": 10,
    "topic": "Technical Support",
    "created": "2025-11-08 10:00:00",
    "updated": "2025-11-08 14:30:00",
    "dueDate": "2025-11-15 10:00:00",
    "staffId": 3,
    "staff": "Jane Smith",
    "teamId": 2,
    "team": "Level 1 Support",
    "slaId": 1,
    "sla": "Standard SLA",
    "isOverdue": false,
    "isAnswered": true
  }
]

Beispiele

curl "https://osticket.local/api/tickets-search.php?query=login" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://osticket.local/api/tickets-search.php?query=payment&status=Open&department=Support&limit=50&offset=50" \
  -H "X-API-Key: YOUR_API_KEY"

5. DELETE Ticket löschen

Löscht ein Ticket endgültig.

Diese Aktion lässt sich nicht rückgängig machen. Das Ticket und sein Thread werden aus der Datenbank entfernt.

DELETE /api/tickets-delete.php/{number}.{format}

Berechtigung: can_delete_tickets, für jeden API-Key standardmäßig deaktiviert.

200 OK: die Nummer des gelöschten Tickets als Klartext.

curl -X DELETE "https://osticket.local/api/tickets-delete.php/781258.json" \
  -H "X-API-Key: YOUR_API_KEY"

Erwäge statt des Löschens ein PATCH auf einen geschlossenen Status.

6. GET Ticket-Statistiken

GET /api/tickets-stats.php

Berechtigung: can_read_stats oder can_read_tickets

{
  "total": 150,
  "open": 45,
  "closed": 105,
  "overdue": 3,
  "by_department": {
    "Billing": {"total": 70, "open": 25, "closed": 45, "overdue": 2},
    "Support": {"total": 80, "open": 20, "closed": 60, "overdue": 1}
  },
  "by_staff": [
    {
      "staff_id": 1,
      "staff_name": "John Smith",
      "total": 35,
      "departments": {
        "Support": {"open": 10, "closed": 20, "overdue": 0}
      }
    }
  ]
}

• by_department ist ein Objekt mit dem Abteilungsnamen als Schlüssel, alphabetisch sortiert.
• by_staff ist ein nach Mitarbeitername sortiertes Array. Gezählt werden nur zugewiesene Tickets.
• Die Statistik wird bei jeder Anfrage durch Iteration über alle Tickets berechnet. Bei Installationen mit sehr vielen Tickets kann der Aufruf eine Weile dauern.

7. GET Statusliste

GET /api/tickets-statuses.php

Berechtigung: can_read_stats oder can_read_tickets

[
  {"id": 1, "name": "Open", "state": "open"},
  {"id": 3, "name": "Closed", "state": "closed"}
]

Die Liste ist nach der Status-Reihenfolge sortiert und enthält auch eigene Status. state ist der osTicket-Zustand des Status.

Subticket-Endpunkte

Die Endpunkte 8 bis 11 setzen das Plugin Subticket Manager (Klasse SubticketPlugin) und die Berechtigung can_manage_subtickets voraus. Sie prüfen in dieser Reihenfolge: zuerst die Eingabe (eine ungültige Ticketnummer liefert 400, Endpunkt 10 liefert zusätzlich 400 bei fehlendem childId und beim Verknüpfen eines Tickets mit sich selbst), dann die Berechtigung (403, API key not authorized for subticket operations), dann das Plugin (501, Subticket plugin not available), dann die Ticket-Suche. Die Endpunkte 10 und 11 prüfen zusätzlich die Abteilung des Tickets, aber nur, wenn das API-Key-Objekt Abteilungsbeschränkungen liefert. Standard-API-Keys von osTicket haben keine.

8. GET Elternticket abrufen

GET /api/tickets-subtickets-parent.php/{number}.{format}

number ist die Nummer des Kindtickets.

{
  "parent": {
    "ticket_id": 100,
    "number": "781200",
    "subject": "Parent Ticket",
    "status": "Open"
  }
}

Liefert {"parent": null}, wenn das Ticket kein Elternticket hat. 404 (Child ticket not found), wenn das Ticket nicht existiert.

9. GET Kindtickets abrufen

GET /api/tickets-subtickets-list.php/{number}.{format}

number ist die Nummer des Elterntickets.

{
  "children": [
    {"ticket_id": 124, "number": "781259", "subject": "Child Ticket 1", "status": "Open"},
    {"ticket_id": 125, "number": "781260", "subject": "Child Ticket 2", "status": "Closed"}
  ]
}

Liefert {"children": []}, wenn es keine gibt. 404 (Parent ticket not found), wenn das Ticket nicht existiert.

10. POST Subticket-Verknüpfung erstellen

Verknüpft zwei bestehende Tickets.

POST /api/tickets-subtickets-create.php/{parentNumber}.{format}

curl -X POST "https://osticket.local/api/tickets-subtickets-create.php/781200.json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"childId": "781259"}'

{
  "success": true,
  "message": "Subticket relationship created successfully",
  "parent": {"ticket_id": 100, "number": "781200", "subject": "Parent Ticket", "status": "Open"},
  "child": {"ticket_id": 124, "number": "781259", "subject": "Child Ticket", "status": "Open"}
}

11. DELETE Subticket-Verknüpfung lösen

Entfernt die Eltern-Verknüpfung eines Kindtickets.

DELETE /api/tickets-subtickets-unlink.php/{number}.{format}

number ist die Nummer des Kindtickets.

{
  "success": true,
  "message": "Subticket relationship removed successfully",
  "child": {"ticket_id": 124, "number": "781259", "subject": "Child Ticket", "status": "Open"}
}

Attachment-Endpunkt

12. GET Attachment herunterladen

Liefert eine Datei als Base64 zusammen mit ihren Metadaten.

GET /api/tickets-attachment-download.php/{file_id}.{format}

Berechtigung: can_read_tickets

{
  "file_id": 29,
  "filename": "screenshot.png",
  "mime_type": "image/png",
  "size": 45320,
  "content": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Bevor der Endpunkt eine Datei ausliefert, prüft er, dass in der Anhang-Tabelle ein Eintrag mit dieser file_id existiert. Die Prüfung filtert nicht nach dem Typ des Objekts, zu dem der Anhang gehört.

curl -s "https://osticket.local/api/tickets-attachment-download.php/29.json" \
  -H "X-API-Key: YOUR_API_KEY" \
  | jq -r '.content' \
  | base64 -d > screenshot.png

Die ganze Datei wird in den Speicher gelesen und Base64-kodiert, wodurch die Antwort etwa ein Drittel größer ist als die Datei.

Rate Limiting

Das Plugin implementiert kein Rate Limiting. Wenn du es brauchst, richte es auf dem Webserver ein.