/public/* sind deprecated und werden am 31. Oktober 2026 abgeschaltet. Neue Integrationen nutzen /public/v1/*.
Jede Legacy-Antwort enthält Deprecation-Header:
Warum migrieren
Basis-URL
Authentifizierung unverändert: Header
cx-api-key.
Response-Envelope
Legacy-Liste (Beispiel):code prüfen, nicht auf message. Siehe Fehler.
Pagination migrieren
Siehe Pagination.
Endpoint-Mapping
Ticket-Export migrieren
Der v1-Export ersetzt den Legacy-Export für nächtliche Syncs und Backfills. Er läuft im Hintergrund, verarbeitet bis zu 50.000 Tickets in einem Export und hat kein Rate Limit pro Ticket für Nachrichten. Der Legacy-EndpointPOST /public/tickets/export bleibt verfügbar.
Nächtlicher Sync
Bisher hat der Sync Tickets mit Legacy-Aufrufen gelistet und die Nachrichten jedes Tickets geladen. Jetzt reichen ein Export und ein paar Statusabfragen.1
Gespeicherte Ansicht nutzen
Lege die Tickets, die du synchronisierst, in einer gespeicherten Ansicht ab und lies ihre
id aus GET /public/v1/views.2
Export anlegen
POST /public/v1/ticket-exports mit { "view_id": "<View-ID>", "include_messages": true }. Die Antwort ist 202 mit dem Export im Status queued.3
Warten, bis er fertig ist
GET /public/v1/ticket-exports/<Export-ID> alle paar Sekunden abrufen, bis status completed ist.4
Herunterladen und parsen
download_url herunterladen, entpacken und tickets.csv sowie messages.csv lesen. Passe deinen Parser an die Wertänderungen in der Tabelle oben an.Backfill
Bisher musste ein Backfill unter 500 Tickets pro Anfrage bleiben und lieferte darüber413 TOO_MANY_TICKETS. Er lief deshalb als viele kleine Zeiträume. Jetzt exportierst du nach Erstellungsdatum, und ein Export enthält bis zu 50.000 Tickets. Datumsangaben sind UTC und einschließlich. Es können 2 Exporte gleichzeitig laufen.
Vorher:
EXPORT_TOO_LARGE fehl. Nutze dann kleinere Zeiträume.
Alle Felder, Status und Limits stehen unter Ticket-Exporte.
Scopes während der Migration
Neue Schlüssel mit expliziten Scopes:
Leere
scopes (vor Migration) = weiterhin Vollzugriff bis zur Rotation.
Migrations-Checkliste
1
Legacy-Nutzung auditieren
Welche
/public/*-Endpoints ruft deine Integration heute auf?2
Scoped v1-Schlüssel erstellen
Einstellungen → API —
tickets:read für Lese-Pfade.3
Filter auf Ansichten mappen
Pro Legacy-Listenfilter eine passende gespeicherte Ansicht anlegen oder finden.
4
Client-Code anpassen
Basis-URL, Envelope-Parsing und Cursor-Pagination umstellen.
5
Message/Thread-Fetch ergänzen
Workarounds durch
GET /tickets/:ticketNumber/messages ersetzen.6
In Staging testen
View-Zugriff für agent-verknüpfte vs. Service-Schlüssel prüfen.
7
Deployen und rotieren
v1-Client deployen, dann Legacy-only-Schlüssel löschen.
Dokumentation und Tools
OpenAPI v1
Interaktive Scalar-Docs für alle v1-Endpoints.
Legacy OpenAPI
Deprecated
/public/* (Sunset Okt 2026).Erste Schritte
Erster v1-Request Schritt für Schritt.
Agent-Tool-Beispiele
KI-Agenten-Muster auf v1.