API overview
Base URL, versioning, request and response conventions, headers and IDs of the Dcision public API.
The public API runs deployed decisions on a state and returns typed answers, confidence and an action. Read endpoints, with the same API keys, list the workspace's decisions and their contracts, its account and its recent executions. A decision can also run from a secret webhook URL, without an API key, and agents can use all of it through the MCP server.
Base URL https://api.dcision.io
Version /v1 (in the path)
Auth Authorization: Bearer dcs_live_… | dcs_test_…
Format JSON in, JSON outEndpoints
| Method and path | Description |
|---|---|
POST /v1/decisions/{slug} | Run the active version of a decision. |
GET /v1/decisions | The workspace's decisions: slug, name, status and active version. |
GET /v1/decisions/{slug} | What a decision's active version accepts and answers: state schema, questions, actions and an example state. |
GET /v1/me | The key's workspace, the key, the plan and the current period's usage. |
GET /v1/executions | Recent executions with answers, action and metrics — never the inputs. |
POST /v1/hooks/{token} | Run a decision from its secret webhook URL — no API key; optionally signed with a whsec_ secret. |
POST /mcp | The MCP server for AI agents — the same keys, limits and billing. |
GET /openapi.json | The OpenAPI 3.1 description of the public API, including the decision.completed webhook event. No authentication. |
GET /health | Service health: { "status": "ok" }. No authentication. |
Decisions, versions, destinations, API keys, members and billing are managed in the app. The app's own endpoints require a user session and refuse API keys with 403 FORBIDDEN. Webhooks travel the other way — from Dcision to you — see Webhook events.
Requests
- HTTPS only, to
https://api.dcision.io. - JSON body with
Content-Type: application/json, UTF-8, at most 128 KB. - Server-side only: API keys are secrets — call the API from your backend, a worker or an agent runtime, never from a browser or a mobile app.
| Request header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <API key> — see Authentication. |
Content-Type | Yes | application/json. |
Idempotency-Key | No | Makes retries safe — see Idempotency. |
X-Request-ID | No | Your correlation ID: 1–128 characters from A–Z a–z 0–9 . _ : -. Otherwise Dcision generates one. |
Responses
-
JSON with snake_case fields; your question keys are used as-is.
-
Standard HTTP status codes:
200on success,4xxfor problems with the request,5xxfor problems on Dcision's or the engine's side. -
Errors always have the same shape — see Errors:
{ "error": { "code": "INVALID_STATE", "message": "Field company_size must be a number.", "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w" } }
| Response header | When | Description |
|---|---|---|
X-Request-ID | Always | Your X-Request-ID, or a generated req_… ID. Quote it when you contact support. |
X-RateLimit-Limit | Authenticated calls | Requests allowed per minute for your workspace — decisions and reads have separate windows. |
X-RateLimit-Remaining | Authenticated calls | Requests left in the current window. |
X-RateLimit-Reset | Authenticated calls | When the window resets, in Unix seconds. |
Retry-After | 429, and 409 while a request with the same Idempotency-Key is still running | Seconds to wait before retrying. |
Idempotent-Replayed | Replays | true when the response is a stored replay. |
IDs
IDs are a prefix followed by 20 letters and digits:
| Prefix | Identifies | Where you see it |
|---|---|---|
dec_ | a decision | decision_id in responses, the decision's page in the app |
exec_ | an execution (one run) | execution_id in responses, Executions, GET /v1/executions |
key_ | an API key | api_key.id in GET /v1/me |
dlv_ | a delivery of a destination | delivery_id in responses, the Dcision-Delivery header, a webhook event's id |
req_ | a request | X-Request-ID, request_id in errors |
Stability
The /v1 request and response shapes are stable; new fields are only added — such as scores, composites and the token counts in metrics in v0.2, and destinations in v0.3 — so ignore fields you don't know. Your decision's contract — the result keys and their types — changes only when you deploy a new version, and the response's version tells which version answered.
The API is a single HTTPS call from any language. The official SDKs for TypeScript and Python add safe retries, function destinations and webhook verification — build them from source until they are published on npm and PyPI. For the terminal and CI, use the CLI.
Destination security and limits
How Dcision protects outgoing requests — https only, SSRF guard, no redirects, secrets — what each destination type sends and stores, who can configure what, and every destination limit.
Authentication
Authenticate with Bearer API keys (dcs_live_ and dcs_test_) — create, store, rotate and revoke them — and know where they work.