Fluxos comuns - Devin Docs

Esta página apresenta fluxos de trabalho completos comuns com a API do Devin. Cada fluxo inclui a sequência completa de chamadas à API, com exemplos de código. Para detalhes de cada endpoint, consulte as páginas relevantes da referência da API.

Configuração

Defina estas variáveis de ambiente antes de executar qualquer exemplo:

# Obrigatório: a chave de API do seu usuário de serviço (começa com cog_)
export DEVIN_API_KEY="cog_your_key_here"

# Obrigatório: o ID da sua organização (exibido no topo de Configurações > API do Devin)
export DEVIN_ORG_ID="your_org_id"

Primeiros passos: da Chave de API à primeira sessão

O fluxo de trabalho mais comum — autenticar-se, identificar sua conta e criar sua primeira sessão.

Etapa 1: Verifique suas credenciais

Usuários de serviço com escopo de organização podem pular para a Etapa 3 — você já sabe o ID da sua organização na página Configurações.

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

Resposta:

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

Etapa 2: Liste suas organizações

Usuários de serviço Enterprise podem listar todas as organizações:

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

Usuário de serviço com escopo de organização já sabe o ID da organização (ele é exibido no topo da página Configurações > API do Devin, onde o usuário de serviço foi provisionado).

Etapa 3: Criar uma sessão

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

Resposta:

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

Etapa 4: Consultar eventos periodicamente

Monitore a sessão consultando periodicamente as mensagens:

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

Exemplo completo em 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 credenciais
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. Criar uma sessão
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. Consultar até concluir
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)

Baixar anexos da sessão

Baixe os arquivos produzidos em uma sessão (logs, capturas de tela, código gerado etc.).

Etapa 1: Obter a sessão

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

Etapa 2: Listar anexos

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

Resposta:

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

Etapa 3: Baixar

Use a url retornada na resposta do anexo para baixar o arquivo diretamente.

Exemplo completo em 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 anexos
attachments = requests.get(
    f"{BASE}/organizations/{ORG_ID}/sessions/{SESSION_ID}/attachments",
    headers=HEADERS
).json()["items"]

# Baixar cada anexo
for att in attachments:
    print(f"Baixando {att['name']}...")
    content = requests.get(att["url"]).content
    with open(att["name"], "wb") as f:
        f.write(content)
    print(f"  Salvo {att['name']} ({len(content)} bytes)")

Gerenciamento de Knowledge e playbook

Gerencie o contexto e as instruções que o Devin usa entre sessões.

Criar uma nota do 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 notas do Knowledge

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

Atualizar uma nota do 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."
  }'

Excluir uma nota do Knowledge

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

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

Exemplo completo em 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"
}

# Criar nota do 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 as 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)}")

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

Agendamento de sessões automatizadas

Crie sessões recorrentes com uma automação que tenha um gatilho schedule:recurring. O gatilho aceita uma condição rrule: um RRULE do iCalendar avaliado em UTC (por exemplo, FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=13;BYMINUTE=0 para dias úteis às 9h no horário do leste dos EUA durante o horário de verão). Requer a permissão ManageOrgAutomations.

Os endpoints antigos /schedules estão descontinuados. A partir de 24 de setembro de 2026, POST /v3/organizations/{org_id}/schedules retornará 403 para organizações migradas para as automações. Consulte as notas de versão da API.

Criar uma automação agendada

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 uma execução única, use um DTSTART com COUNT=1, por exemplo: DTSTART:20260915T170000Z\nRRULE:FREQ=DAILY;COUNT=1. A automação dispara uma vez e depois se desativa automaticamente.

Listar, atualizar e excluir

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

# Desativar uma automação
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}'

# Excluir uma automação
curl -X DELETE "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/automations/$AUTOMATION_ID" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Exemplo completo em 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"
}

# Criar uma automação diária de verificação de integridade (09:00 UTC todos os dias)
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 as automações (o endpoint retorna até 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})")

Passe uma tarefa de qualquer lugar

Como a Sessions API cria uma sessão do Devin na nuvem a partir de uma única requisição, qualquer ferramenta, script ou agente de codificação pode “passar” o trabalho para o Devin, incluindo no prompt o repositório atual, a branch e as alterações ainda não comitadas, para que a sessão na nuvem continue de onde você parou.

Criar uma sessão com contexto de repositório

# Constrói o corpo JSON com jq para que o diff bruto — que contém aspas,
# barras invertidas e quebras de linha — seja escapado em uma string 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)"}')"

A sessão na nuvem clona o repositório, aplica o contexto do seu prompt e roda em sua própria VM com um shell, navegador e acesso completo ao repositório. Acompanhe-a consultando as mensagens ou no app web do Devin.

git diff HEAD pode incluir segredos ainda não comitados — chaves de API, tokens ou edições em .env — e o prompt é importado para a sessão na nuvem. Revise seu diff e faça commit, stash ou remova alterações sensíveis antes de transferir.

Não quer montar isso por conta própria? O plugin open-source Devin Handoff encapsula exatamente esse fluxo — detectando automaticamente repositório, branch e diff — para que você possa transferir a partir do Devin CLI, Claude Code, Codex, Cursor ou de um script de shell simples. Veja Transferir para o Devin.

Tratamento de erros

Todos os exemplos acima devem incluir tratamento de erros em ambiente de produção. Aqui está um padrão reutilizável:

import requests

def api_request(method, url, headers, **kwargs):
    """Make an API request with standard error handling."""
    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}")

Suporte

Precisa de ajuda?

Em caso de dúvidas sobre a API ou para relatar problemas, envie um e-mail para support@cognition.ai

​Configuração

​Primeiros passos: da Chave de API à primeira sessão

​Etapa 1: Verifique suas credenciais

​Etapa 2: Liste suas organizações

​Etapa 3: Criar uma sessão

​Etapa 4: Consultar eventos periodicamente

​Exemplo completo em Python

​Baixar anexos da sessão

​Etapa 1: Obter a sessão

​Etapa 2: Listar anexos

​Etapa 3: Baixar

​Exemplo completo em Python

​Gerenciamento de Knowledge e playbook

​Criar uma nota do Knowledge

​Listar notas do Knowledge

​Atualizar uma nota do Knowledge

​Excluir uma nota do Knowledge

​Criar um playbook

​Exemplo completo em Python

​Agendamento de sessões automatizadas

​Criar uma automação agendada

​Listar, atualizar e excluir

​Exemplo completo em Python

​Passe uma tarefa de qualquer lugar

​Criar uma sessão com contexto de repositório

​Tratamento de erros

​Suporte

Precisa de ajuda?

Configuração

Primeiros passos: da Chave de API à primeira sessão

Etapa 1: Verifique suas credenciais

Etapa 2: Liste suas organizações

Etapa 3: Criar uma sessão

Etapa 4: Consultar eventos periodicamente

Exemplo completo em Python

Baixar anexos da sessão

Etapa 1: Obter a sessão

Etapa 2: Listar anexos

Etapa 3: Baixar

Exemplo completo em Python

Gerenciamento de Knowledge e playbook

Criar uma nota do Knowledge

Listar notas do Knowledge

Atualizar uma nota do Knowledge

Excluir uma nota do Knowledge

Criar um playbook

Exemplo completo em Python

Agendamento de sessões automatizadas

Criar uma automação agendada

Listar, atualizar e excluir

Exemplo completo em Python

Passe uma tarefa de qualquer lugar

Criar uma sessão com contexto de repositório

Tratamento de erros

Suporte