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

# Migration von v1/v2

> Migrieren Sie Ihre Integrationen von API v1 oder v2 auf die aktuelle API

Diese Anleitung hilft Ihnen, bestehende Integrationen von API v1 oder v2 auf die aktuellen Organization- und Enterprise-APIs zu migrieren. Die Legacy-APIs (v1 und v2) funktionieren während der Deprecation-Phase weiterhin, aber alle neuen Funktionen stehen nur in der aktuellen API zur Verfügung.

<div id="whats-changing">
  ## Was sich ändert
</div>

| Bereich               | v1/v2 (Legacy)                                  | Aktuelle API                                |
| --------------------- | ----------------------------------------------- | ------------------------------------------- |
| **Authentifizierung** | API keys (beginnen mit `apk_user_` oder `apk_`) | Service-User-Tokens (beginnen mit `cog_`)   |
| **Basis-URL**         | `/v1/*`, `/v2/*`                                | `/v3/organizations/*`, `/v3/enterprise/*`   |
| **Paginierung**       | Offset-basiert (`offset` + `limit`)             | Cursor-basiert (`first` + `after`)          |
| **Geltungsbereich**   | Flach – alle Endpunkte auf einer Ebene          | Organisationsbezogen und Enterprise-bezogen |
| **Berechtigungen**    | Auf Schlüssel-Ebene (alles oder nichts)         | Rollenbasiert mit granularen Berechtigungen |

<div id="step-1-create-a-service-user">
  ## Schritt 1: Dienstbenutzer erstellen
</div>

Ersetzen Sie Ihren bisherigen API key durch einen Dienstbenutzer:

1. Gehen Sie zu **Settings > Service users**
2. Erstellen Sie einen Dienstbenutzer mit einer geeigneten Rolle
3. Generieren Sie einen API key (beginnt mit `cog_`)
4. Aktualisieren Sie Ihre Integration, damit sie den neuen API key verwendet

```bash theme={null}
# Vorher (veralteter API key)
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

# Nachher (Service-User-Token)
curl -H "Authorization: Bearer cog_YOUR_SERVICE_USER_KEY" ...
```

<Note>
  Ihre Legacy-API keys funktionieren während der Auslaufphase weiterhin. Sie können die Migration schrittweise durchführen.
</Note>

<div id="step-2-update-endpoint-urls">
  ## Schritt 2: Endpunkt-URLs aktualisieren
</div>

<div id="session-endpoints">
  ### Sitzungsendpunkte
</div>

| Operation           | v1-Endpunkt                             | Aktueller Endpunkt                                             |
| ------------------- | --------------------------------------- | -------------------------------------------------------------- |
| Sitzung erstellen   | `POST /v1/sessions`                     | `POST /v3/organizations/{org_id}/sessions`                     |
| Sitzungen auflisten | `GET /v1/sessions`                      | `GET /v3/organizations/{org_id}/sessions`                      |
| Sitzung abrufen     | `GET /v1/session/{session_id}`          | `GET /v3/organizations/{org_id}/sessions/{devin_id}`           |
| Nachricht senden    | `POST /v1/session/{session_id}/message` | `POST /v3/organizations/{org_id}/sessions/{devin_id}/messages` |
| Sitzung archivieren | —                                       | `POST /v3/organizations/{org_id}/sessions/{devin_id}/archive`  |
| Sitzung löschen     | —                                       | `DELETE /v3/organizations/{org_id}/sessions/{devin_id}`        |

<div id="knowledge-endpoints">
  ### Knowledge-Endpunkte
</div>

| Operation               | v1-Endpunkt                      | Aktueller Endpunkt                                            |
| ----------------------- | -------------------------------- | ------------------------------------------------------------- |
| Knowledge auflisten     | `GET /v1/knowledge`              | `GET /v3/organizations/{org_id}/knowledge/notes`              |
| Knowledge erstellen     | `POST /v1/knowledge`             | `POST /v3/organizations/{org_id}/knowledge/notes`             |
| Knowledge aktualisieren | `PUT /v1/knowledge/{note_id}`    | `PUT /v3/organizations/{org_id}/knowledge/notes/{note_id}`    |
| Knowledge löschen       | `DELETE /v1/knowledge/{note_id}` | `DELETE /v3/organizations/{org_id}/knowledge/notes/{note_id}` |

<div id="playbook-endpoints">
  ### Playbook-Endpunkte
</div>

