Migrando de v1/v2 - Devin Docs

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.

O que está mudando

Á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

Etapa 1: Criar um usuário de serviço

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

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

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

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

Etapa 2: Atualizar URLs dos endpoints

Endpoints de sessão

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

Endpoints do Knowledge

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

Endpoints de playbooks

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

Endpoints de segredos

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

Endpoints exclusivos do Enterprise (novos)

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

Etapa 3: Atualizar a paginação

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

# 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 para obter detalhes.

Etapa 4: Lidar com alterações no formato de resposta

Valores de status da sessão

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

Respostas de erro

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

Cronograma de descontinuação

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.

Precisa de ajuda?

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.

​O que está mudando

​Etapa 1: Criar um usuário de serviço

​Etapa 2: Atualizar URLs dos endpoints

​Endpoints de sessão

​Endpoints do Knowledge

​Endpoints de playbooks

​Endpoints de segredos

​Endpoints exclusivos do Enterprise (novos)

​Etapa 3: Atualizar a paginação

​Etapa 4: Lidar com alterações no formato de resposta

​Valores de status da sessão

​Respostas de erro

​Cronograma de descontinuação

​Precisa de ajuda?

O que está mudando

Etapa 1: Criar um usuário de serviço

Etapa 2: Atualizar URLs dos endpoints

Endpoints de sessão

Endpoints do Knowledge

Endpoints de playbooks

Endpoints de segredos

Endpoints exclusivos do Enterprise (novos)

Etapa 3: Atualizar a paginação

Etapa 4: Lidar com alterações no formato de resposta

Valores de status da sessão

Respostas de erro

Cronograma de descontinuação

Precisa de ajuda?