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 (se muestra en la parte superior de Settings > Devin API)
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 parte superior de la página Settings > Devin API, donde se aprovisionó el usuario de servicio).

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 '{
    "title": "PR Review",
    "body": "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={
        "title": "PR Review",
        "body": "Review the PR for bugs, security issues, and style violations."
    }
).json()
print(f"Created playbook: {playbook['playbook_id']}")

Programar sesiones automatizadas

Crea sesiones recurrentes con una automatización que tenga un trigger schedule:recurring. El trigger admite una sola condición rrule: una RRULE de iCalendar evaluada en UTC (por ejemplo, FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=13;BYMINUTE=0 para los días laborables a las 9 AM hora del Este durante el horario de verano). Requiere el permiso ManageOrgAutomations.

Los endpoints antiguos /schedules están obsoletos. A partir del 24 de septiembre de 2026, POST /v3/organizations/{org_id}/schedules devolverá 403 en las organizaciones migradas a automatizaciones. Consulta las notas de la versión de la API.

Crear una automatización programada

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/automations" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekday test run",
    "run_as": {"type": "organization"},
    "triggers": [{
      "event_type": "schedule:recurring",
      "conditions": {"any": [{"all": [{
        "field": "rrule",
        "operator": "recurrence",
        "value": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=13;BYMINUTE=0"
      }]}]}
    }],
    "actions": [{
      "type": "start_session",
      "prompt": "Run the test suite and report any failures"
    }]
  }'

Para una ejecución única, usa un DTSTART con COUNT=1; por ejemplo, DTSTART:20260915T170000Z\nRRULE:FREQ=DAILY;COUNT=1. La automatización se activa una sola vez y después se deshabilita automáticamente.

List, update y delete

# Listar automatizaciones
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/automations" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

# Deshabilitar una automatización
curl -X PATCH "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/automations/$AUTOMATION_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Eliminar una automatización
curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/automations/$AUTOMATION_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 automatización diaria de verificación de estado (09:00 UTC todos los días)
automation = requests.post(
    f"{BASE}/organizations/{ORG_ID}/automations",
    headers=HEADERS,
    json={
        "name": "Daily health check",
        "run_as": {"type": "organization"},
        "triggers": [{
            "event_type": "schedule:recurring",
            "conditions": {"any": [{"all": [{
                "field": "rrule",
                "operator": "recurrence",
                "value": "FREQ=DAILY;BYHOUR=9;BYMINUTE=0"
            }]}]}
        }],
        "actions": [{
            "type": "start_session",
            "prompt": "Run the test suite and report any failures"
        }]
    }
).json()
print(f"Created automation: {automation['automation_id']}")

# Listar todas las automatizaciones (el endpoint devuelve hasta 100 por página)
automations = []
after = None
while True:
    page = requests.get(
        f"{BASE}/organizations/{ORG_ID}/automations",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params={"after": after},
    ).json()
    automations.extend(page["items"])
    if not page["has_next_page"]:
        break
    after = page["end_cursor"]

for a in automations:
    status = "enabled" if a.get("enabled") else "disabled"
    print(f"  {a['automation_id']}: {a['name']} ({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

​Programar sesiones automatizadas

​Crear una automatización programada

​List, update y delete

​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

Programar sesiones automatizadas

Crear una automatización programada

List, update y delete

Ejemplo completo en Python

Delega una tarea desde cualquier lugar

Crear una sesión con contexto del repositorio

Gestión de errores

Soporte