Migration von Legacy /public - Chatarmin CX Docs

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:

Deprecation: true
Sunset: Fri, 31 Oct 2026 23:59:59 GMT
Link: <https://docs.armin.cx/api/v1/migration>; rel="successor-version"

Warum migrieren

Legacy `/public/*`	Public API v1 `/public/v1/*`
Uneinheitliche Envelopes	Einheitlich `{ success, data }` + strukturierte Fehler
Offset-Pagination (`page`, `page_size`)	Cursor (`cursor`, `has_more`, `next_cursor`)
Ad-hoc-Listenfilter (Datum, Status)	Gespeicherte Ansichten via `view_id`
Vollzugriff-Schlüssel	Scoped Keys (Default `tickets:read`)
Kein Message-Thread-Endpoint	`GET /tickets/:ticketNumber/messages`
Keine Ansichten-Liste	`GET /views`

Basis-URL

	URL
Legacy	`https://api.armin.cx/public`
v1	`https://api.armin.cx/public/v1`

Authentifizierung unverändert: Header cx-api-key.

Response-Envelope

Legacy-Liste (Beispiel):

{
  "success": true,
  "tickets": [ ... ],
  "page": 1,
  "total_pages": 10
}

v1-Liste:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "next_cursor": "..."
  }
}

Legacy-Fehler:

{
  "success": false,
  "message": "Something went wrong",
  "error": "..."
}

v1-Fehler:

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "request_id": "req_..."
}

Auf code prüfen, nicht auf message. Siehe Fehler.

Pagination migrieren

Legacy	v1
`page=2&page_size=50`	`cursor=<next_cursor>&limit=50`
`total_pages` / Total im Body	`pagination.has_more` + `next_cursor` (kein Total bei Ticket-Listen)
Seite 1 zum Polling neu laden	Cursor + Backoff; View-`count` für Totals

Siehe Pagination.

Endpoint-Mapping

Legacy-Endpoint	v1-Äquivalent	Hinweise
`GET /public/tickets` (Liste)	`GET /public/v1/views` + `GET /public/v1/tickets?view_id=...`	Listenfilter in gespeicherter Ansicht
`GET /public/tickets` (mit Datum/Filter)	Gespeicherte Ansicht + `view_id`	Kein `date_from` / `date_to` in v1
`GET /public/tickets/:id`	`GET /public/v1/tickets/:ticketNumber`	v1 nutzt numerische Ticketnummer im Pfad
—	`GET /public/v1/tickets/:ticketNumber/messages`	Neu — Konversations-Thread für Agenten
—	`GET /public/v1/views`	Neu — gespeicherte Ansichten entdecken
`POST /public/tickets`	Kein v1-Äquivalent	Legacy bis v2; braucht `tickets:write`
`POST /public/tickets/export`	Kein v1-Äquivalent	Legacy; `tickets:export`
`GET /public/tickets/statistics`	Kein v1-Äquivalent	Legacy; `analytics:read`
`GET /public/agents/metrics`	Kein v1-Äquivalent	Legacy; `analytics:read`

Scopes während der Migration

Neue Schlüssel mit expliziten Scopes:

Integration	Empfohlene Scopes
Reiner Lese-Agent / Sync	nur `tickets:read`
Legacy Ticket erstellen	`tickets:read` + `tickets:write`
Legacy Export	`tickets:read` + `tickets:export`
Legacy Analytics	`tickets:read` + `analytics:read`

Leere scopes (vor Migration) = weiterhin Vollzugriff bis zur Rotation.

Migrations-Checkliste

Legacy-Nutzung auditieren

Welche /public/*-Endpoints ruft deine Integration heute auf?

Scoped v1-Schlüssel erstellen

Einstellungen → API — tickets:read für Lese-Pfade.

Filter auf Ansichten mappen

Pro Legacy-Listenfilter eine passende gespeicherte Ansicht anlegen oder finden.

Client-Code anpassen

Basis-URL, Envelope-Parsing und Cursor-Pagination umstellen.

Message/Thread-Fetch ergänzen

Workarounds durch GET /tickets/:ticketNumber/messages ersetzen.

In Staging testen

View-Zugriff für agent-verknüpfte vs. Service-Schlüssel prüfen.

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

Datum	Ereignis
v1 GA	`/public/v1/*` für alle neuen Integrationen empfohlen
2026-10-31	Legacy `/public/*` Sunset — Endpoints können entfernt werden

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

​Warum migrieren

​Basis-URL

​Response-Envelope

​Pagination migrieren

​Endpoint-Mapping

​Scopes während der Migration

​Migrations-Checkliste

​Dokumentation und Tools

OpenAPI v1

Legacy OpenAPI

Erste Schritte

Agent-Tool-Beispiele

​Zeitplan

Warum migrieren

Basis-URL

Response-Envelope

Pagination migrieren

Endpoint-Mapping

Scopes während der Migration

Migrations-Checkliste

Dokumentation und Tools

Zeitplan