Executar uma decisão

POST /v1/decisions/{slug} — path, query, headers, corpo da requisição, todos os campos da resposta e os erros, com exemplos em cURL, JavaScript e Python.

POST https://api.dcision.io/v1/decisions/{slug}

Executa a versão ativa da decisão slug sobre um estado e devolve uma resposta tipada por pergunta, a confiança de cada resposta, os níveis ponderados e os composites, a ação escolhida pelas políticas da decisão e — para decisões com destinos — o que acontece depois. Todas as perguntas são respondidas numa única chamada ao engine.

Uma sessão de voz do GPT-Live que já tem as respostas as envia para POST /v1/decisions/{slug}/openai-live/answers: mesmas políticas, destinos e resposta, sem chamada ao engine.

Requisição

Parâmetros de path

ParâmetroDescrição
slugO slug da decisão, exibido no editor e na aba Publicar — por exemplo lead-qualification.

Parâmetros de query

ParâmetroDescrição
includeOpcional. probabilities adiciona à resposta a distribuição completa de cada pergunta. Separado por vírgulas; outros valores são ignorados.

Headers

HeaderObrigatórioDescrição
AuthorizationSimBearer dcs_live_… ou Bearer dcs_test_… — veja Autenticação.
Content-TypeSimapplication/json.
Idempotency-KeyNãoDe 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Repete a resposta armazenada de uma chamada bem-sucedida por 24 horas — veja Idempotência.
X-Request-IDNãoO seu ID de correlação (mesmo conjunto de caracteres). Devolvido na resposta e armazenado com a execução.

Corpo

{ "state": { "message": "We need pricing for 500 users and want to start next month.", "company_size": 500 } }
CampoTipoDescrição
stateobject, string ou arrayA entrada da decisão: um objeto para um estado de objeto, uma string não vazia para um estado de texto, um array não vazio (até 500 itens) para um estado de lista. Validado contra o state schema da decisão; campos não declarados de um objeto são aceitos e repassados ao engine. Campos image, audio e file recebem um arquivo — veja Entradas.

Outros campos de nível superior são ignorados. O corpo inteiro precisa caber em 32 MB (espaço para arquivos de até 20 MB cada, 24 MB no total); o estado sem os arquivos precisa caber em 128 KB e, depois que os arquivos são lidos, no orçamento de tokens do engine junto com as perguntas.

Exemplos

curl -X POST https://api.dcision.io/v1/decisions/lead-qualification \
  -H "Authorization: Bearer $DCISION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-8421" \
  -d '{
    "state": {
      "message": "We need pricing for 500 users and want to start next month.",
      "company_size": 500,
      "source": "website"
    }
  }'

Uma decisão com estado de texto recebe uma string:

curl -X POST https://api.dcision.io/v1/decisions/spam-detection \
  -H "Authorization: Bearer $DCISION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "state": "Congratulations! You won a $1000 gift card, click here to claim now." }'

Uma decisão com estado de lista recebe um array — aqui, a transcrição de um chat, para uma decisão chamada chat-triage cujo estado é uma lista de strings:

