Migración desde v1/v2

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

Área	v1/v2 (legado)	API actual
Autenticación	API keys (empiezan con `apk_user_` o `apk_`)	Tokens de usuario de servicio (empiezan con `cog_`)
URL base	`/v1/`, `/v2/`	`/v3/organizations/`, `/v3/enterprise/`
Paginación	Basada en desplazamiento (`offset` + `limit`)	Basada en cursor (`first` + `after`)
Alcance	Plano: todos los endpoints en un único nivel	Con alcance de organización y de Enterprise
Permisos	A 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:

Ve a Settings > Service users
Crea un usuario de servicio con un rol adecuado
Genera una API key (empieza con cog_)
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ón	Endpoint v1	Endpoint actual
Crear sesión	`POST /v1/sessions`	`POST /v3/organizations/{org_id}/sessions`
Listar sesiones	`GET /v1/sessions`	`GET /v3/organizations/{org_id}/sessions`
Obtener sesión	`GET /v1/session/{session_id}`	`GET /v3/organizations/{org_id}/sessions/{devin_id}`
Enviar mensaje	`POST /v1/session/{session_id}/message`	`POST /v3/organizations/{org_id}/sessions/{devin_id}/messages`
Archivar sesión	—	`POST /v3/organizations/{org_id}/sessions/{devin_id}/archive`
Eliminar sesión	—	`DELETE /v3/organizations/{org_id}/sessions/{devin_id}`

Endpoints de Knowledge

Operación	Endpoint v1	Endpoint actual
Listar Knowledge	`GET /v1/knowledge`	`GET /v3/organizations/{org_id}/knowledge/notes`
Crear Knowledge	`POST /v1/knowledge`	`POST /v3/organizations/{org_id}/knowledge/notes`
Actualizar Knowledge	`PUT /v1/knowledge/{note_id}`	`PUT /v3/organizations/{org_id}/knowledge/notes/{note_id}`
Eliminar Knowledge	`DELETE /v1/knowledge/{note_id}`	`DELETE /v3/organizations/{org_id}/knowledge/notes/{note_id}`

Endpoints de playbooks

Operación	endpoint v1/v2	endpoint actual
Listar playbooks	`GET /v1/playbooks`	`GET /v3/organizations/{org_id}/playbooks`
Crear playbook	`POST /v1/playbooks`	`POST /v3/organizations/{org_id}/playbooks`
Obtener playbook	`GET /v1/playbooks/{playbook_id}`	`GET /v3/organizations/{org_id}/playbooks/{playbook_id}`
Actualizar playbook	`PUT /v1/playbooks/{playbook_id}`	`PUT /v3/organizations/{org_id}/playbooks/{playbook_id}`
Eliminar playbook	`DELETE /v1/playbooks/{playbook_id}`	`DELETE /v3/organizations/{org_id}/playbooks/{playbook_id}`

Endpoints de secretos

Operación	Endpoint v1	Endpoint actual
Listar secretos	`GET /v1/secrets`	`GET /v3/organizations/{org_id}/secrets`
Crear secreto	`POST /v1/secrets`	`POST /v3/organizations/{org_id}/secrets`
Eliminar secreto	`DELETE /v1/secrets/{secret_id}`	`DELETE /v3/organizations/{org_id}/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 desplazamiento:

# Antes (v1/v2 basado en desplazamiento)
curl "https://api.devin.ai/v1/sessions?offset=0&limit=25"

# Después (basado en cursor)
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25"
# Luego usa `end_cursor` de la respuesta para la siguiente página:
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/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.

​Qué está cambiando

​Paso 1: Crear un usuario de servicio

​Paso 2: Actualizar las URL de los endpoints

​Endpoints de sesión

​Endpoints de Knowledge

​Endpoints de playbooks

​Endpoints de secretos

​Endpoints exclusivos de Enterprise (nuevo)

​Paso 3: Actualizar la paginación

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

​Valores de estado de la sesión

​Respuestas de error

​Cronograma de obsolescencia

​¿Necesitas ayuda?

Qué está cambiando

Paso 1: Crear un usuario de servicio

Paso 2: Actualizar las URL de los endpoints

Endpoints de sesión

Endpoints de Knowledge

Endpoints de playbooks

Endpoints de secretos

Endpoints exclusivos de Enterprise (nuevo)

Paso 3: Actualizar la paginación

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

Valores de estado de la sesión

Respuestas de error

Cronograma de obsolescencia

¿Necesitas ayuda?