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âmetro | Descrição |
|---|---|
slug | O slug da decisão, exibido no editor e na aba Publicar — por exemplo lead-qualification. |
Parâmetros de query
| Parâmetro | Descrição |
|---|---|
include | Opcional. probabilities adiciona à resposta a distribuição completa de cada pergunta. Separado por vírgulas; outros valores são ignorados. |
Headers
| Header | Obrigatório | Descrição |
|---|---|---|
Authorization | Sim | Bearer dcs_live_… ou Bearer dcs_test_… — veja Autenticação. |
Content-Type | Sim | application/json. |
Idempotency-Key | Não | De 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-ID | Não | O 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 } }| Campo | Tipo | Descrição |
|---|---|---|
state | object, string ou array | A 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
}
}| Campo | Tipo | Descrição |
|---|---|---|
decision_id | string | O ID da decisão (dec_…). |
execution_id | string | O ID desta execução (exec_…), pesquisável em Execuções e em GET /v1/executions. |
schema | string | O slug da decisão. |
version | integer | A versão publicada que respondeu. |
result | object | Uma 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. |
confidence | object | Um número de 0 a 1 por pergunta — veja Confiança. |
scores | object | Só para decisões com perguntas de nota: o nível ponderado de cada uma, contado a partir de 1 — veja Níveis ponderados. |
composites | object | Só para decisões com composites: o valor de cada um. |
action | string | continue, block, escalate ou fallback — veja Políticas e ações. |
action_reason | object | Por que a ação foi escolhida (abaixo). |
probabilities | object | Só com ?include=probabilities: a distribuição de cada pergunta. |
output | object ou null | Só 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. |
destinations | array | Só para decisões com destinos: uma entrada por destino que disparou, na ordem do schema — [] quando nenhum disparou. Veja abaixo. |
metrics.latency_ms | integer | Tempo 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.engine | string | O engine que rodou: jev, laya ou openai. |
metrics.model | string | A 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_usd | number | Custo estimado da chamada: tokens de entrada do engine × o preço do modelo, mais a leitura dos arquivos do estado, quando houver. |
metrics.input_tokens | integer | Tokens de entrada da chamada ao engine — o que Jev e OpenAI Decisions cobram. |
metrics.output_tokens | integer | Tokens de saída da chamada ao engine, para observabilidade: nem Jev nem OpenAI Decisions os cobram. |
metrics.input_files | integer | Só quando o estado tem arquivos: quantos foram lidos. |
metrics.input_processing_ms | integer | Só com arquivos: tempo para baixá-los e lê-los, incluído em latency_ms. |
metrics.input_cost_usd | number | Só 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
type | Campos extras | Significado |
|---|---|---|
policy | rule | A regra de política número rule combinou (a partir de 0). |
other_option | question | Essa pergunta de escolha respondeu other; vale a ação de fallback. |
refusal | question | O engine (OpenAI Decisions) se recusou a responder essa pergunta; ela não aparece em result e a ação de fallback se aplica. |
low_confidence | question, confidence, minConfidence | A confiança dessa pergunta ficou abaixo do mínimo; vale a ação de fallback. |
engine_error | code | O 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.
[
{
"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" }
]| Campo | Tipo | Descrição |
|---|---|---|
key | string | A chave do destino na decisão. |
type | string | reply, json, llm, agent, workflow, webhook, http ou function. |
mode | string | json: template (montado a partir do resultado) ou extract (preenchido por um LLM). |
format | string | json: ui quando output é uma tela json-render; ausente para dados. |
output | object | json concluído: o objeto, verificado contra os seus campos. |
issues | array | json que falhou na validação: { path, message } por problema, sendo path um JSON Pointer. |
status | string | O que aconteceu (abaixo). Respostas fixas e funções que dispararam não têm status. |
text | string | reply: a mensagem. llm: a resposta do modelo. |
buttons | array | reply: os rótulos dos botões. |
model | string | llm e json no modo extract: o modelo que respondeu, conforme informado pelo provedor. |
usage.input_tokens | integer | llm e json no modo extract: tokens de entrada contados pelo provedor — cobrados pelo provedor, não pela Dcision. |
usage.output_tokens | integer | llm: tokens de saída contados pelo provedor. |
reply | string ou null | agent no modo sync: a resposta do agente, ou null quando a resposta dele não tinha campo de reply. |
response | any | agent no modo sync: a resposta inteira do agente, ou null quando ela passa de 16.000 caracteres. |
error | string | Entradas failed: por que a chamada ao LLM ou ao agente — ou a saída estruturada — falhou. |
delivery_id | string | Entradas queued: o ID dlv_… enviado em cada tentativa — deduplique por ele. |
function | string | function: o handler que o seu código deve chamar. |
params | object | function: os argumentos da chamada. |
reason | string | Entradas skipped: por que o destino não rodou (abaixo). |
param | string | skipped com missing_param: o param obrigatório que ficou sem valor. |
status | Tipos | Significado |
|---|---|---|
completed | json, llm, agent | A saída foi montada, ou o modelo ou o agente respondeu — quem chamou esperou por isso. |
failed | json, llm, agent | A chamada falhou ou a saída não bateu com os seus campos; a decisão continua válida. Veja error (e issues). |
queued | webhook, http, workflow, agent | A Dcision entrega em segundo plano, com retries — veja Entrega e retries. |
skipped | todos | O destino combinou, mas não rodou. |
reason | Significado |
|---|---|
missing_param | Um param marcado como required ficou sem valor. |
limit | Mais 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). |
unavailable | Nã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:
| Status | Códigos |
|---|---|
| 400 | INVALID_REQUEST — JSON malformado, um corpo que não é um objeto, um Idempotency-Key inválido |
| 401 | INVALID_API_KEY |
| 402 | CREDITS_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 |
| 404 | DECISION_NOT_FOUND |
| 409 | DECISION_NOT_DEPLOYED, DECISION_DISABLED, IDEMPOTENCY_CONFLICT — com Retry-After: 1 enquanto uma requisição com a mesma chave ainda está rodando |
| 413 | PAYLOAD_TOO_LARGE — corpo maior que 32 MB |
| 422 | INVALID_STATE — inclusive um estado acima do orçamento de tokens do engine — e INVALID_SCHEMA |
| 424 | ENGINE_NOT_CONFIGURED |
| 429 | RATE_LIMITED |
| 500 | INTERNAL_ERROR |
| 502 | ENGINE_AUTH_FAILED, ENGINE_INVALID_REQUEST, ENGINE_ERROR |
| 503 | ENGINE_RATE_LIMITED, ENGINE_UNAVAILABLE |
| 504 | ENGINE_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:
- API key →
401 INVALID_API_KEY. - Rate limit do workspace →
429 RATE_LIMITED. Daqui em diante, as respostas trazem os headersX-RateLimit-*. - Formato do slug →
404 DECISION_NOT_FOUND; corpo →400 INVALID_REQUEST. - 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_CONFLICTcomRetry-After: 1. Caso contrário, a chave fica reservada para esta requisição — e é liberada de novo se algum passo seguinte falhar. - A decisão existe, está ativada e tem uma versão publicada →
404/409. - 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. - Validação do estado, depois o orçamento de tokens do engine para o estado e as perguntas →
422 INVALID_STATE. - Chamada ao engine, com retries dentro de
timeoutMs→424/502/503/504em caso de falha, ou a ação de fallback comonEngineError: "fallback". - Composites e políticas →
actioneaction_reason. - Destinos → respostas e funções são devolvidas, chamadas de LLM e de agente
syncsão aguardadas, entregas entram na fila — então200 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.
Autenticação
Autentique com API keys Bearer (dcs_live_ e dcs_test_) — crie, guarde, troque e revogue as chaves — e saiba onde elas funcionam.
Listar e obter decisões
GET /v1/decisions e GET /v1/decisions/{slug} — as decisões do workspace de uma API key e o contrato da versão ativa de cada uma — mais a delegação de uma decisão para o GPT-Live e o endpoint das respostas.