| Operation              | v1/v2-Endpunkt                       | Aktueller Endpunkt                                          |
| ---------------------- | ------------------------------------ | ----------------------------------------------------------- |
| Playbooks auflisten    | `GET /v1/playbooks`                  | `GET /v3/organizations/{org_id}/playbooks`                  |
| Playbook erstellen     | `POST /v1/playbooks`                 | `POST /v3/organizations/{org_id}/playbooks`                 |
| Playbook abrufen       | `GET /v1/playbooks/{playbook_id}`    | `GET /v3/organizations/{org_id}/playbooks/{playbook_id}`    |
| Playbook aktualisieren | `PUT /v1/playbooks/{playbook_id}`    | `PUT /v3/organizations/{org_id}/playbooks/{playbook_id}`    |
| Playbook löschen       | `DELETE /v1/playbooks/{playbook_id}` | `DELETE /v3/organizations/{org_id}/playbooks/{playbook_id}` |

<div id="secret-endpoints">
  ### Secrets-Endpunkte
</div>

| Operation         | v1-Endpunkt                      | Aktueller Endpunkt                                      |
| ----------------- | -------------------------------- | ------------------------------------------------------- |
| Secrets auflisten | `GET /v1/secrets`                | `GET /v3/organizations/{org_id}/secrets`                |
| Secret erstellen  | `POST /v1/secrets`               | `POST /v3/organizations/{org_id}/secrets`               |
| Secret löschen    | `DELETE /v1/secrets/{secret_id}` | `DELETE /v3/organizations/{org_id}/secrets/{secret_id}` |

<div id="enterprise-only-endpoints-new">
  ### Nur für Enterprise verfügbare Endpunkte (neu)
</div>

Diese Endpunkte haben keine v1-/v2-Entsprechung — sie sind nur in der aktuellen API-Version verfügbar:

* `GET /v3/enterprise/organizations` — Organisationen auflisten
* `GET /v3/enterprise/audit-logs` — Audit-Logs
* `GET /v3/enterprise/consumption/*` — Nutzungs- und Abrechnungsdaten
* `GET /v3/enterprise/metrics/*` — Nutzungsmetriken
* `GET /v3/enterprise/members/users` — Benutzerverwaltung
* `GET /v3/enterprise/roles` — Rollenverwaltung
* Bereitstellung von Servicebenutzern, IP-Zugriffslisten, ACU-Limits und mehr

<div id="step-3-update-pagination">
  ## Schritt 3: Paginierung aktualisieren
</div>

Die aktuelle API verwendet cursor-basierte Paginierung anstelle einer offset-basierten Paginierung:

```bash theme={null}
# Before (v1/v2 offset-based)
curl "https://api.devin.ai/v1/sessions?offset=0&limit=25"

# After (cursor-based)
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25"
# Then use `end_cursor` from the response for the next page:
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25&after=CURSOR_VALUE"
```

Siehe [Paginierung](/de/api-reference/concepts/pagination) für Details.

<div id="step-4-handle-response-format-changes">
  ## Schritt 4: Umgang mit Änderungen am Antwortformat
</div>

<div id="session-status-values">
  ### Statuswerte für Sitzungen
</div>

Die aktuelle API liefert detailliertere Statusinformationen. Weitere Details zum vollständigen Schema finden Sie in der Endpoint-Referenz.

<div id="error-responses">
  ### Fehlerantworten
</div>

Das Fehlerformat ist einheitlich: HTTP-Statuscode + JSON-Objekt mit Fehlerdetails.

<div id="deprecation-timeline">
  ## Zeitplan für die Außerbetriebnahme
</div>

Veraltete API keys zeigen ein Hinweisbanner zur Außerbetriebnahme in den Devin-Einstellungen an. Während der Übergangsphase:

* **Jetzt**: Veraltete API keys funktionieren weiterhin. Neue Organisationen haben möglicherweise keinen Zugriff mehr auf die Erstellung solcher Schlüssel.
* **Außerbetriebnahmezeitraum**: Sowohl veraltete Schlüssel als auch Servicebenutzer-Tokens funktionieren parallel.
* **Ende der Lebensdauer**: Veraltete API keys werden bald entfernt. Prüfen Sie regelmäßig Ihre Devin-Einstellungen auf entsprechende Ankündigungen.

Wir empfehlen, so bald wie möglich auf Servicebenutzer zu migrieren, um von rollenbasierter Zugriffskontrolle, Sitzungszuordnung und neuen Funktionen zu profitieren.

<div id="need-help">
  ## Benötigen Sie Hilfe?
</div>

Wenn während der Migration Probleme auftreten, wenden Sie sich über Ihren üblichen Devin Support-Kanal an uns oder kontaktieren Sie uns unter [support@cognition.ai](mailto:support@cognition.ai).