Flussi comuni - Devin Docs

Questa pagina descrive i flussi di lavoro end-to-end più comuni con l’API di Devin. Ogni flusso include la sequenza completa delle chiamate API con esempi di codice. Per i dettagli sui singoli endpoint, consulta le pagine di riferimento dell’API pertinenti.

Configurazione

Imposta queste environment variables prima di eseguire qualsiasi esempio:

# Obbligatorio: l'API key del tuo utente di servizio (inizia con cog_)
export DEVIN_API_KEY="cog_your_key_here"

# Obbligatorio: l'ID della tua organizzazione (mostrato in alto in Settings > Devin API)
export DEVIN_ORG_ID="your_org_id"

Per iniziare: dall’API key alla prima sessione

Il flusso di lavoro più comune: autenticarsi, individuare il proprio account e creare la prima sessione.

Passaggio 1: Verifica le tue credenziali

Gli utente di servizio con ambito organizzazione possono passare al Passaggio 3 — conosci già il tuo ID org dalla pagina Settings.

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

Risposta:

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

Passaggio 2: Elenca le tue organizzazioni

Gli utenti di servizio Enterprise possono elencare tutte le organizzazioni:

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

Gli utenti di servizio con ambito organizzazione conoscono già il proprio ID org (è indicato in cima alla pagina Settings > Devin API, dove è stato effettuato il provisioning dell’utente di servizio).

Passaggio 3: Creare una sessione

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"}'

Risposta:

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

Passaggio 4: Esegui il polling degli eventi

Monitora la sessione effettuando il polling dei messaggi:

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

Esempio completo in 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. Verifica le credenziali
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. Crea una sessione
session = requests.post(
    f"{BASE}/organizations/{ORG_ID}/sessions",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"prompt": "Create a Python script that analyzes CSV data"}
).json()
print(f"Session: {session['url']}")

# 3. Esegui il polling fino al completamento
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)

Scaricare gli allegati della sessione

Recupera i file generati da una sessione (log, screenshot, codice generato, ecc.).

Passaggio 1: Recupera la sessione

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

Passaggio 2: Elencare gli allegati

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

Risposta:

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

Passaggio 3: Scaricamento

Usa l’url restituito nella risposta dell’allegato per scaricare direttamente il file.

Esempio completo in 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}"}

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

# Scarica ogni allegato
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)")

Gestione di Knowledge e playbook

Gestisci il contesto e le istruzioni che Devin usa nelle varie sessioni.

Crea una nota di 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."
  }'

Elenca le note di Knowledge

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

Aggiorna una nota di 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."
  }'

Eliminare una nota di Knowledge

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

Creare 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."
  }'

Esempio completo in 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"
}

# Crea nota di 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']}")

# Elenca tutte le note
notes = requests.get(
    f"{BASE}/organizations/{ORG_ID}/knowledge/notes",
    headers={"Authorization": f"Bearer {API_KEY}"}
).json()["items"]
print(f"Total notes: {len(notes)}")

# Crea 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']}")

Pianificazione di sessioni automatizzate

Crea sessioni ricorrenti con un’automazione dotata di un trigger schedule:recurring. Il trigger accetta una sola condizione rrule: una RRULE iCalendar valutata in UTC (per esempio FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=13;BYMINUTE=0 per i giorni lavorativi alle 9:00 ora orientale durante l’ora legale). Richiede l’autorizzazione ManageOrgAutomations.

I vecchi endpoint /schedules sono deprecati. A partire dal 24 settembre 2026, POST /v3/organizations/{org_id}/schedules restituisce 403 per le organizzazioni migrate alle automazioni. Consulta le note di rilascio dell’API.

Creare un’automazione pianificata

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"
    }]
  }'

Per un run una tantum, usa un DTSTART con COUNT=1, ad esempio DTSTART:20260915T170000Z\nRRULE:FREQ=DAILY;COUNT=1. L’automazione si attiva una sola volta e poi si disabilita da sé.

Elencare, aggiornare ed eliminare

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

# Disabilita un'automazione
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}'

# Elimina un'automazione
curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/automations/$AUTOMATION_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Esempio completo in 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"
}

