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:
- Go to Settings > Service users
- Create a service user with an appropriate role
- Generate an API key (starts with
cog_)
- 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/sessions |
| List sessions | GET /v1/sessions | GET /v3/organizations/sessions |
| Get session | GET /v1/session/{session_id} | GET /v3/organizations/sessions/{devin_id} |
| Send message | POST /v1/session/{session_id}/message | POST /v3/organizations/sessions/{devin_id}/messages |
| Archive session | — | POST /v3/organizations/sessions/{devin_id}/archive |
| Delete session | — | DELETE /v3/organizations/sessions/{devin_id} |
Knowledge endpoints
| Operation | v1 endpoint | Current endpoint |
|---|
| List knowledge | GET /v1/knowledge | GET /v3/organizations/knowledge/notes |
| Create knowledge | POST /v1/knowledge | POST /v3/organizations/knowledge/notes |
| Update knowledge | PUT /v1/knowledge/{note_id} | PUT /v3/organizations/knowledge/notes/{note_id} |
| Delete knowledge | DELETE /v1/knowledge/{note_id} | DELETE /v3/organizations/knowledge/notes/{note_id} |
Playbook endpoints
| Operation | v1/v2 endpoint | Current endpoint |
|---|
| List playbooks | GET /v1/playbooks | GET /v3/organizations/playbooks |
| Create playbook | POST /v1/playbooks | POST /v3/organizations/playbooks |
| Get playbook | GET /v1/playbooks/{playbook_id} | GET /v3/organizations/playbooks/{playbook_id} |
| Update playbook | PUT /v1/playbooks/{playbook_id} | PUT /v3/organizations/playbooks/{playbook_id} |
| Delete playbook | DELETE /v1/playbooks/{playbook_id} | DELETE /v3/organizations/playbooks/{playbook_id} |
Secret endpoints
| Operation | v1 endpoint | Current endpoint |
|---|
| List secrets | GET /v1/secrets | GET /v3/organizations/secrets |
| Create secret | POST /v1/secrets | POST /v3/organizations/secrets |
| Delete secret | DELETE /v1/secrets/{secret_id} | DELETE /v3/organizations/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 organizationsGET /v3/enterprise/audit-logs — Audit logsGET /v3/enterprise/consumption/* — Usage and billing dataGET /v3/enterprise/metrics/* — Usage metricsGET /v3/enterprise/members/users — User managementGET /v3/enterprise/roles — Role management- Service user provisioning, IP access lists, ACU limits, and more
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/sessions?first=25"
# Then use `end_cursor` from the response for the next page:
curl "https://api.devin.ai/v3/organizations/sessions?first=25&after=CURSOR_VALUE"
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 support@cognition.ai. 