Flujos comunes - Devin Docs

Esta página describe flujos de trabajo integrales comunes con la API de Devin. Cada flujo incluye la secuencia completa de llamadas a la API con ejemplos de código. Para obtener información detallada sobre cada endpoint, consulta las páginas relevantes de referencia de la API.

Configuración

Define estas variables de entorno antes de ejecutar cualquier ejemplo:

# Obligatorio: el API key de tu usuario de servicio (comienza con cog_)
export DEVIN_API_KEY="cog_your_key_here"

# Obligatorio: el ID de tu organización (encuéntralo en Settings > Service Users)
export DEVIN_ORG_ID="your_org_id"

Primeros pasos: de la API key a la primera sesión

El flujo de trabajo más común: autenticarse, identificar su cuenta y crear su primera sesión.

Paso 1: Verifica tus credenciales

Los usuarios de servicio con ámbito de organización pueden pasar al Paso 3 — ya conocen el ID de su org desde la página de Settings.

curl "https://api.devin.ai/v3/self" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Respuesta:

{
  "principal_type": "service_user",
  "service_user_id": "service-user-abc123",
  "service_user_name": "CI Bot",
  "org_id": null
}

Paso 2: Listar tus organizaciones

Los usuarios de servicio de Enterprise pueden listar todas las organizaciones:

curl "https://api.devin.ai/v3/enterprise/organizations" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Los usuarios de servicio con ámbito de organización ya conocen su ID de org (aparece en la página Settings > Service Users, donde se creó la clave).

Paso 3: Crear una sesión

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create a Python script that analyzes CSV data"}'

Respuesta:

{
  "session_id": "devin-abc123",
  "url": "https://app.devin.ai/sessions/devin-abc123",
  "status": "running"
}

Paso 4: Sondear eventos

Supervisa la sesión sondeando los mensajes:

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/devin-abc123/messages" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Ejemplo completo en Python

import os
import time
import requests

API_KEY = os.environ["DEVIN_API_KEY"]
ORG_ID = os.environ["DEVIN_ORG_ID"]
BASE = "https://api.devin.ai/v3"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Verificar credenciales
me = requests.get(f"{BASE}/self", headers=HEADERS)
me.raise_for_status()
data = me.json()
print(f"Authenticated as: {data.get('service_user_name') or data.get('user_name')}")

# 2. Crear una sesión
session = requests.post(
    f"{BASE}/organizations/{ORG_ID}/sessions",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"prompt": "Crea un script de Python que analice datos CSV"}
).json()
print(f"Session: {session['url']}")

# 3. Sondear hasta completar
while True:
    status = requests.get(
        f"{BASE}/organizations/{ORG_ID}/sessions/{session['session_id']}",
        headers=HEADERS
    ).json()["status"]
    print(f"Status: {status}")
    if status in ("exit", "error", "suspended"):
        break
    time.sleep(10)

Descargar archivos adjuntos de la sesión

Obtén los archivos generados en una sesión (registros, capturas de pantalla, código generado, etc.).

Paso 1: Obtener la sesión

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

paso 2: Listar archivos adjuntos

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID/attachments" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Respuesta:

{
  "items": [
    {
      "attachment_id": "att_123",
      "name": "output.py",
      "url": "https://..."
    }
  ]
}

Paso 3: Descargar

Usa la url de la respuesta del adjunto para descargar el archivo directamente.

Ejemplo completo en Python

import os
import requests

API_KEY = os.environ["DEVIN_API_KEY"]
ORG_ID = os.environ["DEVIN_ORG_ID"]
SESSION_ID = os.environ["SESSION_ID"]
BASE = "https://api.devin.ai/v3"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Listar adjuntos
attachments = requests.get(
    f"{BASE}/organizations/{ORG_ID}/sessions/{SESSION_ID}/attachments",
    headers=HEADERS
).json()["items"]

# Descargar cada adjunto
for att in attachments:
    print(f"Downloading {att['name']}...")
    content = requests.get(att["url"]).content
    with open(att["name"], "wb") as f:
        f.write(content)
    print(f"  Saved {att['name']} ({len(content)} bytes)")

