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

# Migración desde v1/v2

> Migra tus integraciones de la API v1 o v2 a la API actual

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.

<div id="whats-changing">
  ## Qué está cambiando
</div>

| Á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            |

<div id="step-1-create-a-service-user">
  ## Paso 1: Crear un usuario de servicio
</div>

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

```bash theme={null}
# 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" ...
```

<Note>
  Tus API keys anteriores seguirán funcionando durante el período de deprecación. Podrás migrar gradualmente.
</Note>

<div id="step-2-update-endpoint-urls">
  ## Paso 2: Actualizar las URL de los endpoints
</div>

<div id="session-endpoints">
  ### Endpoints de sesión
</div>

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

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

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

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

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

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

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

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

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

<div id="step-3-update-pagination">
  ## Paso 3: Actualizar la paginación
</div>

La API actual usa paginación basada en cursor en lugar de paginación basada en desplazamiento:

```bash theme={null}
# 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](/es/api-reference/concepts/pagination) para obtener más detalles.

<div id="step-4-handle-response-format-changes">
  ## Paso 4: Gestionar los cambios en el formato de la respuesta
</div>

<div id="session-status-values">
  ### Valores de estado de la sesión
</div>

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

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

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

<div id="deprecation-timeline">
  ## Cronograma de obsolescencia
</div>

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.

<div id="need-help">
  ## ¿Necesitas ayuda?
</div>

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](mailto:support@cognition.ai).