Migration von v1/v2

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.

Was sich ändert

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

Schritt 1: Service-Benutzer erstellen

Ersetzen Sie Ihren veralteten API-Schlüssel durch einen Service-Benutzer:

Gehen Sie zu Settings > Devin API und öffnen Sie den Tab Service-Benutzer
Klicken Sie auf Provision Service-Benutzer und weisen Sie eine geeignete Rolle zu
Kopieren Sie den nach dem Provisioning angezeigten API key (beginnt mit cog_)
Aktualisieren Sie Ihre Integration, damit sie den neuen API key verwendet

# Vorher (veralteter API-Schlüssel)
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

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

Ihre veralteten API-Schlüssel funktionieren während der Deprecation-Phase weiterhin. Sie können die Migration schrittweise durchführen.

Schritt 2: Endpunkt-URLs aktualisieren

Sitzungsendpunkte

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}`

Knowledge-Endpunkte

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}`

Playbook-Endpunkte

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}`

Secrets-Endpunkte

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}`

Nur für Enterprise verfügbare Endpunkte (neu)

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

Schritt 3: Paginierung aktualisieren

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

# 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 für Details.

Schritt 4: Umgang mit Änderungen am Antwortformat

Statuswerte für Sitzungen

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

Fehlerantworten

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

Zeitplan für die Außerbetriebnahme

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.

Benötigen Sie Hilfe?

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.

Erste Schritte

Konzepte

Agent Lifecycle

Kontextverwaltung

Umgebungsverwaltung

Automatisierung

Integrationen

Analytics

Observability

Devin für Sicherheit

Infrastruktur

Identität & Zugriff

Konfiguration

Legacy API v1

Legacy API v2

Was sich ändert

Schritt 1: Service-Benutzer erstellen

Schritt 2: Endpunkt-URLs aktualisieren

Sitzungsendpunkte

Knowledge-Endpunkte

Playbook-Endpunkte

Secrets-Endpunkte

Nur für Enterprise verfügbare Endpunkte (neu)

Schritt 4: Umgang mit Änderungen am Antwortformat

Statuswerte für Sitzungen

Fehlerantworten

Zeitplan für die Außerbetriebnahme

Benötigen Sie Hilfe?

​Was sich ändert

​Schritt 1: Service-Benutzer erstellen

​Schritt 2: Endpunkt-URLs aktualisieren

​Sitzungsendpunkte

​Knowledge-Endpunkte

​Playbook-Endpunkte

​Secrets-Endpunkte

​Nur für Enterprise verfügbare Endpunkte (neu)

​Schritt 3: Paginierung aktualisieren

​Schritt 4: Umgang mit Änderungen am Antwortformat

​Statuswerte für Sitzungen

​Fehlerantworten

​Zeitplan für die Außerbetriebnahme

​Benötigen Sie Hilfe?

Was sich ändert

Schritt 1: Service-Benutzer erstellen

Schritt 2: Endpunkt-URLs aktualisieren

Sitzungsendpunkte

Knowledge-Endpunkte

Playbook-Endpunkte

Secrets-Endpunkte

Nur für Enterprise verfügbare Endpunkte (neu)

Schritt 3: Paginierung aktualisieren

Schritt 4: Umgang mit Änderungen am Antwortformat

Statuswerte für Sitzungen

Fehlerantworten

Zeitplan für die Außerbetriebnahme

Benötigen Sie Hilfe?