> ## Documentation Index
> Fetch the complete documentation index at: https://docs.armin.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration von Legacy /public

> Von deprecated /public/* auf /public/v1 — Envelope, Pagination und Scopes.

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):**

```json theme={null}
{
  "success": true,
  "tickets": [ ... ],
  "page": 1,
  "total_pages": 10
}
```

**v1-Liste:**

```json theme={null}
{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "next_cursor": "..."
  }
}
```

**Legacy-Fehler:**

```json theme={null}
{
  "success": false,
  "message": "Something went wrong",
  "error": "..."
}
```

**v1-Fehler:**

```json theme={null}
{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "request_id": "req_..."
}
```

Auf `code` prüfen, nicht auf `message`. Siehe [Fehler](/de/api/errors).

## 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](/de/api/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

<Steps>
  <Step title="Legacy-Nutzung auditieren">
    Welche `/public/*`-Endpoints ruft deine Integration heute auf?
  </Step>

  <Step title="Scoped v1-Schlüssel erstellen">
    [Einstellungen → API](https://armin.cx/app/_/settings/api) — `tickets:read` für Lese-Pfade.
  </Step>

  <Step title="Filter auf Ansichten mappen">
    Pro Legacy-Listenfilter eine passende [gespeicherte Ansicht](/de/inbox/views-and-filters) anlegen oder finden.
  </Step>

  <Step title="Client-Code anpassen">
    Basis-URL, Envelope-Parsing und Cursor-Pagination umstellen.
  </Step>

  <Step title="Message/Thread-Fetch ergänzen">
    Workarounds durch `GET /tickets/:ticketNumber/messages` ersetzen.
  </Step>

  <Step title="In Staging testen">
    View-Zugriff für agent-verknüpfte vs. Service-Schlüssel prüfen.
  </Step>

  <Step title="Deployen und rotieren">
    v1-Client deployen, dann Legacy-only-Schlüssel löschen.
  </Step>
</Steps>

## Dokumentation und Tools

<CardGroup cols={2}>
  <Card title="OpenAPI v1" icon="book" href="https://api.armin.cx/docs/v1">
    Interaktive Scalar-Docs für alle v1-Endpoints.
  </Card>

  <Card title="Legacy OpenAPI" icon="book-open" href="https://api.armin.cx/docs">
    Deprecated `/public/*` (Sunset Okt 2026).
  </Card>

  <Card title="Erste Schritte" icon="rocket" href="/de/api/getting-started">
    Erster v1-Request Schritt für Schritt.
  </Card>

  <Card title="Agent-Tool-Beispiele" icon="robot" href="/de/api/agent-tool-examples">
    KI-Agenten-Muster auf v1.
  </Card>
</CardGroup>

## Zeitplan

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

<Warning>
  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.
</Warning>