Zum Hauptinhalt springen
Legacy-Endpoints unter /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):
v1-Liste:
Legacy-Fehler:
v1-Fehler:
Auf 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-Endpoint POST /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.
Vorher (Legacy-Export, höchstens 500 Tickets, die Datei ist die Antwort):
Nachher (v1-Export, bis zu 50.000 Tickets, im Hintergrund):

Backfill

Bisher musste ein Backfill unter 500 Tickets pro Anfrage bleiben und lieferte darüber 413 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:
Nachher:
Frage den Export ab, lade die Datei herunter und lege dann den nächsten Zeitraum an. Trifft ein Zeitraum auf mehr als 50.000 Tickets, schlägt die Anfrage mit 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.

Zeitplan

Migriere vor dem Sunset. Legacy Analytics hat noch kein v1-Pendant — scoped Legacy-Schlüssel nur für diese Aufrufe behalten, bis v2.