Gestión de Knowledge y playbooks

Gestiona el contexto y las instrucciones que Devin utiliza en distintas sesiones.

Crear una nota de Knowledge

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coding standards",
    "trigger": "When writing code in any repository",
    "body": "Use TypeScript strict mode. Follow existing code style. Run lint before committing."
  }'

Listar las notas de Knowledge

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Actualizar una nota de Knowledge

curl -X PUT "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes/$NOTE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coding standards (updated)",
    "trigger": "When writing code in any repository",
    "body": "Use TypeScript strict mode. Follow existing code style. Run lint and type-check before committing."
  }'

Eliminar una nota de Knowledge

curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes/$NOTE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Crear un playbook

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/playbooks" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PR Review",
    "instructions": "Review the PR for bugs, security issues, and style violations. Leave inline comments."
  }'

Ejemplo completo en Python

import os
import requests

API_KEY = os.environ["DEVIN_API_KEY"]
ORG_ID = os.environ["DEVIN_ORG_ID"]
BASE = "https://api.devin.ai/v3"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Crear nota de Knowledge
note = requests.post(
    f"{BASE}/organizations/{ORG_ID}/knowledge/notes",
    headers=HEADERS,
    json={
        "name": "Coding standards",
        "trigger": "When writing code in any repository",
        "body": "Use TypeScript strict mode. Follow existing code style."
    }
).json()
print(f"Created note: {note['note_id']}")

# Listar todas las notas
notes = requests.get(
    f"{BASE}/organizations/{ORG_ID}/knowledge/notes",
    headers={"Authorization": f"Bearer {API_KEY}"}
).json()["items"]
print(f"Total notes: {len(notes)}")

# Crear playbook
playbook = requests.post(
    f"{BASE}/organizations/{ORG_ID}/playbooks",
    headers=HEADERS,
    json={
        "name": "PR Review",
        "instructions": "Review the PR for bugs, security issues, and style violations."
    }
).json()
print(f"Created playbook: {playbook['playbook_id']}")

Programación de sesiones automatizadas

Crea sesiones recurrentes que se ejecutan de forma programada.

Crear una programación

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Run the test suite and report any failures",
    "cron_schedule": "0 9 * * 1-5",
    "timezone": "America/New_York"
  }'

Esto crea una programación que se ejecuta de lunes a viernes a las 9 a. m., hora del Este.

Listar programaciones

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Actualizar una programación

curl -X PATCH "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules/$SCHEDULE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cron_schedule": "0 8 * * 1-5",
    "is_enabled": true
  }'

Eliminar una programación

curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules/$SCHEDULE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Ejemplo completo en Python

import os
import requests

API_KEY = os.environ["DEVIN_API_KEY"]
ORG_ID = os.environ["DEVIN_ORG_ID"]
BASE = "https://api.devin.ai/v3"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Crear una programación diaria de verificación de estado
schedule = requests.post(
    f"{BASE}/organizations/{ORG_ID}/schedules",
    headers=HEADERS,
    json={
        "prompt": "Run the test suite and report any failures",
        "cron_schedule": "0 9 * * 1-5",
        "timezone": "America/New_York"
    }
).json()
print(f"Created schedule: {schedule['schedule_id']}")

# Listar todas las programaciones
schedules = requests.get(
    f"{BASE}/organizations/{ORG_ID}/schedules",
    headers={"Authorization": f"Bearer {API_KEY}"}
).json()["items"]

for s in schedules:
    status = "enabled" if s.get("is_enabled") else "disabled"
    print(f"  {s['schedule_id']}: {s['cron_schedule']} ({status})")

Delega una tarea desde cualquier lugar

Como la API de Sessions crea una sesión de Devin en la nube a partir de una única solicitud, cualquier herramienta, script o agente de código puede “delegar” trabajo a Devin, incluyendo el repo actual, la rama y los cambios sin confirmar en el prompt para que la sesión en la nube continúe desde donde lo dejaste.

