# Dcision Documentation

> Dcision is Decision as a Service: structured, typed and auditable decisions over a state — choice, score and probability questions, policies that pick an action and destinations that act on it — deployed as one API.

## Get started

- [Introduction](https://docs.dcision.io/docs): What Dcision is — structured decisions over a state (choice, score and probability questions plus policies that pick an action), deployed as one API — and why it exists.
- [Quickstart](https://docs.dcision.io/docs/quickstart): Sign up, create a decision from a template, test it in the Playground, deploy it and call it with cURL, JavaScript or Python — in about five minutes.

## Concepts

- [Decision schema](https://docs.dcision.io/docs/concepts/decision-schema): The JSON document behind every decision — the state it accepts, the questions it answers, composites, the policies that pick the action, the runtime settings and the destinations.
- [Questions](https://docs.dcision.io/docs/concepts/questions): Choice, score and probability questions — structured instructions and criteria, what the API returns for each, weighted levels, the reserved other option and minimum confidence.
- [Composites](https://docs.dcision.io/docs/concepts/composites): Combine several answers into one number with weights you control — Σ(weight × value) / Σ|weight| — return it in composites and use it in policies.
- [Policies and actions](https://docs.dcision.io/docs/concepts/policies-and-actions): How policy rules with AND conditions are written and evaluated, and how the action and action_reason of every response are computed — policy, other option, low confidence, default or engine error.
- [Confidence and probabilities](https://docs.dcision.io/docs/concepts/confidence-and-probabilities): What confidence means for each question type on one 0–1 scale, how it affects minConfidence, weighted levels, the full probability distributions and near ties.
- [Versions and deploy](https://docs.dcision.io/docs/concepts/versions-and-deploy): Drafts, immutable versions, deploys, slugs, disabling, duplicating and deleting decisions — and what your API clients see at each step.
- [Decision settings](https://docs.dcision.io/docs/concepts/settings): engine, storeInput, storeOutput, timeoutMs, fallbackAction and onEngineError — what each runtime setting of a decision does, its default and its limits — plus the workspace settings.
- [Templates](https://docs.dcision.io/docs/concepts/templates): The nine built-in templates — what each one decides, its questions, composites and policies, the patterns it demonstrates — and how to start a decision from one.
- [Engines and BYOK](https://docs.dcision.io/docs/concepts/engines-and-byok): Decisions run on Jev or Laya. Use Dcision's key on TypeSafe, bring your own OpenRouter, TypeSafe or Vercel AI Gateway key, or run Laya on your own server — plus cost, limits and errors.
- [Playground](https://docs.dcision.io/docs/concepts/playground): Test drafts — including unsaved edits — with real payloads, read confidence and distributions, preview destinations, compare runs and replay inputs from past executions.
- [Executions and usage](https://docs.dcision.io/docs/concepts/executions-and-usage): Every run is logged with its version, action reason, confidence and — if you allow it — input and output. Find executions, read usage and know how long logs are kept.

## Patterns

- [Patterns overview](https://docs.dcision.io/docs/patterns): TypeSafe's four architectural patterns — speculative fan-out, confidence-gated routing, composite scoring and intent routing — and how each maps to Dcision features and templates.
- [Speculative fan-out](https://docs.dcision.io/docs/patterns/fan-out): Ask every question a flow might need in one call — Jev answers them in parallel — and let AND rules and your code decide which answers matter. Built on the Support Ticket Triage template.
- [Confidence-gated routing](https://docs.dcision.io/docs/patterns/confidence-routing): Use confidence as a second axis — the answer says what, confidence says whether to act — with a minimum confidence per question and per-action AND rules. Built on the Voice Banking template.
- [Composite scoring](https://docs.dcision.io/docs/patterns/composite-scoring): Break a judgment into atomic scores and combine them with weights you control — composites computed by Dcision and usable in policies. Built on the Resume Screening template.
- [Intent routing](https://docs.dcision.io/docs/patterns/intent-routing): Classify each request in one fast call and route it to the cheapest capable handler — code, a specialist LLM or a person. Built on the Customer Service Router template.

## Destinations

- [Destinations overview](https://docs.dcision.io/docs/destinations): What happens after a decision — per option, score level, probability threshold or final action — fixed replies, LLM answers, your agent, workflows, signed webhooks, HTTP requests and functions.
- [Destination triggers](https://docs.dcision.io/docs/destinations/triggers): When a destination fires — conditions on answers, confidence, weighted levels and composites, final actions, a minimum confidence per route, score levels, probability thresholds — and in which order.
- [Params and templates](https://docs.dcision.io/docs/destinations/params-and-templates): Map values into a destination — params from a field or a fixed value, required params, {{…}} variables in URLs, headers, bodies and texts, and how each place encodes them for you.
- [Fixed replies](https://docs.dcision.io/docs/destinations/fixed-replies): Return a ready-made message — text and optional buttons, with variables — in the API response for a given result, instantly and without calling any model.
- [LLM answers](https://docs.dcision.io/docs/destinations/llm): Let a model answer for a route — Dcision calls OpenRouter or Vercel AI Gateway with your workspace's own key, the route's prompt as the system message and the state as input.
- [Agents](https://docs.dcision.io/docs/destinations/agents): Hand a result to your own agent endpoint with the route's instructions and tools — wait for its reply in the response, or hand off in the background with retries.
- [Workflows](https://docs.dcision.io/docs/destinations/workflows): Trigger n8n, Make, Zapier, Pipedream or any workflow URL with the route's variables as flat JSON fields, plus the decision under dcision — signed and retried in the background.
- [Webhooks](https://docs.dcision.io/docs/destinations/webhooks): Receive the signed decision.completed event at your URL — the envelope, its headers, verifying Dcision-Signature with and without the SDKs, raw bodies in Express and Next.js, rotation and deduplication.
- [HTTP requests](https://docs.dcision.io/docs/destinations/http-requests): Call any API after a decision — method, URL, headers and a JSON body built from variables and workspace secrets — delivered with retries, an Idempotency-Key and a signature.
- [Functions](https://docs.dcision.io/docs/destinations/functions): Let your own code act on a result — the response names the function and its params, and the TypeScript and Python SDKs call the handler you registered, in order and once per call.
- [Workspace secrets](https://docs.dcision.io/docs/destinations/secrets): Keep tokens and secret URLs out of decisions — workspace secrets referenced as {{secrets.NAME}}, who can manage them, how they are stored and masked, and when changes apply.
- [Delivery and retries](https://docs.dcision.io/docs/destinations/delivery): How Dcision delivers webhooks, API requests, workflows and agent hand-offs — at least once, six attempts over about seven hours, Retry-After, timeouts, statuses, resends and retention.
- [Testing destinations](https://docs.dcision.io/docs/destinations/testing): Preview destinations in the Playground with secrets masked, run them for real with livemode false, use test API keys and follow deliveries, attempts and receiver answers.
- [Destination security and limits](https://docs.dcision.io/docs/destinations/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.

## API reference

- [API overview](https://docs.dcision.io/docs/api): Base URL, versioning, request and response conventions, headers and IDs of the Dcision public API.
- [Authentication](https://docs.dcision.io/docs/api/authentication): Authenticate with Bearer API keys (dcs_live_ and dcs_test_) — create, store, rotate and revoke them — and know where they work.
- [Run a decision](https://docs.dcision.io/docs/api/run-decision): POST /v1/decisions/{slug} — path, query, headers, request body, every response field and the errors, with examples in cURL, JavaScript and Python.
- [List and get decisions](https://docs.dcision.io/docs/api/decisions): GET /v1/decisions and GET /v1/decisions/{slug} — the decisions of an API key's workspace and the contract of each one's active version, with an example state.
- [Get account and usage](https://docs.dcision.io/docs/api/me): GET /v1/me — the workspace, API key and plan behind a key, plus this billing period's usage. Verify a key in CI and watch your quota from code.
- [List executions](https://docs.dcision.io/docs/api/executions): GET /v1/executions — recent runs of your decisions with answers, action, reason and metrics, filtered by decision and status and paginated with a cursor. Inputs are never returned.
- [Webhook trigger](https://docs.dcision.io/docs/api/webhook-trigger): POST /v1/hooks/{token} — run a deployed decision from a secret URL without an API key, from forms, CRMs, Zapier, n8n, Make or any backend, optionally signed with a whsec_ secret.
- [Webhook events](https://docs.dcision.io/docs/api/webhooks): The decision.completed event of the OpenAPI document — the request sent to webhook destinations, its headers, every field of the event and the answers Dcision expects.
- [Errors](https://docs.dcision.io/docs/api/errors): The error format and every error code with its HTTP status, what it means and what to do about it — plus which errors are safe to retry.
- [Rate limits](https://docs.dcision.io/docs/api/rate-limits): Per-workspace request limits for each plan, separate windows for decisions and reads, the X-RateLimit headers on every call, Retry-After on 429 and how to back off.
- [Idempotency](https://docs.dcision.io/docs/api/idempotency): Retry safely with the Idempotency-Key header — keys reserved before the run, replays of successful calls for 24 hours, the Idempotent-Replayed header and IDEMPOTENCY_CONFLICT.
- [Limits](https://docs.dcision.io/docs/api/limits): Every size and count limit in one place — request body, state and token budget, decision schema, destinations and deliveries, identifiers, workspace, team and sign-in limits.

## SDKs

- [SDKs overview](https://docs.dcision.io/docs/sdks): The official TypeScript and Python SDKs — what they add over plain HTTPS, how they compare, and how to build them from source until they are published on npm and PyPI.
- [TypeScript SDK](https://docs.dcision.io/docs/sdks/typescript): @dcision/sdk for Node.js, Bun, Deno and edge runtimes — build from source, decide, destinations and functions, errors, idempotent retries, executions, me() and webhook verification.
- [Python SDK](https://docs.dcision.io/docs/sdks/python): The dcision package for Python 3.9+ — build from source, decide, destinations and functions, errors, idempotent retries, executions, me() and webhook verification with Flask or FastAPI.

## AI agents

- [Use Dcision in Claude Code](https://docs.dcision.io/docs/claude-code): Connect Claude Code to Dcision with the MCP server and the Dcision skill — list, check and run decisions, write and validate decision schemas, and use the CLI and SDKs from your agent.
- [MCP server](https://docs.dcision.io/docs/mcp): The Dcision MCP server at https://api.dcision.io/mcp — authentication, the nine tools with their inputs and outputs, errors, and setup for Claude Code, Cursor, VS Code, Claude Desktop, Codex, Gemini CLI and curl.

## Guides

- [Lead qualification](https://docs.dcision.io/docs/guides/lead-qualification): Score purchase intent, set a priority, rank with a lead score and route inbound leads to sales, SDRs or nurture — and block spam — with the Lead Qualification template.
- [Support routing](https://docs.dcision.io/docs/guides/support-routing): Route support messages to the right department, rate their urgency and escalate to a human when needed, with the Support Routing template.
- [Spam detection](https://docs.dcision.io/docs/guides/spam-detection): Classify free text as allow, review or block and estimate its spam probability with the Spam Detection template — a decision with a text state.
- [Agent routing](https://docs.dcision.io/docs/guides/agent-routing): Let an AI agent pick its first tool and decide when a task really needs a large language model, with the Agent Routing template.
- [RAG relevance](https://docs.dcision.io/docs/guides/rag-relevance): Check whether a retrieved chunk answers the query before calling the LLM, and decide when to retrieve more context, with the RAG Relevance template.
- [Writing good questions](https://docs.dcision.io/docs/guides/writing-good-questions): Phrase instructions, options and criteria that Jev answers reliably — literal wording, math and dates in code, less indirection, a filtered state, option order and no text generation.
- [Handling low confidence and other](https://docs.dcision.io/docs/guides/low-confidence-and-other): Design decisions that admit uncertainty — the reserved other option, minimum confidence, confidence policies, the fallback action, near ties and the engine-error fallback.
- [Overview and calibration](https://docs.dcision.io/docs/guides/overview-and-calibration): Read a decision's Overview tab — runs, success rate, latency, cost, actions, reasons and per-question statistics — and act on every calibration suggestion, with the thresholds behind it.
- [Idempotent retries](https://docs.dcision.io/docs/guides/idempotent-retries): A production-ready Dcision client — idempotency keys, timeouts, which errors to retry, exponential backoff with Retry-After — in JavaScript and Python.

## Platform

- [Plans, quotas and billing](https://docs.dcision.io/docs/plans-and-billing): Genesis, Developer, Growth and Enterprise — included decisions, prepaid credits past them, rate limits, decision and log limits — what is billed, and how credits, upgrades, downgrades, cancellations and invoices work.
- [Team, roles and account](https://docs.dcision.io/docs/team-and-roles): Organizations and workspaces, the Owner, Admin, Member and Viewer roles, invitations, leaving and transferring, deleting a workspace, passwords, signing out everywhere and e-mail language.
- [CLI](https://docs.dcision.io/docs/cli): The dcision command line — save an API key, run decisions, list templates, scaffold and validate decision schemas offline — with exit codes for scripts and CI.
- [Security and data](https://docs.dcision.io/docs/security): What Dcision stores and for how long, where your state goes — destinations included — how keys, secrets and passwords are protected, roles and workspace isolation, and how to keep sensitive data out.

## Resources

- [Changelog](https://docs.dcision.io/docs/changelog): Release notes of Dcision — v0.6 Laya engine; v0.5 prepaid credits; v0.4 MCP server, Claude Code and webhook triggers; v0.3 destinations, teams, SDKs and Overview; v0.2 full Jev coverage; v0.1 launch.
- [FAQ](https://docs.dcision.io/docs/faq): Answers to common questions about Dcision — billing, quotas and credits, keys, models and latency, data retention, deployments and integration.

## Quick facts

- API base URL: https://api.dcision.io (version in the path: /v1).
- Run a decision: `POST https://api.dcision.io/v1/decisions/{slug}` with `Authorization: Bearer dcs_live_…` (or `dcs_test_…`) and the JSON body `{ "state": … }` — an object, a string or an array, depending on the decision.
- The response has `result`, `confidence` (0–1), `scores` (weighted levels), `composites`, `action` (`continue`, `block`, `escalate`, `fallback`), `action_reason`, `metrics` and, for decisions with destinations, `destinations` (one entry per destination that fired: fixed replies, LLM and agent answers, queued deliveries, functions to run).
- Read with the same key: `GET https://api.dcision.io/v1/decisions` (slugs, status, version), `GET https://api.dcision.io/v1/decisions/{slug}` (state schema, questions, actions, example state), `GET https://api.dcision.io/v1/me` (workspace, plan, usage) and `GET https://api.dcision.io/v1/executions` (recent runs, never the inputs). OpenAPI 3.1: `GET https://api.dcision.io/openapi.json`.
- MCP server for agents: `https://api.dcision.io/mcp` (Streamable HTTP, `Authorization: Bearer <API key>`), tools `get_account`, `list_decisions`, `get_decision`, `check_state`, `run_decision` (billed), `list_executions`, `list_templates`, `get_template`, `validate_schema`. Claude Code skill: https://docs.dcision.io/skills/dcision/SKILL.md
- Webhook trigger, no API key: `POST https://api.dcision.io/v1/hooks/whk_…` with `{ "state": … }` or the raw payload; with a secret, sign it like deliveries (`Dcision-Signature`, 300 s window) or send `Authorization: Bearer whsec_…`.
- Errors always look like `{ "error": { "code", "message", "request_id", "details" } }`. A `409 IDEMPOTENCY_CONFLICT` with `Retry-After: 1` means the same Idempotency-Key is still running: retry with the same key.
- Webhook, workflow, agent and API-request destinations are delivered at least once (6 attempts over about 7 hours) and signed with `Dcision-Signature: t=<unix>,v1=<hex>`, the HMAC-SHA256 of `<t>.<raw body>` with the workspace's `whsec_` secret; deduplicate on the `dlv_` delivery ID.
- Official SDKs: TypeScript `@dcision/sdk` and Python `dcision` — not on npm or PyPI yet; build them from source (`pnpm --filter @dcision/sdk build`, `pip install ./packages/sdk-python`).
- Build, test, deploy decisions and create API keys in the app: https://app.dcision.io
- The whole documentation in one file: https://docs.dcision.io/llms-full.txt
- Markdown of any page: append `.md` to its URL, e.g. https://docs.dcision.io/docs/quickstart.md