curl -X POST https://api.dcision.io/v1/decisions/chat-triage \
  -H "Authorization: Bearer $DCISION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "state": ["Hi!", "Can I get a quote for 50 seats?"] }'

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-ID: req_Qm8vT2kLx9Pw4Rz7Nc1B
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1791195060
{
  "decision_id": "dec_3fKq9ZtW1mXcV7bN2pLa",
  "execution_id": "exec_8HsT2kQw9ZyR4vMn1cXe",
  "schema": "lead-qualification",
  "version": 1,
  "result": {
    "purchase_intent": 0.9412,
    "priority": "high",
    "route": "sales"
  },
  "confidence": {
    "purchase_intent": 0.8824,
    "priority": 0.69,
    "route": 0.85
  },
  "scores": { "priority": 2.81 },
  "composites": { "lead_score": 0.8414 },
  "action": "continue",
  "action_reason": { "type": "default" },
  "metrics": {
    "latency_ms": 412,
    "engine": "jev",
    "model": "jev-1.13.0",
    "estimated_cost_usd": 0.00001575,
    "input_tokens": 375,
    "output_tokens": 36
  }
}
CampoTipoDescrição
decision_idstringO ID da decisão (dec_…).
execution_idstringO ID desta execução (exec_…), pesquisável em Execuções e em GET /v1/executions.
schemastringO slug da decisão.
versionintegerA versão publicada que respondeu.
resultobjectUma resposta por pergunta, na ordem das perguntas: uma opção (choice), o rótulo do nível mais provável (score) ou a probabilidade de sim de 0 a 1 (probability). Vazio depois de um fallback por erro do engine.
confidenceobjectUm número de 0 a 1 por pergunta — veja Confiança.
scoresobjectSó para decisões com perguntas de nota: o nível ponderado de cada uma, contado a partir de 1 — veja Níveis ponderados.
compositesobjectSó para decisões com composites: o valor de cada um.
actionstringcontinue, block, escalate ou fallback — veja Políticas e ações.
action_reasonobjectPor que a ação foi escolhida (abaixo).
probabilitiesobjectSó com ?include=probabilities: a distribuição de cada pergunta.
outputobject ou nullSó quando um destino de saída estruturada disparou: o objeto do primeiro que foi concluído, verificado contra os seus campos — null quando nenhum foi concluído.
destinationsarraySó para decisões com destinos: uma entrada por destino que disparou, na ordem do schema — [] quando nenhum disparou. Veja abaixo.
metrics.latency_msintegerTempo que a execução levou dentro da Dcision — validação do estado, chamada ao engine, composites e políticas. Destinos de LLM e de agente, que rodam depois, não entram.
metrics.enginestringO engine que rodou: jev, laya ou openai.
metrics.modelstringA versão exata do modelo que respondeu, por exemplo jev-1.13.0 — também quando o workspace usa um alias como jev-latest.
metrics.estimated_cost_usdnumberCusto estimado da chamada: tokens de entrada do engine × o preço do modelo, mais a leitura dos arquivos do estado, quando houver.
metrics.input_tokensintegerTokens de entrada da chamada ao engine — o que Jev e OpenAI Decisions cobram.
metrics.output_tokensintegerTokens de saída da chamada ao engine, para observabilidade: nem Jev nem OpenAI Decisions os cobram.
metrics.input_filesintegerSó quando o estado tem arquivos: quantos foram lidos.
metrics.input_processing_msintegerSó com arquivos: tempo para baixá-los e lê-los, incluído em latency_ms.
metrics.input_cost_usdnumberSó com arquivos: custo estimado da leitura pela OpenAI (transcrição, descrição de imagens, leitura de arquivos) — 0 quando a Dcision os leu sozinha. Incluído em estimated_cost_usd.

action_reason

typeCampos extrasSignificado
policyruleA regra de política número rule combinou (a partir de 0).
other_optionquestionEssa pergunta de escolha respondeu other; vale a ação de fallback.
refusalquestionO engine (OpenAI Decisions) se recusou a responder essa pergunta; ela não aparece em result e a ação de fallback se aplica.
low_confidencequestion, confidence, minConfidenceA confiança dessa pergunta ficou abaixo do mínimo; vale a ação de fallback.
engine_errorcodeO engine falhou com o erro code e o onEngineError da decisão é fallback: vale a ação de fallback, result fica vazio e a chamada não é cobrada.
default—Nada combinou: continue.

As chaves das perguntas são suas

result, confidence, scores e probabilities são indexados pelas chaves das suas perguntas, e composites pelas chaves dos seus composites, então nunca colidem com os campos de nível superior: o result.action do template Spam Detection (a sua pergunta action: allow, review ou block) é diferente do action de nível superior escolhido pelas suas políticas.

destinations

Presente quando a decisão tem destinos. Cada entrada descreve um destino que disparou — o que ele devolveu ou o que a Dcision colocou na fila — e destinos nunca fazem a chamada falhar: um problema aparece na sua entrada.