Crear una sesión con contexto del repositorio

# Construye el cuerpo JSON con jq para que el diff sin procesar — que contiene comillas,
# barras invertidas y saltos de línea — se escape correctamente en una cadena JSON válida.
curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg diff "$(git diff HEAD)" \
    '{prompt: "Repo: my-org/my-repo (branch: fix-flaky-tests)\nFix the flaky integration tests in CI.\n\nUncommitted changes:\n\($diff)"}')"

La sesión en la nube clona el repo, aplica el contexto de tu prompt y se ejecuta en su propia VM con un shell, un navegador y acceso completo al repo. Hazle seguimiento sondeando los mensajes o en la aplicación web de Devin.

git diff HEAD puede incluir secretos aún no confirmados — claves de API, tokens o cambios en .env — y el prompt se sube a la sesión en la nube. Revisa tu diff y confirma, guarda en stash o elimina los cambios sensibles antes de ceder el control.

¿No quieres hacerlo tú mismo? El plugin de código abierto Devin Handoff encapsula exactamente este flujo — detecta automáticamente el repo, la rama y el diff — para que puedas delegar desde Devin CLI, Claude Code, Codex, Cursor o un simple script de shell. Consulta Delegar a Devin.

Gestión de errores

Todos los ejemplos anteriores deben incluir gestión de errores en producción. Aquí tienes un patrón reutilizable:

import requests

def api_request(method, url, headers, **kwargs):
    """Realiza una solicitud a la API con manejo de errores estándar."""
    response = requests.request(method, url, headers=headers, **kwargs)
    try:
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        status = e.response.status_code
        if status == 401:
            raise Exception("Invalid or expired API key")
        elif status == 403:
            raise Exception("Service user lacks required permission")
        elif status == 404:
            raise Exception("Resource not found")
        elif status == 429:
            raise Exception("Rate limit exceeded — wait and retry")
        else:
            raise Exception(f"API error {status}: {e.response.text}")

Soporte

¿Necesitas ayuda?

Si tienes preguntas sobre la API o quieres informar de algún problema, escribe a support@cognition.ai

​Configuración

​Primeros pasos: de la API key a la primera sesión

​Paso 1: Verifica tus credenciales

​Paso 2: Listar tus organizaciones

​Paso 3: Crear una sesión

​Paso 4: Sondear eventos

​Ejemplo completo en Python

​Descargar archivos adjuntos de la sesión

​Paso 1: Obtener la sesión

​paso 2: Listar archivos adjuntos

​Paso 3: Descargar

​Ejemplo completo en Python

​Gestión de Knowledge y playbooks

​Crear una nota de Knowledge

​Listar las notas de Knowledge

​Actualizar una nota de Knowledge

​Eliminar una nota de Knowledge

​Crear un playbook

​Ejemplo completo en Python

​Programación de sesiones automatizadas

​Crear una programación

​Listar programaciones

​Actualizar una programación

​Eliminar una programación

​Ejemplo completo en Python

​Delega una tarea desde cualquier lugar

​Crear una sesión con contexto del repositorio

​Gestión de errores

​Soporte

¿Necesitas ayuda?

Configuración

Primeros pasos: de la API key a la primera sesión

Paso 1: Verifica tus credenciales

Paso 2: Listar tus organizaciones

Paso 3: Crear una sesión

Paso 4: Sondear eventos

Ejemplo completo en Python

Descargar archivos adjuntos de la sesión

Paso 1: Obtener la sesión

paso 2: Listar archivos adjuntos

Paso 3: Descargar

Ejemplo completo en Python

Gestión de Knowledge y playbooks

Crear una nota de Knowledge

Listar las notas de Knowledge

Actualizar una nota de Knowledge

Eliminar una nota de Knowledge

Crear un playbook

Ejemplo completo en Python

Programación de sesiones automatizadas

Crear una programación

Listar programaciones

Actualizar una programación

Eliminar una programación

Ejemplo completo en Python

Delega una tarea desde cualquier lugar

Crear una sesión con contexto del repositorio

Gestión de errores

Soporte