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

# Esempi di utilizzo

> Esempi di codice e casi d'uso comuni per l'API Devin

Questa pagina fornisce esempi di codice per i casi d'uso più comuni dell'API. Tutti gli esempi utilizzano variabili d'ambiente per le credenziali: impostale una sola volta e ogni esempio sarà pronto da copiare e incollare. Per gli schemi completi di richiesta/risposta, consulta la pagina di riferimento dell'API per ciascun endpoint.

<div id="setup">
  ## Configurazione
</div>

Imposta queste variabili d'ambiente prima di eseguire qualsiasi esempio:

```bash theme={null}
# Required: your service user API key (starts with cog_)
export DEVIN_API_KEY="cog_your_key_here"

# Required: your organization ID (shown at the top of Settings → Devin API)
export DEVIN_ORG_ID="your_org_id"
```

<Tip>
  Trova l'ID della tua organizzazione in cima alla pagina **Impostazioni → API di Devin**.
</Tip>

<div id="curl-examples">
  ## Esempi curl
</div>

Questi esempi funzionano direttamente nel tuo terminale dopo aver impostato le variabili d'ambiente sopra.

<AccordionGroup>
  <Accordion title="Crea una sessione">
    ```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": "Crea uno script Python che analizzi dati CSV"}'
    ```
  </Accordion>

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

  <Accordion title="Invia un messaggio a una sessione">
    ```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": "Aggiungi anche i test unitari"}'
    ```
  </Accordion>

  <Accordion title="Crea una nota in 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": "Standard di codifica",
        "trigger": "Quando scrivi codice in questo repo",
        "body": "Usa TypeScript in strict mode. Segui lo stile di codice esistente."
      }'
    ```
  </Accordion>

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

  <Accordion title="Recupera i dati di consumo">
    ```bash theme={null}
    # Usa timestamp Unix — esempio: dal 1° gennaio al 31 gennaio 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">
  ## Esempi in Python
</div>

<AccordionGroup>
  <Accordion title="Crea una sessione">
    ```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="Eseguire il polling dello stato della sessione">
    ```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}")

        # Stati terminali: "exit" (completato), "error", "suspended"
        if status in ("exit", "error", "suspended"):
            break

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

  <Accordion title="Flusso di lavoro multi-organizzazione (enterprise)">
    Automatizza su più organizzazioni:

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

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

    # Recupera tutte le organizzazioni
    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"]

    # Crea una sessione in ogni organizzazione
    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="Recupero dei log di audit con paginazione (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"

    # Ultimi 7 giorni come timestamp 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="Gestione degli errori">
    ```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">
  ## Supporto
</div>

<Card title="Hai bisogno di aiuto?">
  Per domande sull'API o per segnalare problemi, scrivi a [support@cognition.ai](mailto:support@cognition.ai)
</Card>