# Crea un'automazione giornaliera di controllo dello stato (ogni giorno alle 09:00 UTC)
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']}")

# Elenca tutte le automazioni (l'endpoint restituisce fino a 100 elementi per pagina)
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})")

Affida un’attività da qualsiasi ambiente

Poiché la Sessions API crea una sessione di Devin nel cloud a partire da una singola richiesta, qualsiasi tool, script o coding agent può “affidare” il lavoro a Devin, includendo nel prompt la repo corrente, il branch e le modifiche non ancora sottoposte a commit, così la sessione cloud riprende da dove avevi lasciato.

Creare una sessione con il contesto del repo

# Costruisce il corpo JSON con jq in modo che il diff grezzo — che contiene virgolette,
# backslash e newline — venga codificato come stringa JSON valida.
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 sessione cloud clona la repo, applica il contesto del prompt e viene eseguita nella propria VM con una shell, un browser e accesso completo alla repo. Monitora l’avanzamento facendo polling dei messaggi o nell’app web di Devin.

git diff HEAD può includere segreti non ancora sottoposti a commit — chiavi API, token o modifiche a .env — e il prompt viene caricato nella sessione cloud. Controlla il diff ed esegui il commit, lo stash o rimuovi le modifiche sensibili prima di affidare il lavoro.

Non vuoi implementare tutto questo da solo? Il plugin open-source Devin Handoff racchiude esattamente questo flusso — rilevando automaticamente repo, branch e diff — così puoi affidare il lavoro da Devin CLI, Claude Code, Codex, Cursor o da un semplice script shell. Vedi Affida il lavoro a Devin.

Gestione degli errori

Negli ambienti di produzione, tutti gli esempi sopra dovrebbero includere la gestione degli errori. Ecco uno schema riutilizzabile:

import requests

def api_request(method, url, headers, **kwargs):
    """Esegui una richiesta API con gestione standard degli errori."""
    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}")

Supporto

Hai bisogno di aiuto?

Per domande sull’API o per segnalare problemi, scrivi a support@cognition.ai

​Configurazione

​Per iniziare: dall’API key alla prima sessione

​Passaggio 1: Verifica le tue credenziali

​Passaggio 2: Elenca le tue organizzazioni

​Passaggio 3: Creare una sessione

​Passaggio 4: Esegui il polling degli eventi

​Esempio completo in Python

​Scaricare gli allegati della sessione

​Passaggio 1: Recupera la sessione

​Passaggio 2: Elencare gli allegati

​Passaggio 3: Scaricamento

​Esempio completo in Python

​Gestione di Knowledge e playbook

​Crea una nota di Knowledge

​Elenca le note di Knowledge

​Aggiorna una nota di Knowledge

​Eliminare una nota di Knowledge

​Creare un playbook

​Esempio completo in Python

​Pianificazione di sessioni automatizzate

​Creare un’automazione pianificata

​Elencare, aggiornare ed eliminare

​Esempio completo in Python

​Affida un’attività da qualsiasi ambiente

​Creare una sessione con il contesto del repo

​Gestione degli errori

​Supporto

Hai bisogno di aiuto?

Configurazione

Per iniziare: dall’API key alla prima sessione

Passaggio 1: Verifica le tue credenziali

Passaggio 2: Elenca le tue organizzazioni

Passaggio 3: Creare una sessione

Passaggio 4: Esegui il polling degli eventi

Esempio completo in Python

Scaricare gli allegati della sessione

Passaggio 1: Recupera la sessione

Passaggio 2: Elencare gli allegati

Passaggio 3: Scaricamento

Esempio completo in Python

Gestione di Knowledge e playbook

Crea una nota di Knowledge

Elenca le note di Knowledge

Aggiorna una nota di Knowledge

Eliminare una nota di Knowledge

Creare un playbook

Esempio completo in Python

Pianificazione di sessioni automatizzate

Creare un’automazione pianificata

Elencare, aggiornare ed eliminare

Esempio completo in Python

Affida un’attività da qualsiasi ambiente

Creare una sessione con il contesto del repo

Gestione degli errori

Supporto