Todos os tipos de entrada
[
  {
    "key": "sales_reply",
    "type": "reply",
    "text": "Thanks! Someone from our sales team will contact you today.",
    "buttons": ["Book a demo", "See pricing"]
  },
  {
    "key": "lead",
    "type": "json",
    "mode": "template",
    "status": "completed",
    "output": { "company_size": 500, "route": "sales", "start": "next month" }
  },
  {
    "key": "sales_llm",
    "type": "llm",
    "status": "completed",
    "text": "Thanks for reaching out! Someone from our sales team will contact you today to talk about your 500 users.",
    "model": "openai/gpt-5-mini",
    "usage": { "input_tokens": 61, "output_tokens": 27 }
  },
  {
    "key": "sales_agent",
    "type": "agent",
    "status": "completed",
    "reply": "I booked a demo for tomorrow at 10:00. You'll get an invitation by e-mail.",
    "response": { "reply": "I booked a demo for tomorrow at 10:00. You'll get an invitation by e-mail.", "booking_id": "bk_5521" }
  },
  { "key": "sales_summary", "type": "llm", "status": "failed", "error": "No answer from OpenRouter within 20 s." },
  { "key": "sales_crm", "type": "workflow", "status": "queued", "delivery_id": "dlv_8kJx2mQp4LzN7vR1tY6w" },
  { "key": "notify_sales", "type": "webhook", "status": "queued", "delivery_id": "dlv_Q2w9Lm4Xc7Rv1Tz8Wn3B" },
  { "key": "handoff", "type": "agent", "status": "queued", "delivery_id": "dlv_Hq2Lm9Xc4Rv1Tz8Wn3Bk" },
  { "key": "assign_owner", "type": "function", "function": "assignToSales", "params": { "email": "ana@acme.com", "route": "sales" } },
  { "key": "create_ticket", "type": "http", "status": "skipped", "reason": "missing_param", "param": "ticket_id" }
]
CampoTipoDescrição
keystringA chave do destino na decisão.
typestringreply, json, llm, agent, workflow, webhook, http ou function.
modestringjson: template (montado a partir do resultado) ou extract (preenchido por um LLM).
formatstringjson: ui quando output é uma tela json-render; ausente para dados.
outputobjectjson concluído: o objeto, verificado contra os seus campos.
issuesarrayjson que falhou na validação: { path, message } por problema, sendo path um JSON Pointer.
statusstringO que aconteceu (abaixo). Respostas fixas e funções que dispararam não têm status.
textstringreply: a mensagem. llm: a resposta do modelo.
buttonsarrayreply: os rótulos dos botões.
modelstringllm e json no modo extract: o modelo que respondeu, conforme informado pelo provedor.
usage.input_tokensintegerllm e json no modo extract: tokens de entrada contados pelo provedor — cobrados pelo provedor, não pela Dcision.
usage.output_tokensintegerllm: tokens de saída contados pelo provedor.
replystring ou nullagent no modo sync: a resposta do agente, ou null quando a resposta dele não tinha campo de reply.
responseanyagent no modo sync: a resposta inteira do agente, ou null quando ela passa de 16.000 caracteres.
errorstringEntradas failed: por que a chamada ao LLM ou ao agente — ou a saída estruturada — falhou.
delivery_idstringEntradas queued: o ID dlv_… enviado em cada tentativa — deduplique por ele.
functionstringfunction: o handler que o seu código deve chamar.
paramsobjectfunction: os argumentos da chamada.
reasonstringEntradas skipped: por que o destino não rodou (abaixo).
paramstringskipped com missing_param: o param obrigatório que ficou sem valor.
statusTiposSignificado
completedjson, llm, agentA saída foi montada, ou o modelo ou o agente respondeu — quem chamou esperou por isso.
failedjson, llm, agentA chamada falhou ou a saída não bateu com os seus campos; a decisão continua válida. Veja error (e issues).
queuedwebhook, http, workflow, agentA Dcision entrega em segundo plano, com retries — veja Entrega e retries.
skippedtodosO destino combinou, mas não rodou.
reasonSignificado
missing_paramUm param marcado como required ficou sem valor.
limitMais de 10 destinos combinaram, ou mais de 3 que fazem quem chamou esperar (respostas de LLM, agentes sync e saídas estruturadas no modo extract).
unavailableNão foi possível colocar a entrega na fila.

