Migrating from v1/v2

Migrate your integrations from API v1 or v2 to the current API

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

Area	v1/v2 (Legacy)	Current API
Authentication	API keys (starts with apk_user_ or apk_)	Service user tokens (starts with cog_)
Base URL	/v1/*, /v2/*	/v3/organizations/*, /v3/enterprise/*
Pagination	Offset-based (offset + limit)	Cursor-based (first + after)
Scoping	Flat — all endpoints at one level	Org-scoped and enterprise-scoped
Permissions	Key-level (all or nothing)	Role-based with granular permissions

Step 1: Create a service user

Replace your legacy API key with a service user:

1. Go to Settings > Service users
2. Create a service user with an appropriate role
3. Generate an API key (starts with cog_)
4. Update your integration to use the new key

# Before (legacy API key)
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

# After (service user token)
curl -H "Authorization: Bearer cog_YOUR_SERVICE_USER_KEY" ...

Your legacy API keys will continue to work during the deprecation period. You can migrate incrementally.

Step 2: Update endpoint URLs

Session endpoints

Operation	v1 endpoint	Current endpoint
Create session	POST /v1/sessions	POST /v3/organizations/{org_id}/sessions
List sessions	GET /v1/sessions	GET /v3/organizations/{org_id}/sessions
Get session	GET /v1/session/{session_id}	GET /v3/organizations/{org_id}/sessions/{devin_id}
Send message	POST /v1/session/{session_id}/message	POST /v3/organizations/{org_id}/sessions/{devin_id}/messages
Archive session	—	POST /v3/organizations/{org_id}/sessions/{devin_id}/archive
Delete session	—	DELETE /v3/organizations/{org_id}/sessions/{devin_id}

Knowledge endpoints

Operation	v1 endpoint	Current endpoint
List knowledge	GET /v1/knowledge	GET /v3/organizations/{org_id}/knowledge/notes
Create knowledge	POST /v1/knowledge	POST /v3/organizations/{org_id}/knowledge/notes
Update knowledge	PUT /v1/knowledge/{note_id}	PUT /v3/organizations/{org_id}/knowledge/notes/{note_id}
Delete knowledge	DELETE /v1/knowledge/{note_id}	DELETE /v3/organizations/{org_id}/knowledge/notes/{note_id}

Playbook endpoints

Operation	v1/v2 endpoint	Current endpoint
List playbooks	GET /v1/playbooks	GET /v3/organizations/{org_id}/playbooks
Create playbook	POST /v1/playbooks	POST /v3/organizations/{org_id}/playbooks
Get playbook	GET /v1/playbooks/{playbook_id}	GET /v3/organizations/{org_id}/playbooks/{playbook_id}
Update playbook	PUT /v1/playbooks/{playbook_id}	PUT /v3/organizations/{org_id}/playbooks/{playbook_id}
Delete playbook	DELETE /v1/playbooks/{playbook_id}	DELETE /v3/organizations/{org_id}/playbooks/{playbook_id}

Secret endpoints

Operation	v1 endpoint	Current endpoint
List secrets	GET /v1/secrets	GET /v3/organizations/{org_id}/secrets
Create secret	POST /v1/secrets	POST /v3/organizations/{org_id}/secrets
Delete secret	DELETE /v1/secrets/{secret_id}	DELETE /v3/organizations/{org_id}/secrets/{secret_id}

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:

# 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"

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

Error format remains consistent: HTTP status code + JSON body with error details.

Deprecation timeline

Legacy API keys show a deprecation banner in the Devin settings UI. 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 [e-mail].