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ámetroDescripción
slugEl 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ámetroDescripción
includeOpcional. probabilities añade a la respuesta la distribución completa de cada pregunta. Separados por comas; los demás valores se ignoran.

Encabezados

EncabezadoObligatorioDescripción
AuthorizationSíBearer dcs_live_… o Bearer dcs_test_… — consulta Autenticación.
Content-TypeSíapplication/json.
Idempotency-KeyNoDe 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-IDNoTu 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 } }
CampoTipoDescripción
stateobjeto, string o arrayLa 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
  }
}
CampoTipoDescripción
decision_idstringEl ID de la decisión (dec_…).
execution_idstringEl ID de esta ejecución (exec_…), que se puede buscar en Ejecuciones y en GET /v1/executions.
schemastringEl slug de la decisión.
versionintegerLa versión desplegada que respondió.
resultobjectUna 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.
confidenceobjectUn número de 0 a 1 por pregunta — consulta Confianza.
scoresobjectSolo para decisiones con preguntas de puntaje: el nivel ponderado de cada una, contado desde 1 — consulta Niveles ponderados.
compositesobjectSolo para decisiones con compuestos: el valor de cada uno.
actionstringcontinue, block, escalate o fallback — consulta Políticas y acciones.
action_reasonobjectPor qué se eligió la acción (abajo).
probabilitiesobjectSolo con ?include=probabilities: la distribución de cada pregunta.
outputobject o nullSolo cuando se activó un destino de salida estructurada: el objeto del primero que se completó, validado contra sus campos — null cuando ninguno se completó.
destinationsarraySolo 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_msintegerTiempo 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.enginestringEl motor que se ejecutó: jev, laya u openai.
metrics.modelstringLa 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_usdnumberCosto 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_tokensintegerTokens de entrada de la llamada al motor — lo que cobran Jev y OpenAI Decisions.
metrics.output_tokensintegerTokens de salida de la llamada al motor, para observabilidad: ni Jev ni OpenAI Decisions los cobran.
metrics.input_filesintegerSolo cuando el estado tiene archivos: cuántos se leyeron.
metrics.input_processing_msintegerSolo con archivos: tiempo para descargarlos y leerlos, incluido en latency_ms.
metrics.input_cost_usdnumberSolo 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

typeCampos extraSignificado
policyruleCoincidió la regla de política número rule (contando desde 0).
other_optionquestionEsa pregunta de opción respondió other; se aplica la acción de fallback.
refusalquestionEl motor (OpenAI Decisions) se negó a responder esa pregunta; no aparece en result y se aplica la acción de fallback.
low_confidencequestion, confidence, minConfidenceLa confianza de esa pregunta quedó por debajo de su mínimo; se aplica la acción de fallback.
engine_errorcodeEl 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.

Todos los 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" }
]
CampoTipoDescripción
keystringLa clave del destino en la decisión.
typestringreply, json, llm, agent, workflow, webhook, http o function.
modestringjson: template (construido a partir del resultado) o extract (rellenado por un LLM).
formatstringjson: ui cuando output es una pantalla json-render; ausente para datos.
outputobjectjson que se completó: el objeto, validado contra sus campos.
issuesarrayjson que no pasó la validación: { path, message } por problema, con path como JSON Pointer.
statusstringQué ocurrió (abajo). Las respuestas fijas y las funciones que se activaron no tienen status.
textstringreply: el mensaje. llm: la respuesta del modelo.
buttonsarrayreply: las etiquetas de los botones.
modelstringllm y json en modo extract: el modelo que respondió, tal como lo informa el proveedor.
usage.input_tokensintegerllm y json en modo extract: tokens de entrada contados por el proveedor — los cobra el proveedor, no Dcision.
usage.output_tokensintegerllm: tokens de salida contados por el proveedor.
replystring o nullagent en modo sync: la respuesta del agente, o null cuando su respuesta no tenía campo de respuesta.
responseanyagent en modo sync: la respuesta completa del agente, o null cuando supera los 16,000 caracteres.
errorstringEntradas failed: por qué falló la llamada al LLM o al agente — o la salida estructurada.
delivery_idstringEntradas queued: el ID dlv_… enviado con cada intento — deduplica con él.
functionstringfunction: el handler que tu código debe llamar.
paramsobjectfunction: los argumentos de la llamada.
reasonstringEntradas skipped: por qué el destino no se ejecutó (abajo).
paramstringskipped con missing_param: el param obligatorio que no tenía valor.
statusTiposSignificado
completedjson, llm, agentSe construyó la salida, o el modelo o el agente respondió — quien llama esperó por ello.
failedjson, llm, agentLa llamada falló o la salida no coincidió con sus campos; la decisión sigue siendo válida. Consulta error (e issues).
queuedwebhook, http, workflow, agentDcision lo entrega en segundo plano, con reintentos — consulta Entrega y reintentos.
skippedtodosEl destino coincidió pero no se ejecutó.
reasonSignificado
missing_paramUn param marcado como required no tenía valor.
limitCoincidieron 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).
unavailableNo 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:

EstadoCódigos
400INVALID_REQUEST — JSON mal formado, un cuerpo que no es un objeto, un Idempotency-Key inválido
401INVALID_API_KEY
402CREDITS_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
404DECISION_NOT_FOUND
409DECISION_NOT_DEPLOYED, DECISION_DISABLED, IDEMPOTENCY_CONFLICT — con Retry-After: 1 mientras una solicitud con la misma clave sigue en ejecución
413PAYLOAD_TOO_LARGE — cuerpo de más de 32 MB
422INVALID_STATE — incluido un estado que supera el presupuesto de tokens del motor — 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

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:

  1. Clave de API → 401 INVALID_API_KEY.
  2. Límite de tasa del workspace → 429 RATE_LIMITED. A partir de aquí, las respuestas incluyen los encabezados X-RateLimit-*.
  3. Formato del slug → 404 DECISION_NOT_FOUND; cuerpo → 400 INVALID_REQUEST.
  4. 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_CONFLICT con Retry-After: 1. Si no, la clave se reserva para esta solicitud — y se libera de nuevo si falla algún paso posterior.
  5. La decisión existe, está activada y tiene una versión desplegada → 404 / 409.
  6. 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.
  7. Validación del estado, luego el presupuesto de tokens del motor para el estado y las preguntas → 422 INVALID_STATE.
  8. Llamada al motor, con reintentos dentro de timeoutMs → 424 / 502 / 503 / 504 si falla, o la acción de fallback con onEngineError: "fallback".
  9. Compuestos y políticas → action y action_reason.
  10. Destinos → las respuestas y las funciones se devuelven, las llamadas a LLM y a agentes sync se esperan, las entregas se ponen en cola — luego 200 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.

En esta página