No Playground, as entradas são prévias — "status": "preview" com a requisição ou o prompt que seria enviado — a menos que você rode os destinos de verdade. Veja Testando destinos.

Erros

Os erros usam o formato padrão. Os que este endpoint devolve:

StatusCódigos
400INVALID_REQUEST — JSON malformado, um corpo que não é um objeto, um Idempotency-Key inválido
401INVALID_API_KEY
402CREDITS_EXHAUSTED — o volume incluído acabou e não há créditos; SPEND_CAP_REACHED — o limite de gastos do ciclo foi atingido; QUOTA_EXCEEDED — o volume incluído de um plano com limite rígido acabou
404DECISION_NOT_FOUND
409DECISION_NOT_DEPLOYED, DECISION_DISABLED, IDEMPOTENCY_CONFLICT — com Retry-After: 1 enquanto uma requisição com a mesma chave ainda está rodando
413PAYLOAD_TOO_LARGE — corpo maior que 32 MB
422INVALID_STATE — inclusive um estado acima do orçamento de tokens do engine — e INVALID_SCHEMA
424ENGINE_NOT_CONFIGURED
429RATE_LIMITED
500INTERNAL_ERROR
502ENGINE_AUTH_FAILED, ENGINE_INVALID_REQUEST, ENGINE_ERROR
503ENGINE_RATE_LIMITED, ENGINE_UNAVAILABLE
504ENGINE_TIMEOUT

Os erros de engine vêm depois dos retries da própria Dcision, dentro do timeoutMs da decisão. Quando o onEngineError da decisão é fallback, os erros de engine 502, 503 e 504 viram um 200 com a ação de fallback e action_reason.type = "engine_error" — veja Configurações da decisão.

Ordem das verificações

Quando várias coisas estão erradas, o primeiro passo que falha define o erro:

  1. API key → 401 INVALID_API_KEY.
  2. Rate limit do workspace → 429 RATE_LIMITED. Daqui em diante, as respostas trazem os headers X-RateLimit-*.
  3. Formato do slug → 404 DECISION_NOT_FOUND; corpo → 400 INVALID_REQUEST.
  4. Idempotência: uma resposta armazenada para a mesma chave e a mesma requisição é repetida agora; a mesma chave com outra requisição → 409 IDEMPOTENCY_CONFLICT; a mesma requisição ainda rodando → 409 IDEMPOTENCY_CONFLICT com Retry-After: 1. Caso contrário, a chave fica reservada para esta requisição — e é liberada de novo se algum passo seguinte falhar.
  5. A decisão existe, está ativada e tem uma versão publicada → 404 / 409.
  6. Volume incluído e créditos: além das decisões incluídas no plano, os créditos disponíveis → 402 CREDITS_EXHAUSTED, depois o limite de gastos → 402 SPEND_CAP_REACHED; um plano com limite rígido → 402 QUOTA_EXCEEDED.
  7. Validação do estado, depois o orçamento de tokens do engine para o estado e as perguntas → 422 INVALID_STATE.
  8. Chamada ao engine, com retries dentro de timeoutMs → 424 / 502 / 503 / 504 em caso de falha, ou a ação de fallback com onEngineError: "fallback".
  9. Composites e políticas → action e action_reason.
  10. Destinos → respostas e funções são devolvidas, chamadas de LLM e de agente sync são aguardadas, entregas entram na fila — então 200 OK.

Os passos 7 a 10 são registrados como execuções, falhas incluídas. Só um 200 novo do passo 10 é cobrado — não erros, não repetições, não fallbacks por erro do engine. Veja Planos, cotas e cobrança.

Nesta página