Visión general de la API

URL base, versionado, convenciones de solicitudes y respuestas, headers e IDs de la API pública de Dcision.

La API pública ejecuta decisiones desplegadas sobre un estado y devuelve respuestas tipadas, confianza y una acción. Los endpoints de lectura, con las mismas claves de API, listan las decisiones del workspace y sus contratos, su cuenta y sus ejecuciones recientes. Una decisión también puede ejecutarse desde una URL de webhook secreta, sin clave de API, y los agentes pueden usarlo todo a través del servidor MCP.

Base URL   https://api.dcision.io
Version    /v1 (in the path)
Auth       Authorization: Bearer dcs_live_… | dcs_test_…
Format     JSON in, JSON out

Endpoints

Método y rutaDescripción
POST /v1/decisions/{slug}Ejecuta la versión activa de una decisión.
GET /v1/decisionsLas decisiones del workspace: slug, nombre, estado y versión activa.
GET /v1/decisions/{slug}Qué acepta y responde la versión activa de una decisión: esquema del estado, preguntas, acciones y un estado de ejemplo.
GET /v1/decisions/{slug}/openai-liveLas preguntas de la versión activa como delegación de GPT-Live, para la voz en tiempo real de OpenAI.
POST /v1/decisions/{slug}/openai-live/answersAplica las respuestas de una sesión de GPT-Live: políticas, destinos y el log de ejecuciones, facturado como una ejecución.
GET /v1/meEl workspace de la clave, la clave, el plan y el uso del período actual.
GET /v1/executionsEjecuciones recientes con respuestas, acción y métricas — nunca las entradas.
POST /v1/hooks/{token}Ejecuta una decisión desde su URL de webhook secreta — sin clave de API; firma opcional con un secreto whsec_.
POST /mcpEl servidor MCP para agentes de IA — las mismas claves, límites y facturación.
GET /openapi.jsonLa descripción OpenAPI 3.1 de la API pública, incluido el evento de webhook decision.completed. Sin autenticación.
GET /healthEstado del servicio: { "status": "ok" }. Sin autenticación.

Las decisiones, versiones, destinos, claves de API, miembros y la facturación se gestionan en la app. Los endpoints propios de la app requieren una sesión de usuario y rechazan las claves de API con 403 FORBIDDEN. Los webhooks viajan en sentido contrario — de Dcision hacia ti — consulta Eventos de webhook.

Solicitudes

  • Solo HTTPS, a https://api.dcision.io.
  • Body JSON con Content-Type: application/json, UTF-8, de como máximo 128 KB — 1 MB en POST /mcp, cuyas herramientas pueden llevar un esquema de decisión completo (el estado sigue limitado a 128 KB), y 32 MB en POST /v1/decisions/{slug} y en el webhook de entrada, cuyo estado puede llevar archivos — el webhook de entrada también acepta multipart/form-data. Consulta Límites.
  • Solo del lado del servidor: las claves de API son secretos — llama a la API desde tu backend, un worker o el runtime de un agente, nunca desde un navegador ni una app móvil.
Header de solicitudObligatorioDescripción
AuthorizationSíBearer <API key> — consulta Autenticación.
Content-TypeSíapplication/json.
Idempotency-KeyNoHace seguros los reintentos — consulta Idempotencia.
X-Request-IDNoTu ID de correlación: de 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Si no lo envías, Dcision genera uno.

Respuestas

  • JSON con campos en snake_case; las claves de tus preguntas se usan tal cual.

  • Códigos de estado HTTP estándar: 200 en caso de éxito, 4xx para problemas con la solicitud, 5xx para problemas del lado de Dcision o del motor.

  • Los errores siempre tienen la misma forma — consulta Errores:

    { "error": { "code": "INVALID_STATE", "message": "Field company_size must be a number.", "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w" } }
Header de respuestaCuándoDescripción
X-Request-IDSiempreTu X-Request-ID, o un ID req_… generado. Inclúyelo cuando contactes a soporte.
X-RateLimit-LimitLlamadas autenticadasSolicitudes permitidas por minuto para tu workspace — las decisiones y las lecturas tienen ventanas separadas.
X-RateLimit-RemainingLlamadas autenticadasSolicitudes restantes en la ventana actual.
X-RateLimit-ResetLlamadas autenticadasCuándo se reinicia la ventana, en segundos Unix.
Retry-After429, y 409 mientras una solicitud con el mismo Idempotency-Key todavía se ejecutaSegundos que hay que esperar antes de reintentar.
Idempotent-ReplayedReproduccionestrue cuando la respuesta es una reproducción guardada.

IDs

Los IDs son un prefijo seguido de 20 letras y dígitos:

PrefijoIdentificaDónde lo ves
dec_una decisióndecision_id en las respuestas, la página de la decisión en la app
exec_una ejecución (una corrida)execution_id en las respuestas, Ejecuciones, GET /v1/executions
key_una clave de APIapi_key.id en GET /v1/me
dlv_una entrega de un destinodelivery_id en las respuestas, el header Dcision-Delivery, el id de un evento de webhook
req_una solicitudX-Request-ID, request_id en los errores

Estabilidad

Las formas de solicitud y respuesta de /v1 son estables; solo se agregan campos nuevos — como scores, composites y los conteos de tokens en metrics en la v0.2, y destinations en la v0.3 —, así que ignora los campos que no conozcas. El contrato de tu decisión — las claves de result y sus tipos — solo cambia cuando tú despliegas una nueva versión, y el version de la respuesta indica qué versión respondió.

La API es una sola llamada HTTPS desde cualquier lenguaje. Los SDKs oficiales para TypeScript y Python agregan reintentos seguros, destinos de función y verificación de webhooks — compílalos desde el código fuente hasta que se publiquen en npm y PyPI. Para la terminal y CI, usa la CLI.

En esta página