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

# Migrando de v1/v2

> Migre suas integrações da API v1 ou v2 para a API atual

Este guia ajuda você a migrar integrações existentes da API v1 ou v2 para as APIs atuais de Organization e Enterprise. As APIs legadas (v1 e v2) continuarão funcionando durante o período de descontinuação, mas todos os novos recursos estarão disponíveis apenas na API atual.

<div id="whats-changing">
  ## O que está mudando
</div>

| Área             | v1/v2 (Legado)                                    | API atual                                         |
| ---------------- | ------------------------------------------------- | ------------------------------------------------- |
| **Autenticação** | Chaves de API (começam com `apk_user_` ou `apk_`) | Tokens de usuário de serviço (começam com `cog_`) |
| **URL base**     | `/v1/*`, `/v2/*`                                  | `/v3/organizations/*`, `/v3/enterprise/*`         |
| **Paginação**    | Baseada em deslocamento (`offset` + `limit`)      | Baseada em cursor (`first` + `after`)             |
| **Escopo**       | Linear — todos os endpoints em um único nível     | Com escopo por organização e por Enterprise       |
| **Permissões**   | No nível da chave (tudo ou nada)                  | Baseadas em função com permissões granulares      |

<div id="step-1-create-a-service-user">
  ## Etapa 1: Criar um usuário de serviço
</div>

Substitua sua chave de API legada por um usuário de serviço:

1. Acesse **Settings > Service users**
2. Crie um usuário de serviço com uma função adequada
3. Gere uma chave de API (começa com `cog_`)
4. Atualize sua integração para usar a nova chave

```bash theme={null}
# Antes (Chave de API legada)
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

# Depois (token de usuário de serviço)
curl -H "Authorization: Bearer cog_YOUR_SERVICE_USER_KEY" ...
```

<Note>
  Suas chaves de API legadas continuarão funcionando durante o período de descontinuação. Você pode migrar gradualmente.
</Note>

<div id="step-2-update-endpoint-urls">
  ## Etapa 2: Atualizar URLs dos endpoints
</div>

<div id="session-endpoints">
  ### Endpoints de sessão
</div>

| Operação        | Endpoint v1                             | Endpoint atual                                                 |
| --------------- | --------------------------------------- | -------------------------------------------------------------- |
| Criar sessão    | `POST /v1/sessions`                     | `POST /v3/organizations/{org_id}/sessions`                     |
| Listar sessões  | `GET /v1/sessions`                      | `GET /v3/organizations/{org_id}/sessions`                      |
| get sessão      | `GET /v1/session/{session_id}`          | `GET /v3/organizations/{org_id}/sessions/{devin_id}`           |
| Enviar mensagem | `POST /v1/session/{session_id}/message` | `POST /v3/organizations/{org_id}/sessions/{devin_id}/messages` |
| Arquivar sessão | —                                       | `POST /v3/organizations/{org_id}/sessions/{devin_id}/archive`  |
| Excluir sessão  | —                                       | `DELETE /v3/organizations/{org_id}/sessions/{devin_id}`        |

<div id="knowledge-endpoints">
  ### Endpoints do Knowledge
</div>

| Operação            | Endpoint v1                      | Endpoint atual                                                |
| ------------------- | -------------------------------- | ------------------------------------------------------------- |
| Listar Knowledge    | `GET /v1/knowledge`              | `GET /v3/organizations/{org_id}/knowledge/notes`              |
| Criar Knowledge     | `POST /v1/knowledge`             | `POST /v3/organizations/{org_id}/knowledge/notes`             |
| Atualizar Knowledge | `PUT /v1/knowledge/{note_id}`    | `PUT /v3/organizations/{org_id}/knowledge/notes/{note_id}`    |
| Excluir Knowledge   | `DELETE /v1/knowledge/{note_id}` | `DELETE /v3/organizations/{org_id}/knowledge/notes/{note_id}` |

<div id="playbook-endpoints">
  ### Endpoints de playbooks
</div>

