> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flujos comunes

> Guías de flujos de trabajo integrales para casos de uso comunes de la API

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.

<div id="setup">
  ## Configuración
</div>

Define estas variables de entorno antes de ejecutar cualquier ejemplo:

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

***

<div id="getting-started-api-key-to-first-session">
  ## Primeros pasos: de la API key a la primera sesión
</div>

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

<div id="step-1-verify-your-credentials">
  ### Paso 1: Verifica tus credenciales
</div>

<Note>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.</Note>

```bash theme={null}
curl "https://api.devin.ai/v3/self" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

Respuesta:

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

<div id="step-2-list-your-organizations">
  ### Paso 2: Listar tus organizaciones
</div>

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

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

<div id="step-3-create-a-session">
  ### Paso 3: Crear una sesión
</div>

```bash theme={null}
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:

```json theme={null}
{
  "session_id": "devin-abc123",
  "url": "https://app.devin.ai/sessions/devin-abc123",
  "status": "running"
}
```

<div id="step-4-poll-for-events">
  ### Paso 4: Sondear eventos
</div>

Supervisa la sesión sondeando los mensajes:

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/devin-abc123/messages" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="full-python-example">
  ### Ejemplo completo en Python
</div>

```python theme={null}
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)
```

***

<div id="downloading-session-attachments">
  ## Descargar archivos adjuntos de la sesión
</div>

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

<div id="step-1-get-the-session">
  ### Paso 1: Obtener la sesión
</div>

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="step-2-list-attachments">
  ### paso 2: Listar archivos adjuntos
</div>

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID/attachments" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

Respuesta:

```json theme={null}
{
  "items": [
    {
      "attachment_id": "att_123",
      "name": "output.py",
      "url": "https://..."
    }
  ]
}
```

<div id="step-3-download">
  ### Paso 3: Descargar
</div>

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

<div id="full-python-example">
  ### Ejemplo completo en Python
</div>

```python theme={null}
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)")
```

***

<div id="knowledge-playbook-management">
  ## Gestión de Knowledge y playbooks
</div>

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

<div id="create-a-knowledge-note">
  ### Crear una nota de Knowledge
</div>

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

<div id="list-knowledge-notes">
  ### Listar las notas de Knowledge
</div>

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="update-a-knowledge-note">
  ### Actualizar una nota de Knowledge
</div>

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

<div id="delete-a-knowledge-note">
  ### Eliminar una nota de Knowledge
</div>

```bash theme={null}
curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes/$NOTE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="create-a-playbook">
  ### Crear un playbook
</div>

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

<div id="full-python-example">
  ### Ejemplo completo en Python
</div>

```python theme={null}
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']}")
```

***

<div id="scheduling-automated-sessions">
  ## Programación de sesiones automatizadas
</div>

Crea sesiones recurrentes que se ejecutan de forma programada.

<div id="create-a-schedule">
  ### Crear una programación
</div>

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

<div id="list-schedules">
  ### Listar programaciones
</div>

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="update-a-schedule">
  ### Actualizar una programación
</div>

```bash theme={null}
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
  }'
```

<div id="delete-a-schedule">
  ### Eliminar una programación
</div>

```bash theme={null}
curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/schedules/$SCHEDULE_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="full-python-example">
  ### Ejemplo completo en Python
</div>

```python theme={null}
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})")
```

***

<div id="hand-off-a-task-from-anywhere">
  ## Delega una tarea desde cualquier lugar
</div>

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.

<div id="create-a-session-with-repo-context">
  ### Crear una sesión con contexto del repositorio
</div>

```bash theme={null}
# 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](#step-4-poll-for-events) o en la [aplicación web de Devin](https://app.devin.ai).

<Warning>
  `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.
</Warning>

<Tip>
  ¿No quieres hacerlo tú mismo? El plugin de código abierto [Devin Handoff](https://github.com/club-cog/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](/es/work-with-devin/devin-handoff).
</Tip>

***

<div id="error-handling">
  ## Gestión de errores
</div>

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

```python theme={null}
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}")
```

<div id="support">
  ## Soporte
</div>

<Card title="¿Necesitas ayuda?">
  Si tienes preguntas sobre la API o quieres informar de algún problema, escribe a [support@cognition.ai](mailto:support@cognition.ai)
</Card>