Skip to main content
This guide helps you migrate existing integrations from API v1 or v2 to the current Organization and Enterprise APIs. The legacy APIs (v1 and v2) will continue to work during the deprecation period, but all new features are only available in the current API.

What’s changing

Step 1: Create a service user

Replace your legacy API key with a service user:
  1. Go to Settings > Devin API and open the Service users tab
  2. Click Provision service user, assign an appropriate role, and choose an expiration (30 days by default)
  3. Copy the API key shown after provisioning (starts with cog_)
  4. Update your integration to use the new key
Your legacy API keys will continue to work during the deprecation period. You can migrate incrementally.

Step 2: Update endpoint URLs

Session endpoints

Knowledge endpoints

Playbook endpoints

The /playbooks endpoints are deprecated in every API version. Playbooks are moving to Skills. Create new instructions as skills on the Customize page. An account created on or after October 24, 2026 with no playbooks gets 410 from these endpoints. See Playbooks are moving to Skills.

Secret endpoints

Enterprise-only endpoints (new)

These endpoints have no v1/v2 equivalent — they are only available in the current API:
  • GET /v3/enterprise/organizations — List organizations
  • GET /v3/enterprise/audit-logs — Audit logs
  • GET /v3/enterprise/consumption/* — Usage and billing data
  • GET /v3/enterprise/metrics/* — Usage metrics
  • GET /v3/enterprise/members/users — User management
  • GET /v3/enterprise/roles — Role management
  • Service user provisioning, IP access lists, ACU limits, and more

Step 3: Update pagination

The current API uses cursor-based pagination instead of offset-based:
See Pagination for details.

Step 4: Handle response format changes

Session status values

The current API returns more detailed status information. See the endpoint reference for the full schema.

Error responses

The current API returns errors in the RFC 9457 format, with the application/problem+json content type. The body has type, title, and status members. It can also have detail, instance, errors, and error_code members. The legacy APIs return a JSON body with a detail member. On 422 responses in the current API, detail is a string, and the errors member has the field-level errors.

Deprecation timeline

Settings > Devin API lists legacy keys on the API keys (legacy) tab. Enterprise settings > Devin API lists them on the Legacy API tab, which shows a deprecation banner. During the transition period:
  • Now: Legacy API keys continue to work. New organizations may not have access to legacy key creation.
  • Deprecation period: Both legacy keys and service user tokens work side-by-side.
  • End of life: Legacy API keys will be removed soon. Monitor your Devin settings for announcements.
We recommend migrating to service users as soon as possible to take advantage of role-based access control, session attribution, and new features.

Need help?

If you encounter issues during migration, reach out through your usual Devin support channel or contact us at support@cognition.ai.