Saltar al contenido principal
Esta guía explica cómo migrar integraciones existentes de la API v1 o v2 a las API actuales de Organización y Enterprise. Las API heredadas (v1 y v2) seguirán funcionando durante el período de deprecación, pero todas las nuevas funcionalidades solo están disponibles en la API actual.

​
Qué está cambiando

Áreav1/v2 (legado)API actual
AutenticaciónAPI keys (empiezan con apk_user_ o apk_)Tokens de usuario de servicio (empiezan con cog_)
URL base/v1/*, /v2/*/v3/organizations/*, /v3/enterprise/*
PaginaciónBasada en desplazamiento (offset + limit)Basada en cursor (first + after)
AlcancePlano: todos los endpoints en un único nivelCon alcance de organización y de Enterprise
PermisosA nivel de clave (todo o nada)Basados en roles con permisos granulares

​
Paso 1: Crear un usuario de servicio

Reemplaza tu API key heredada por un usuario de servicio:
  1. Ve a Settings > Service users
  2. Crea un usuario de servicio con un rol adecuado
  3. Genera una API key (empieza con cog_)
  4. Actualiza tu integración para usar la nueva clave
# Antes (API key heredada)
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

# Después (token de usuario de servicio)
curl -H "Authorization: Bearer cog_YOUR_SERVICE_USER_KEY" ...
Tus API keys anteriores seguirán funcionando durante el período de deprecación. Podrás migrar gradualmente.

​
Paso 2: Actualizar las URL de los endpoints

​
Endpoints de sesión

OperaciónEndpoint v1Endpoint actual
Crear sesiónPOST /v1/sessionsPOST /v3/organizations/sessions
Listar sesionesGET /v1/sessionsGET /v3/organizations/sessions
Obtener sesiónGET /v1/session/{session_id}GET /v3/organizations/sessions/{devin_id}
Enviar mensajePOST /v1/session/{session_id}/messagePOST /v3/organizations/sessions/{devin_id}/messages
Archivar sesión—POST /v3/organizations/sessions/{devin_id}/archive
Eliminar sesión—DELETE /v3/organizations/sessions/{devin_id}

​
Endpoints de Knowledge

OperaciónEndpoint v1Endpoint actual
Listar KnowledgeGET /v1/knowledgeGET /v3/organizations/knowledge/notes
Crear KnowledgePOST /v1/knowledgePOST /v3/organizations/knowledge/notes
Actualizar KnowledgePUT /v1/knowledge/{note_id}PUT /v3/organizations/knowledge/notes/{note_id}
Eliminar KnowledgeDELETE /v1/knowledge/{note_id}DELETE /v3/organizations/knowledge/notes/{note_id}

​
Endpoints de playbooks

Operaciónendpoint v1/v2endpoint actual
Listar playbooksGET /v1/playbooksGET /v3/organizations/playbooks
Crear playbookPOST /v1/playbooksPOST /v3/organizations/playbooks
Obtener playbookGET /v1/playbooks/{playbook_id}GET /v3/organizations/playbooks/{playbook_id}
Actualizar playbookPUT /v1/playbooks/{playbook_id}PUT /v3/organizations/playbooks/{playbook_id}
Eliminar playbookDELETE /v1/playbooks/{playbook_id}DELETE /v3/organizations/playbooks/{playbook_id}

​
Endpoints de secretos

OperaciónEndpoint v1Endpoint actual
Listar secretosGET /v1/secretsGET /v3/organizations/secrets
Crear secretoPOST /v1/secretsPOST /v3/organizations/secrets
Eliminar secretoDELETE /v1/secrets/{secret_id}DELETE /v3/organizations/secrets/{secret_id}

​
Endpoints exclusivos de Enterprise (nuevo)

Estos endpoints no tienen equivalente en v1/v2: solo están disponibles en la versión actual de la API:
  • GET /v3/enterprise/organizations — Listar organizaciones
  • GET /v3/enterprise/audit-logs — Registros de auditoría
  • GET /v3/enterprise/consumption/* — Datos de uso y facturación
  • GET /v3/enterprise/metrics/* — Métricas de uso
  • GET /v3/enterprise/members/users — Administración de usuarios
  • GET /v3/enterprise/roles — Administración de roles
  • Aprovisionamiento de usuarios de servicio, listas de acceso por IP, límites de ACU y más

​
Paso 3: Actualizar la paginación

La API actual usa paginación basada en cursor en lugar de paginación basada en offsets: 
# Antes (v1/v2 basado en offset)
curl "https://api.devin.ai/v1/sessions?offset=0&limit=25"

# Después (basado en cursor)
curl "https://api.devin.ai/v3/organizations/sessions?first=25"
# Luego usa `end_cursor` de la respuesta para la siguiente página:
curl "https://api.devin.ai/v3/organizations/sessions?first=25&after=CURSOR_VALUE"
Consulta Paginación para obtener más detalles.

​
Paso 4: Gestionar los cambios en el formato de la respuesta

​
Valores de estado de la sesión

La API actual devuelve información de estado más detallada. Consulta la referencia del endpoint para conocer el esquema completo.

​
Respuestas de error

El formato de las respuestas de error es coherente: código de estado HTTP + cuerpo JSON con detalles del error.

​
Cronograma de obsolescencia

Las API keys heredadas muestran un banner de obsolescencia en la interfaz de configuración de Devin. Durante el período de transición:
  • Ahora: Las API keys heredadas siguen funcionando. Es posible que las organizaciones nuevas no tengan acceso a la creación de keys heredadas.
  • Período de obsolescencia: Tanto las keys heredadas como los tokens de usuarios de servicio funcionan en paralelo.
  • Fin de vida útil: Las API keys heredadas se eliminarán pronto. Supervisa la configuración de Devin para ver los anuncios.
Recomendamos migrar a usuarios de servicio lo antes posible para aprovechar el control de acceso basado en roles, la atribución de sesiones y las nuevas funciones.

​
¿Necesitas ayuda?

Si tienes problemas durante la migración, ponte en contacto a través de tu canal de soporte habitual de Devin o escríbenos a support@cognition.ai.