Pular para o conteúdo principal
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

Áreav1/v2 (Legado)API atual
AutenticaçãoChaves 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çãoBaseada em deslocamento (offset + limit)Baseada em cursor (first + after)
EscopoLinear — todos os endpoints em um único nívelCom escopo por organização e por Enterprise
PermissõesNo 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:
  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
# 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çãoEndpoint v1Endpoint atual
Criar sessãoPOST /v1/sessionsPOST /v3/organizations/sessions
Listar sessõesGET /v1/sessionsGET /v3/organizations/sessions
Recuperar sessãoGET /v1/session/{session_id}GET /v3/organizations/sessions/{devin_id}
Enviar mensagemPOST /v1/session/{session_id}/messagePOST /v3/organizations/sessions/{devin_id}/messages
Arquivar sessão—POST /v3/organizations/sessions/{devin_id}/archive
Excluir sessão—DELETE /v3/organizations/sessions/{devin_id}

​
Endpoints do Knowledge

OperaçãoEndpoint v1Endpoint atual
Listar KnowledgeGET /v1/knowledgeGET /v3/organizations/knowledge/notes
Criar KnowledgePOST /v1/knowledgePOST /v3/organizations/knowledge/notes
Atualizar KnowledgePUT /v1/knowledge/{note_id}PUT /v3/organizations/knowledge/notes/{note_id}
Excluir KnowledgeDELETE /v1/knowledge/{note_id}DELETE /v3/organizations/knowledge/notes/{note_id}

​
Endpoints de playbooks

OperaçãoEndpoint v1/v2Endpoint atual
Listar playbooksGET /v1/playbooksGET /v3/organizations/playbooks
Criar playbookPOST /v1/playbooksPOST /v3/organizations/playbooks
Obter playbookGET /v1/playbooks/{playbook_id}GET /v3/organizations/playbooks/{playbook_id}
Atualizar playbookPUT /v1/playbooks/{playbook_id}PUT /v3/organizations/playbooks/{playbook_id}
Excluir playbookDELETE /v1/playbooks/{playbook_id}DELETE /v3/organizations/playbooks/{playbook_id}

​
Endpoints de segredos

OperaçãoEndpoint v1Endpoint atual
Listar segredosGET /v1/secretsGET /v3/organizations/secrets
Criar segredoPOST /v1/secretsPOST /v3/organizations/secrets
Excluir segredoDELETE /v1/secrets/{secret_id}DELETE /v3/organizations/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 offset: 
# Antes (v1/v2 baseado em offset)
curl "https://api.devin.ai/v1/sessions?offset=0&limit=25"

# Depois (baseado em cursor)
curl "https://api.devin.ai/v3/organizations/sessions?first=25"
# Em seguida, use `end_cursor` da resposta para a próxima página:
curl "https://api.devin.ai/v3/organizations/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.