| Operação           | Endpoint v1/v2                       | Endpoint atual                                              |
| ------------------ | ------------------------------------ | ----------------------------------------------------------- |
| Listar playbooks   | `GET /v1/playbooks`                  | `GET /v3/organizations/{org_id}/playbooks`                  |
| Criar 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}`    |
| Atualizar playbook | `PUT /v1/playbooks/{playbook_id}`    | `PUT /v3/organizations/{org_id}/playbooks/{playbook_id}`    |
| Excluir playbook   | `DELETE /v1/playbooks/{playbook_id}` | `DELETE /v3/organizations/{org_id}/playbooks/{playbook_id}` |

<div id="secret-endpoints">
  ### Endpoints de segredos
</div>

| Operação        | Endpoint v1                      | Endpoint atual                                          |
| --------------- | -------------------------------- | ------------------------------------------------------- |
| Listar segredos | `GET /v1/secrets`                | `GET /v3/organizations/{org_id}/secrets`                |
| Criar segredo   | `POST /v1/secrets`               | `POST /v3/organizations/{org_id}/secrets`               |
| Excluir segredo | `DELETE /v1/secrets/{secret_id}` | `DELETE /v3/organizations/{org_id}/secrets/{secret_id}` |

<div id="enterprise-only-endpoints-new">
  ### Endpoints exclusivos do Enterprise (novos)
</div>

Esses endpoints não têm equivalente nas versões v1/v2 — eles estão disponíveis apenas na API atual:

* `GET /v3/enterprise/organizations` — Listar organizações
* `GET /v3/enterprise/audit-logs` — Logs de auditoria
* `GET /v3/enterprise/consumption/*` — Dados de uso e cobrança
* `GET /v3/enterprise/metrics/*` — Métricas de uso
* `GET /v3/enterprise/members/users` — Gerenciamento de usuários
* `GET /v3/enterprise/roles` — Gerenciamento de funções
* Provisionamento de usuários de serviço, listas de acesso por IP, limites de ACU e mais

<div id="step-3-update-pagination">
  ## Etapa 3: Atualizar a paginação
</div>

A API atual usa paginação baseada em cursor, em vez de baseada em deslocamento:

```bash theme={null}
# Antes (v1/v2 baseado em deslocamento)
curl "https://api.devin.ai/v1/sessions?offset=0&limit=25"

# Depois (baseado em cursor)
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25"
# Em seguida, use `end_cursor` da resposta para a próxima página:
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25&after=CURSOR_VALUE"
```

Consulte [Paginação](/pt-BR/api-reference/concepts/pagination) para obter detalhes.

<div id="step-4-handle-response-format-changes">
  ## Etapa 4: Lidar com alterações no formato de resposta
</div>

<div id="session-status-values">
  ### Valores de status da sessão
</div>

A API atual retorna informações de status mais detalhadas. Consulte a referência do endpoint para ver o esquema completo.

<div id="error-responses">
  ### Respostas de erro
</div>

O formato das respostas de erro é consistente: código de status HTTP + corpo JSON com detalhes do erro.

<div id="deprecation-timeline">
  ## Cronograma de descontinuação
</div>

Chaves de API legadas exibem um banner de descontinuação na interface de configurações do Devin. Durante o período de transição:

* **Agora**: As chaves de API legadas continuam funcionando. Novas organizações podem não ter acesso à criação de chaves legadas.
* **Período de descontinuação**: Tanto as chaves legadas quanto os tokens de usuário de serviço funcionam em paralelo.
* **Fim do ciclo de vida**: As chaves de API legadas serão removidas em breve. Acompanhe suas configurações do Devin para novos comunicados.

Recomendamos migrar para usuários de serviço o mais rápido possível para aproveitar o controle de acesso baseado em função, atribuição de sessão e novos recursos.

<div id="need-help">
  ## Precisa de ajuda?
</div>

Se você tiver problemas durante a migração, entre em contato pelo seu canal de suporte habitual do Devin ou fale conosco em [support@cognition.ai](mailto:support@cognition.ai).