Criar sessão

Cria uma nova sessão.

POST /v3/organizations/{org_id}/sessions

Criar sessão

cURL

curl --request POST \
  --url https://api.devin.ai/v3/organizations/{org_id}/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "attachment_urls": [
    "<string>"
  ],
  "bypass_approval": true,
  "child_playbook_id": "<string>",
  "create_as_user_id": "<string>",
  "knowledge_ids": [
    "<string>"
  ],
  "max_acu_limit": 123,
  "platform": "<string>",
  "playbook_id": "<string>",
  "repos": [
    "<string>"
  ],
  "secret_ids": [
    "<string>"
  ],
  "session_links": [
    "<string>"
  ],
  "session_secrets": [
    {
      "key": "<string>",
      "value": "<string>",
      "sensitive": true
    }
  ],
  "structured_output_required": true,
  "structured_output_schema": {},
  "tags": [
    "<string>"
  ],
  "title": "<string>"
}
'

200

{
  "acus_consumed": 123,
  "created_at": 123,
  "org_id": "<string>",
  "pull_requests": [
    {
      "pr_state": "<string>",
      "pr_url": "<string>"
    }
  ],
  "session_id": "<string>",
  "tags": [
    "<string>"
  ],
  "updated_at": 123,
  "url": "<string>",
  "child_session_ids": [
    "<string>"
  ],
  "is_archived": false,
  "parent_session_id": "<string>",
  "playbook_id": "<string>",
  "service_user_id": "<string>",
  "structured_output": {},
  "subcategory": "<string>",
  "title": "<string>",
  "user_id": "<string>"
}

​

Permissões

Requer um usuário de serviço com a permissão ManageOrgSessions no nível da organização.

​

Permissões adicionais para recursos avançados

Recurso	Permissão necessária
create_as_user_id	ImpersonateOrgSessions

​

Modo Devin

O parâmetro devin_mode controla qual modo do agente Devin é usado na sessão:

Modo	Descrição
normal	O modo padrão do agente. Rápido e bom para planejamento de longo prazo.
fast	~2x mais rápido, 4x mais caro, mesma inteligência.

Quando omitido, a sessão usa o modo padrão da organização. O modo rápido está sujeito às mesmas restrições de feature flag e de prévia do agente no Enterprise que o app web.

​

Impersonação de usuário

O parâmetro create_as_user_id permite criar uma sessão em nome de outro usuário. Para isso, é necessário que:

1. O usuário de serviço tenha a permissão ImpersonateOrgSessions
2. O usuário de destino seja membro da organização
3. O usuário de destino tenha a permissão UseDevinSessions

Autorizações

Authorization · string · header · obrigatório

Credencial de usuário de serviço (prefixo: cog_)

Parâmetros de caminho

org_id · string | null · obrigatório

ID da organização (prefixo: org-)

Exemplo:

"org-abc123def456"

Parâmetros de consulta

devin_id · string | null

Corpo

application/json

prompt · string · obrigatório

attachment_urls · string<uri>[] | null

Required string length: 1 - 2083

bypass_approval · boolean | null

child_playbook_id · string | null

create_as_user_id · string | null

devin_mode · enum<string> | null

Override do modo Agent do Devin para a sessão. 'normal' usa o modo Agent padrão, 'fast' usa o modo Fast e 'lite' usa o Devin Lite. Fast e Lite estão sujeitos ao mesmo feature flag e às mesmas restrições de prévia do agent no Enterprise que o app web.

Opções disponíveis: normal, fast, lite

knowledge_ids · string[] | null

max_acu_limit · integer | null

platform · string | null

Override da plataforma de VM para a sessão (por exemplo, 'windows'). Quando omitido (ou definido como 'inherit'), uma sessão criada por um Devin pai herda a plataforma do pai; caso contrário, a plataforma padrão da organização é usada. O valor deve corresponder a uma plataforma configurada para sua organização (sem diferenciar maiúsculas de minúsculas); valores não reconhecidos são rejeitados com um 400 cujo corpo do erro lista os rótulos de plataforma disponíveis para a org.

playbook_id · string | null

repos · string[] | null

secret_ids · string[] | null

session_links · string[] | null

session_secrets · SessionSecretInput · object[] | null

Show child attributes

structured_output_required · boolean | null

Quando verdadeiro (padrão), o agente DEVE chamar provide_structured_output com is_final=true antes do fim do seu turno. Quando falso, a ferramenta fica disponível, mas não é obrigatória — não há garantia de que será chamada em um determinado turno.

structured_output_schema · Structured Output Schema · object

JSON Schema (Draft 7) usado para validar a saída estruturada. Máx. 64 KB. Deve ser autocontido (sem $ref externos).

tags · string[] | null

title · string | null

Resposta

200

application/json

Resposta com sucesso

acus_consumed · number · obrigatório

created_at · integer · obrigatório

org_id · string · obrigatório

pull_requests · SessionPullRequest · object[] · obrigatório

Show child attributes

session_id · string · obrigatório

status · enum<string> · obrigatório

Opções disponíveis: new, claimed, running, exit, error, suspended, resuming

tags · string[] · obrigatório

updated_at · integer · obrigatório

url · string · obrigatório

category · enum<string> | null

A categoria de caso de uso atribuída à sessão, se a categorização tiver sido executada. Preenchida apenas nos endpoints get/list.

Opções disponíveis: bug_fixing, ci_cd_and_devops, code_quality_and_security, code_review, code_review_and_analysis, data_and_automation, documentation_and_content, feature_development, migrations_and_upgrades, other, refactoring_and_optimization, research_and_exploration, security, unit_test_generation

child_session_ids · string[] | null

is_archived · boolean · padrão: false

origin · enum<string> | null

A origem em que a sessão foi criada.

Opções disponíveis: webapp, slack, teams, api, linear, jira, automation, cli, desktop, code_scan, other

parent_session_id · string | null

playbook_id · string | null

service_user_id · string | null

status_detail · enum<string> | null

Detalhe adicional sobre o status atual da sessão. Quando o status é 'running': 'working' (trabalhando ativamente), 'waiting_for_user' (requer entrada do usuário), 'waiting_for_approval' (aguardando aprovação da ação no modo seguro) ou 'finished' (tarefa concluída). Quando o status é 'suspended': o motivo da suspensão, como 'inactivity', 'user_request', 'usage_limit_exceeded', 'out_of_credits', 'out_of_quota', 'no_quota_allocation', 'payment_declined', 'org_usage_limit_exceeded', 'total_session_limit_exceeded' ou 'error'. Preenchido apenas nos endpoints get/list.

Opções disponíveis: working, waiting_for_user, waiting_for_approval, finished, inactivity, user_request, usage_limit_exceeded, out_of_credits, out_of_quota, no_quota_allocation, payment_declined, org_usage_limit_exceeded, total_session_limit_exceeded, error

structured_output · Structured Output · object

Saída estruturada validada da sessão. Preenchido apenas em endpoints GET/list.

subcategory · string | null

O nome de exibição da subcategoria atribuída à sessão. 'Other' quando uma categoria estiver definida, mas nenhuma subcategoria tiver sido atribuída ou resolvida. Preenchido apenas nos endpoints get/list.

title · string | null

user_id · string | null