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

# 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

```bash theme={null}
# 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" ...
```

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

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

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

See [Pagination](/api-reference/concepts/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 [support@cognition.ai](mailto:support@cognition.ai).