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

# Ejemplos de uso

> Ejemplos de código y casos de uso habituales de la Devin API

Esta página incluye ejemplos de código para casos de uso habituales de la Devin API. Todos los ejemplos usan variables de entorno para las credenciales: configúralas una vez y cada ejemplo estará listo para copiar y pegar. Para ver los esquemas completos de solicitud/respuesta, consulta la página de referencia de la API de cada endpoint.

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

Configura estas variables de entorno antes de ejecutar cualquier ejemplo:

```bash theme={null}
# Obligatorio: tu API key de 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"
```

<Tip>
  Busca el ID de tu organización en la parte superior de la página **Settings → Devin API**.
</Tip>

<div id="curl-examples">
  ## Ejemplos de curl
</div>

Estos ejemplos se pueden ejecutar directamente en la terminal después de configurar las variables de entorno anteriores.

<AccordionGroup>
  <Accordion title="Crear una sesión">
    ```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"}'
    ```
  </Accordion>

  <Accordion title="Listar sesiones">
    ```bash theme={null}
    curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
      -H "Authorization: Bearer $DEVIN_API_KEY"
    ```
  </Accordion>

  <Accordion title="Enviar un mensaje a una sesión">
    ```bash theme={null}
    export SESSION_ID="your_session_id"

    curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID/messages" \
      -H "Authorization: Bearer $DEVIN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"message": "Please also add unit tests"}'
    ```
  </Accordion>

  <Accordion title="Crear una nota de Knowledge">
    ```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 this repo",
        "body": "Use TypeScript strict mode. Follow the existing code style."
      }'
    ```
  </Accordion>

  <Accordion title="Listar organizaciones Enterprise">
    ```bash theme={null}
    curl "https://api.devin.ai/v3/enterprise/organizations" \
      -H "Authorization: Bearer $DEVIN_API_KEY"
    ```
  </Accordion>

  <Accordion title="Obtener datos de consumo">
    ```bash theme={null}
    # Usa marcas de tiempo Unix; por ejemplo, del 1 al 31 de enero de 2025
    curl "https://api.devin.ai/v3/enterprise/consumption/daily?time_after=1735689600&time_before=1738368000" \
      -H "Authorization: Bearer $DEVIN_API_KEY"
    ```
  </Accordion>
</AccordionGroup>

<div id="python-examples">
  ## Ejemplos en Python
</div>

<AccordionGroup>
  <Accordion title="Crear una sesión">
    ```python theme={null}
    import os
    import requests

    API_KEY = os.environ["DEVIN_API_KEY"]
    ORG_ID = os.environ["DEVIN_ORG_ID"]
    BASE_URL = "https://api.devin.ai/v3"

    response = requests.post(
        f"{BASE_URL}/organizations/{ORG_ID}/sessions",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "prompt": "Create a Python script that analyzes CSV data"
        }
    )
    response.raise_for_status()

    session = response.json()
    print(f"Session created: {session['session_id']}")
    print(f"URL: {session['url']}")
    ```
  </Accordion>

  <Accordion title="Sondear el estado de la sesión">
    ```python theme={null}
    import os
    import time
    import requests

    API_KEY = os.environ["DEVIN_API_KEY"]
    ORG_ID = os.environ["DEVIN_ORG_ID"]
    BASE_URL = "https://api.devin.ai/v3"
    SESSION_ID = os.environ.get("SESSION_ID", "your_session_id")

    while True:
        response = requests.get(
            f"{BASE_URL}/organizations/{ORG_ID}/sessions/{SESSION_ID}",
            headers={"Authorization": f"Bearer {API_KEY}"}
        )
        response.raise_for_status()
        session = response.json()

        status = session["status"]
        print(f"Status: {status}")

        # Estados terminales: "exit" (completado), "error", "suspended"
        if status in ("exit", "error", "suspended"):
            break

        time.sleep(10)
    ```
  </Accordion>

  <Accordion title="Flujo de trabajo multi-organización (Enterprise)">
    Automatiza en múltiples organizaciones:

    ```python theme={null}
    import os
    import requests

    API_KEY = os.environ["DEVIN_API_KEY"]
    BASE_URL = "https://api.devin.ai/v3"

    # Obtener todas las organizaciones
    orgs_response = requests.get(
        f"{BASE_URL}/enterprise/organizations",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    orgs_response.raise_for_status()
    organizations = orgs_response.json()["items"]

    # Crear una sesión en cada organización
    for org in organizations:
        session_response = requests.post(
            f"{BASE_URL}/organizations/{org['org_id']}/sessions",
            headers={
                "Authorization": f"Bearer {API_KEY}",
                "Content-Type": "application/json"
            },
            json={
                "prompt": f"Run daily health check for {org['name']}"
            }
        )

        if session_response.ok:
            session = session_response.json()
            print(f"Created session for {org['name']}: {session['session_id']}")
        else:
            print(f"Failed for {org['name']}: {session_response.status_code}")
    ```
  </Accordion>

  <Accordion title="Obtención paginada del registro de auditoría (Enterprise)">
    ```python theme={null}
    import os
    import requests
    from datetime import datetime, timedelta, timezone

    API_KEY = os.environ["DEVIN_API_KEY"]
    BASE_URL = "https://api.devin.ai/v3"

    # Últimos 7 días como marcas de tiempo Unix
    now = datetime.now(timezone.utc)
    seven_days_ago = now - timedelta(days=7)

    params = {
        "time_after": int(seven_days_ago.timestamp()),
        "time_before": int(now.timestamp()),
        "first": 100,
    }

    all_logs = []
    while True:
        response = requests.get(
            f"{BASE_URL}/enterprise/audit-logs",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params=params,
        )
        response.raise_for_status()
        data = response.json()

        all_logs.extend(data["items"])
        print(f"Fetched {len(data['items'])} logs (total: {len(all_logs)})")

        if not data.get("has_next_page"):
            break
        params["after"] = data["end_cursor"]

    for log in all_logs:
        ts = datetime.fromtimestamp(log["created_at"], tz=timezone.utc).isoformat()
        actor = log.get("service_user_id") or log.get("user_id") or "system"
        print(f"{ts} - {log['action']} (actor={actor})")
    ```
  </Accordion>

  <Accordion title="Gestión de errores">
    ```python theme={null}
    import os
    import requests

    API_KEY = os.environ["DEVIN_API_KEY"]
    ORG_ID = os.environ["DEVIN_ORG_ID"]
    BASE_URL = "https://api.devin.ai/v3"

    try:
        response = requests.get(
            f"{BASE_URL}/organizations/{ORG_ID}/sessions",
            headers={"Authorization": f"Bearer {API_KEY}"}
        )
        response.raise_for_status()
        data = response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            print("Invalid or expired API key")
        elif e.response.status_code == 403:
            print("Service user lacks required permission")
        elif e.response.status_code == 429:
            print("Rate limit exceeded — wait and retry")
        else:
            print(f"API error: {e.response.status_code} {e.response.text}")
    ```
  </Accordion>
</AccordionGroup>

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

<Card title="¿Necesitas ayuda?">
  Para consultas sobre la API o para informar de incidencias, escribe a [support@cognition.ai](mailto:support@cognition.ai)
</Card>