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 outEndpoints
| Método y ruta | Descripción |
|---|---|
POST /v1/decisions/{slug} | Ejecuta la versión activa de una decisión. |
GET /v1/decisions | Las 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-live | Las 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/answers | Aplica las respuestas de una sesión de GPT-Live: políticas, destinos y el log de ejecuciones, facturado como una ejecución. |
GET /v1/me | El workspace de la clave, la clave, el plan y el uso del período actual. |
GET /v1/executions | Ejecuciones 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 /mcp | El servidor MCP para agentes de IA — las mismas claves, límites y facturación. |
GET /openapi.json | La descripción OpenAPI 3.1 de la API pública, incluido el evento de webhook decision.completed. Sin autenticación. |
GET /health | Estado 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 enPOST /mcp, cuyas herramientas pueden llevar un esquema de decisión completo (el estado sigue limitado a 128 KB), y 32 MB enPOST /v1/decisions/{slug}y en el webhook de entrada, cuyo estado puede llevar archivos — el webhook de entrada también aceptamultipart/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 solicitud | Obligatorio | Descripción |
|---|---|---|
Authorization | Sí | Bearer <API key> — consulta Autenticación. |
Content-Type | Sí | application/json. |
Idempotency-Key | No | Hace seguros los reintentos — consulta Idempotencia. |
X-Request-ID | No | Tu 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:
200en caso de éxito,4xxpara problemas con la solicitud,5xxpara 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 respuesta | Cuándo | Descripción |
|---|---|---|
X-Request-ID | Siempre | Tu X-Request-ID, o un ID req_… generado. Inclúyelo cuando contactes a soporte. |
X-RateLimit-Limit | Llamadas autenticadas | Solicitudes permitidas por minuto para tu workspace — las decisiones y las lecturas tienen ventanas separadas. |
X-RateLimit-Remaining | Llamadas autenticadas | Solicitudes restantes en la ventana actual. |
X-RateLimit-Reset | Llamadas autenticadas | Cuándo se reinicia la ventana, en segundos Unix. |
Retry-After | 429, y 409 mientras una solicitud con el mismo Idempotency-Key todavía se ejecuta | Segundos que hay que esperar antes de reintentar. |
Idempotent-Replayed | Reproducciones | true cuando la respuesta es una reproducción guardada. |
IDs
Los IDs son un prefijo seguido de 20 letras y dígitos:
| Prefijo | Identifica | Dónde lo ves |
|---|---|---|
dec_ | una decisión | decision_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 API | api_key.id en GET /v1/me |
dlv_ | una entrega de un destino | delivery_id en las respuestas, el header Dcision-Delivery, el id de un evento de webhook |
req_ | una solicitud | X-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.
Seguridad y límites de los destinos
Cómo protege Dcision las solicitudes salientes — solo https, protección contra SSRF, sin redirecciones, secretos —, qué envía y guarda cada tipo de destino, quién puede configurar qué y todos los límites de los destinos.
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.