Ejecutar una decisión
POST /v1/decisions/{slug} — ruta, query, encabezados, cuerpo de la solicitud, cada campo de la respuesta y los errores, con ejemplos en cURL, JavaScript y Python.
POST https://api.dcision.io/v1/decisions/{slug}Ejecuta la versión activa de la decisión slug sobre un estado y devuelve una respuesta tipada por pregunta, la confianza de cada respuesta, los niveles ponderados y los compuestos, la acción elegida por las políticas de la decisión y — para decisiones con destinos — qué ocurre después. Todas las preguntas se responden en una sola llamada al motor.
Una sesión de voz de GPT-Live que ya tiene las respuestas las envía a POST /v1/decisions/{slug}/openai-live/answers: mismas políticas, destinos y respuesta, sin llamada al motor.
Solicitud
Parámetros de ruta
| Parámetro | Descripción |
|---|---|
slug | El slug de la decisión, que se muestra en el editor y en la pestaña Publicar — por ejemplo lead-qualification. |
Parámetros de query
| Parámetro | Descripción |
|---|---|
include | Opcional. probabilities añade a la respuesta la distribución completa de cada pregunta. Separados por comas; los demás valores se ignoran. |
Encabezados
| Encabezado | Obligatorio | Descripción |
|---|---|---|
Authorization | Sí | Bearer dcs_live_… o Bearer dcs_test_… — consulta Autenticación. |
Content-Type | Sí | application/json. |
Idempotency-Key | No | De 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Repite la respuesta almacenada de una llamada exitosa durante 24 horas — consulta Idempotencia. |
X-Request-ID | No | Tu ID de correlación (mismo conjunto de caracteres). Se devuelve en la respuesta y se guarda con la ejecución. |
Cuerpo
{ "state": { "message": "We need pricing for 500 users and want to start next month.", "company_size": 500 } }| Campo | Tipo | Descripción |
|---|---|---|
state | objeto, string o array | La entrada de la decisión: un objeto para un estado de objeto, un string no vacío para un estado de texto, un array no vacío (hasta 500 elementos) para un estado de lista. Se valida contra el schema del estado de la decisión; los campos no declarados de un objeto se aceptan y se reenvían al motor. Los campos image, audio y file reciben un archivo — consulta Entradas. |
Los demás campos de nivel superior se ignoran. El cuerpo completo debe caber en 32 MB (espacio para archivos de hasta 20 MB cada uno, 24 MB en total); el estado sin sus archivos debe caber en 128 KB y, una vez leídos los archivos, en el presupuesto de tokens del motor junto con las preguntas.
Ejemplos
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"
}
}'Una decisión con un estado de texto recibe un 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." }'Una decisión con un estado de lista recibe un array — aquí la transcripción de un chat, para una decisión llamada chat-triage cuyo estado es una 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?"] }'Respuesta
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 | Descripción |
|---|---|---|
decision_id | string | El ID de la decisión (dec_…). |
execution_id | string | El ID de esta ejecución (exec_…), que se puede buscar en Ejecuciones y en GET /v1/executions. |
schema | string | El slug de la decisión. |
version | integer | La versión desplegada que respondió. |
result | object | Una respuesta por pregunta, en el orden de las preguntas: una opción (choice), la etiqueta del nivel más probable (score) o la probabilidad de sí de 0 a 1 (probability). Vacío tras un fallback por error del motor. |
confidence | object | Un número de 0 a 1 por pregunta — consulta Confianza. |
scores | object | Solo para decisiones con preguntas de puntaje: el nivel ponderado de cada una, contado desde 1 — consulta Niveles ponderados. |
composites | object | Solo para decisiones con compuestos: el valor de cada uno. |
action | string | continue, block, escalate o fallback — consulta Políticas y acciones. |
action_reason | object | Por qué se eligió la acción (abajo). |
probabilities | object | Solo con ?include=probabilities: la distribución de cada pregunta. |
output | object o null | Solo cuando se activó un destino de salida estructurada: el objeto del primero que se completó, validado contra sus campos — null cuando ninguno se completó. |
destinations | array | Solo para decisiones con destinos: una entrada por cada destino que se activó, en el orden del schema — [] cuando ninguno se activó. Consulta más abajo. |
metrics.latency_ms | integer | Tiempo que tomó la ejecución dentro de Dcision — validación del estado, llamada al motor, compuestos y políticas. Los destinos de LLM y de agente, que se ejecutan después, no se incluyen. |
metrics.engine | string | El motor que se ejecutó: jev, laya u openai. |
metrics.model | string | La versión exacta del modelo que respondió, por ejemplo jev-1.13.0 — también cuando el workspace usa un alias como jev-latest. |
metrics.estimated_cost_usd | number | Costo estimado de la llamada: tokens de entrada del motor × el precio del modelo, más la lectura de los archivos del estado, si los hay. |
metrics.input_tokens | integer | Tokens de entrada de la llamada al motor — lo que cobran Jev y OpenAI Decisions. |
metrics.output_tokens | integer | Tokens de salida de la llamada al motor, para observabilidad: ni Jev ni OpenAI Decisions los cobran. |
metrics.input_files | integer | Solo cuando el estado tiene archivos: cuántos se leyeron. |
metrics.input_processing_ms | integer | Solo con archivos: tiempo para descargarlos y leerlos, incluido en latency_ms. |
metrics.input_cost_usd | number | Solo con archivos: costo estimado de leerlos con OpenAI (transcripción, descripción de imágenes, lectura de archivos) — 0 cuando Dcision los leyó por sí mismo. Incluido en estimated_cost_usd. |
action_reason
type | Campos extra | Significado |
|---|---|---|
policy | rule | Coincidió la regla de política número rule (contando desde 0). |
other_option | question | Esa pregunta de opción respondió other; se aplica la acción de fallback. |
refusal | question | El motor (OpenAI Decisions) se negó a responder esa pregunta; no aparece en result y se aplica la acción de fallback. |
low_confidence | question, confidence, minConfidence | La confianza de esa pregunta quedó por debajo de su mínimo; se aplica la acción de fallback. |
engine_error | code | El motor falló con el error code y el onEngineError de la decisión es fallback: se aplica la acción de fallback, result está vacío y la llamada no se cobra. |
default | — | No coincidió nada: continue. |
Las claves de las preguntas son tuyas
result, confidence, scores y probabilities usan como claves las claves de tus preguntas, y composites las de tus compuestos, así que nunca chocan con los campos de nivel superior: el result.action de la plantilla Detección de spam (su pregunta action: allow, review o block) es distinto del action de nivel superior elegido por sus políticas.
destinations
Presente cuando la decisión tiene destinos. Cada entrada describe un destino que se activó — lo que devolvió, o lo que Dcision puso en cola — y los destinos nunca hacen fallar la llamada: un problema aparece en su 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 | Descripción |
|---|---|---|
key | string | La clave del destino en la decisión. |
type | string | reply, json, llm, agent, workflow, webhook, http o function. |
mode | string | json: template (construido a partir del resultado) o extract (rellenado por un LLM). |
format | string | json: ui cuando output es una pantalla json-render; ausente para datos. |
output | object | json que se completó: el objeto, validado contra sus campos. |
issues | array | json que no pasó la validación: { path, message } por problema, con path como JSON Pointer. |
status | string | Qué ocurrió (abajo). Las respuestas fijas y las funciones que se activaron no tienen status. |
text | string | reply: el mensaje. llm: la respuesta del modelo. |
buttons | array | reply: las etiquetas de los botones. |
model | string | llm y json en modo extract: el modelo que respondió, tal como lo informa el proveedor. |
usage.input_tokens | integer | llm y json en modo extract: tokens de entrada contados por el proveedor — los cobra el proveedor, no Dcision. |
usage.output_tokens | integer | llm: tokens de salida contados por el proveedor. |
reply | string o null | agent en modo sync: la respuesta del agente, o null cuando su respuesta no tenía campo de respuesta. |
response | any | agent en modo sync: la respuesta completa del agente, o null cuando supera los 16,000 caracteres. |
error | string | Entradas failed: por qué falló la llamada al LLM o al agente — o la salida estructurada. |
delivery_id | string | Entradas queued: el ID dlv_… enviado con cada intento — deduplica con él. |
function | string | function: el handler que tu código debe llamar. |
params | object | function: los argumentos de la llamada. |
reason | string | Entradas skipped: por qué el destino no se ejecutó (abajo). |
param | string | skipped con missing_param: el param obligatorio que no tenía valor. |
status | Tipos | Significado |
|---|---|---|
completed | json, llm, agent | Se construyó la salida, o el modelo o el agente respondió — quien llama esperó por ello. |
failed | json, llm, agent | La llamada falló o la salida no coincidió con sus campos; la decisión sigue siendo válida. Consulta error (e issues). |
queued | webhook, http, workflow, agent | Dcision lo entrega en segundo plano, con reintentos — consulta Entrega y reintentos. |
skipped | todos | El destino coincidió pero no se ejecutó. |
reason | Significado |
|---|---|
missing_param | Un param marcado como required no tenía valor. |
limit | Coincidieron más de 10 destinos, o más de 3 que hacen esperar a quien llama (respuestas de LLM, agentes sync y salidas estructuradas en modo extract). |
unavailable | No se pudo poner la entrega en cola. |
En el Playground, las entradas son vistas previas — "status": "preview" con la solicitud o el prompt que se enviaría — a menos que ejecutes los destinos de verdad. Consulta Probar destinos.
Errores
Los errores usan el formato estándar. Los que devuelve este endpoint:
| Estado | Códigos |
|---|---|
| 400 | INVALID_REQUEST — JSON mal formado, un cuerpo que no es un objeto, un Idempotency-Key inválido |
| 401 | INVALID_API_KEY |
| 402 | CREDITS_EXHAUSTED — el volumen incluido se agotó y no quedan créditos; SPEND_CAP_REACHED — se alcanzó el tope de gasto del ciclo; QUOTA_EXCEEDED — se agotó el volumen incluido de un plan con tope estricto |
| 404 | DECISION_NOT_FOUND |
| 409 | DECISION_NOT_DEPLOYED, DECISION_DISABLED, IDEMPOTENCY_CONFLICT — con Retry-After: 1 mientras una solicitud con la misma clave sigue en ejecución |
| 413 | PAYLOAD_TOO_LARGE — cuerpo de más de 32 MB |
| 422 | INVALID_STATE — incluido un estado que supera el presupuesto de tokens del motor — 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 |
Los errores del motor llegan después de los propios reintentos de Dcision, dentro del timeoutMs de la decisión. Cuando el onEngineError de la decisión es fallback, los errores del motor 502, 503 y 504 se convierten en un 200 con la acción de fallback y action_reason.type = "engine_error" — consulta Configuración de la decisión.
Orden de las comprobaciones
Cuando hay varios problemas, el primer paso que falla determina el error:
- Clave de API →
401 INVALID_API_KEY. - Límite de tasa del workspace →
429 RATE_LIMITED. A partir de aquí, las respuestas incluyen los encabezadosX-RateLimit-*. - Formato del slug →
404 DECISION_NOT_FOUND; cuerpo →400 INVALID_REQUEST. - Idempotencia: una respuesta almacenada para la misma clave y la misma solicitud se repite en este punto; la misma clave con otra solicitud →
409 IDEMPOTENCY_CONFLICT; la misma solicitud aún en ejecución →409 IDEMPOTENCY_CONFLICTconRetry-After: 1. Si no, la clave se reserva para esta solicitud — y se libera de nuevo si falla algún paso posterior. - La decisión existe, está activada y tiene una versión desplegada →
404/409. - Volumen incluido y créditos: superadas las decisiones incluidas en el plan, los créditos disponibles →
402 CREDITS_EXHAUSTED, luego el tope de gasto →402 SPEND_CAP_REACHED; un plan con tope estricto →402 QUOTA_EXCEEDED. - Validación del estado, luego el presupuesto de tokens del motor para el estado y las preguntas →
422 INVALID_STATE. - Llamada al motor, con reintentos dentro de
timeoutMs→424/502/503/504si falla, o la acción de fallback cononEngineError: "fallback". - Compuestos y políticas →
actionyaction_reason. - Destinos → las respuestas y las funciones se devuelven, las llamadas a LLM y a agentes
syncse esperan, las entregas se ponen en cola — luego200 OK.
Los pasos 7 a 10 se registran como ejecuciones, incluidos los fallos. Solo se cobra un 200 nuevo del paso 10 — no los errores, ni las repeticiones, ni los fallbacks por error del motor. Consulta Planes, cuotas y facturación.
Autenticación
Autentícate con claves de API Bearer (dcs_live_ y dcs_test_) — créalas, guárdalas, rótalas y revócalas — y conoce dónde funcionan.
Listar y obtener decisiones
GET /v1/decisions y GET /v1/decisions/{slug} — las decisiones del workspace de una clave de API y el contrato de la versión activa de cada una — más la delegación de GPT-Live de una decisión y su endpoint de respuestas.