Developer Docs

Integrate the Decision API in minutes.

Call /api/decide when a product, agent, queue, or internal tool needs a recorded yes, no, or review before it changes state. Persist the Decision Record v1 fields beside the downstream action.

Production requests require an API key. The public playground is for API-fit checks only and does not represent production auth, quotas, telemetry, replay visibility, or retention.

Start quickstart Request API access Open playground API reference Decision intelligence Machine spec OpenAPI

docs.json: loading… vendors.json: loading… source refs: loading…

Surface status

Use this map to separate the production integration core from lifecycle surfaces that depend on caller data and public utilities that support review. This is a product-status guide, not a legal availability term.

Stable core

Decision API and Decision Record v1

The first production boundary uses /api/decide, response views, idempotency, replay, verification, and fields your system stores beside the action.

/api/decide
Decision Record v1
Replay and verify links

Stable proof

SDK, verifier, and fixtures

The JavaScript SDK, CLI verifier, hosted verifier, conformance fixtures, and copyable examples support implementation and review without inventing package claims.

@decide-fyi/sdk
Hosted verifier
Offline fixture pack

Data-dependent

Execution, outcomes, and intelligence

Execution receipts, Outcome Records, effectiveness, confidence, anomalies, benchmarks, and Decision Packet v1 become most useful after the caller reports action attempts and terminal results.

Execution Receipt v1
Outcome Record v1
Policy intelligence reports

Reference utility

Patterns, vendors, alerts, and status

Pattern catalog, vendor directory, source-alert feed, status page, and security packet help teams evaluate and operate Decide. They are supporting surfaces around the core API.

Policy patterns
Reference directory
Readiness and alert packets

Quickstart: call the Decision API

For a binding production verdict, send structured context through a versioned declarative Rulebook v1. Supply facts directly through context.inputs, or invoke one registered trusted adapter with a pinned version and manifest hash. Do not send both. The public JSON Schema is available at https://api.decide.fyi/schemas/rulebook-v1.schema.json, and the conformance index is available at https://api.decide.fyi/conformance/rulebook-v1/index.json. Store the full Decision Record v1 object with the action your system takes. The legacy single, multi, and runtime modes remain AI-assisted.

Production boundary: Rulebook v1 supports only binding_mode values direct_declarative_rulebook and trusted_adapter_facts_then_declarative_rulebook. Customer-authored executable policy logic is not supported today; a request such as customer_executable_rulebook fails closed with RULEBOOK_BINDING_MODE_UNSUPPORTED instead of being reinterpreted as a direct declarative rulebook.

Response-only material: Decision Record fields such as runtime_binding, trusted_adapter, adapter_facts, rulebook_attestation, application_verdict, and action are produced by Decide. Do not send them as request authority; Rulebook requests that preload output material fail closed with RULEBOOK_OUTPUT_MATERIAL_FORBIDDEN.

Rulebook v1 conformance fixtures cover pricing-exception-direct-approve.json, solana-execution-gate-adapter-approve.json, executable-payload-rejected.json, and caller-output-material-rejected.json. Success fixtures assert deterministic semantic output, rulebook_contract schema URL/hash/evaluator metadata, and repeat-run stability.

Rulebook compatibility: compatibility_policy_v1 means Historical replay never reinterprets stored records with the current evaluator or adapter. Rulebook id/version pairs cannot silently rebind to new hashes or evaluator versions. Adapter dependency changes require explicit adapter and rulebook version migration, while REST, MCP, and SDK responses may add optional fields but cannot remove, rename, or change stable field meanings without a new versioned contract.

Golden replay corpus: https://api.decide.fyi/replay/rulebook-v1/index.json publishes rulebook_v1_golden_replay_v1 fixtures under historical_rulebook_replay_v1 for direct rulebooks, the Solana trusted-adapter gate, and all four reference notary families. Backend migrations should run npm run rulebook:migration-dry-run -- --json before changing evaluator, adapter, or rulebook routing. Release gates should use a rulebook_migration_v1 manifest with npm run rulebook:migration-dry-run -- --migration path/to/migration.json --json so expected drift and approval status are machine-readable. The manifest schema is https://api.decide.fyi/schemas/rulebook-migration-v1.schema.json.

cURL

curl -i https://www.decide.fyi/api/decide \
  -H "content-type: application/json" \
  -H "x-api-key: $DECIDE_API_KEY" \
  -H "x-idempotency-key: deal_1042_discount_15" \
  -d '{
    "mode": "rulebook",
    "binding_mode": "direct_declarative_rulebook",
    "rulebook": {
      "schema_version": "rulebook_v1",
      "rulebook_id": "pricing_exception",
      "version": "2026-06-11",
      "input_schema": {
        "required": [
          "requested_discount_percent",
          "margin_floor_passed",
          "owner_verified"
        ],
        "properties": {
          "requested_discount_percent": { "type": "number" },
          "margin_floor_passed": { "type": "boolean" },
          "owner_verified": { "type": "boolean" }
        }
      },
      "rules": [{
        "rule_id": "approve_standard_exception",
        "priority": 100,
        "condition": {
          "all": [
            { "field": "requested_discount_percent", "operator": "lte", "value": 15 },
            { "field": "margin_floor_passed", "operator": "eq", "value": true },
            { "field": "owner_verified", "operator": "eq", "value": true }
          ]
        },
        "outcome": {
          "decision": "yes",
          "verdict": "APPROVE",
          "action": "approve_discount",
          "reason_code": "STANDARD_EXCEPTION_ALLOWED"
        }
      }],
      "default_outcome": {
        "decision": "review",
        "verdict": "REVIEW",
        "action": "route_to_pricing_owner",
        "reason_code": "MANUAL_REVIEW_REQUIRED"
      }
    },
    "context": {
      "workflow": "pricing_exception",
      "source_record_id": "deal_1042",
      "requested_action": "approve_discount",
      "inputs": {
        "requested_discount_percent": 15,
        "margin_floor_passed": true,
        "owner_verified": true
      }
    }
  }'

Response

{
  "decision_record_version": "decision_record_v1",
  "c": "yes",
  "v": "APPROVE",
  "verdict": "yes",
  "application_verdict": "APPROVE",
  "reason_code": "STANDARD_EXCEPTION_ALLOWED",
  "matched_rule_id": "approve_standard_exception",
  "rulebook": {
    "schema_version": "rulebook_v1",
    "id": "pricing_exception",
    "version": "2026-06-11",
    "hash": "4cf1..."
  },
  "evaluator_version": "decide_rulebook_v1",
  "rulebook_contract": {
    "schema_version": "rulebook_v1",
    "schema_url": "https://api.decide.fyi/schemas/rulebook-v1.schema.json",
    "schema_hash": "bbf6...",
    "evaluator_version": "decide_rulebook_v1"
  },
  "runtime_binding": {
    "production_core": "hybrid_declarative_rulebook_with_trusted_adapters",
    "binding_mode": "direct_declarative_rulebook",
    "verdict_authority": "declarative_rulebook",
    "customer_supplied_code": "rejected"
  },
  "rulebook_registry": {
    "rulebook_registry_version": "decision_rulebook_registry_v1",
    "schema_version": "rulebook_v1",
    "rulebook_id": "pricing_exception",
    "version": "2026-06-11",
    "hash": "4cf1...",
    "evaluator_version": "decide_rulebook_v1",
    "hash_algorithm": "sha256",
    "canonicalization": "json.sort_deep.v1",
    "scope_hash": "a982...",
    "registry_attestation": {
      "registry_attestation_version": "decision_registry_attestation_v1",
      "status": "signed",
      "attestation_hash": "8a31...",
      "key_id": "decide_registry_ed25519_...",
      "signature_algorithm": "ed25519",
      "signature": "ed25519:..."
    },
    "registered_at": "2026-06-11T00:00:00.000Z"
  },
  "request_id": "req_9f3c",
  "decision_id": "dec_43b2",
  "idempotency_key": "deal_1042_discount_15",
  "evidence": ["STANDARD_EXCEPTION_ALLOWED"],
  "evidence_manifest": {
    "codes": ["STANDARD_EXCEPTION_ALLOWED"],
    "sources": []
  },
  "action": "approve_discount",
  "action_binding": {
    "system": "pricing_exception",
    "resource": "deal_1042",
    "proposed_action": "approve_discount"
  },
  "policy_id": "pricing_exception",
  "policy_version": "2026-06-11",
  "policy_hash": "4cf1...",
  "source_hash": "4cf1...",
  "policy_bundle": {
    "id": "pricing_exception",
    "version": "2026-06-11",
    "hash": "4cf1...",
    "hash_algorithm": "sha256",
    "canonicalization": "json.sort_deep.v1"
  },
  "policy_bundle_hash": "4cf1...",
  "decision_confidence": {
    "decision_confidence_version": "decision_confidence_v1",
    "score": 0.91,
    "level": "high",
    "similar_decisions": 43,
    "policy_stability": "high",
    "recommendation": "high_confidence_proceed",
    "confidence_hash": "4ca2..."
  },
  "confidence_hash": "4ca2...",
  "input_hash": "8b1d...",
  "output_hash": "de43...",
  "record_hash": "7f3a...",
  "receipt_hash": "c91e...",
  "receipt_key_id": "decide_ed25519_2026_05",
  "receipt_signature": "ed25519:9d4e...",
  "receipt_signature_algorithm": "ed25519",
  "receipt_public_key_fingerprint": "65af...",
  "replay_url": "/api/decision/dec_43b2/replay",
  "verify_url": "/api/decision/dec_43b2/verify",
  "integrity": {
    "canonicalization": "json.sort_deep.v1",
    "hash_algorithm": "sha256",
    "policy_hash": "4cf1...",
    "policy_bundle_hash": "4cf1...",
    "signature": {
      "algorithm": "ed25519",
      "key_id": "decide_ed25519_2026_05",
      "public_key_fingerprint": "65af..."
    }
  },
  "created_at": "2026-06-11T00:00:00.000Z"
}

Application binding

decide_application_binding_v1 is the contract for workflow applications that install Decide into one customer-facing or internal action path. The application can be broad, but before it hands off execution it must bind the Decide runtime material to the app-level record.

Accepted facts

Binding facts must come from context.inputs or registered adapter_facts; trusted adapters emit facts only and the declarative rulebook remains the verdict selector.

Required material

Preserve rulebook_contract, runtime_binding, verdict, application_verdict, action, reason_code, matched_rule_id, rulebook.hash, input_hash, and rulebook_attestation.bundle_hash.

Response-only material

The application preserves Decide-produced material after evaluation. It must not preload runtime_binding, adapter_facts, rulebook_attestation, application_verdict, or action into the Rulebook request.

Before action

must_bind_before_action is true. If action_executes_before_decision_material_is_captured, the app is exploratory or advisory, not a deterministic production Decide-backed workflow.

This is why Krafthaus apps can differ at the surface level while still sharing the same deterministic Decide runtime underneath: the app owns intake, interface, and handoff, while Decide owns the binding verdict, runtime metadata, replay/conformance references, and record material.

Choose the docs path

The full docs stay on one page for fast search, with focused references for the parts teams need during integration review.

Start Quickstart

Make the first server-side call and inspect the Decision Record shape.

Open quickstart

Core API reference

Review endpoints, response views, auth, rate limits, and storage fields.

Open API reference

Proof Verification

Use hosted, CLI, and API verification for exported records and receipt signatures.

Open verification

Moat Intelligence

Track execution, outcomes, effectiveness, confidence, benchmarks, and anomalies.

Open intelligence

Operate Errors

Map failures into fail-closed behavior, retries, and remediation steps.

Open error reference

Boundary One action asks first

A product, agent, queue, CRM, billing flow, or internal tool pauses before a state-changing action.

API contract Record returns

The caller stores verdict, evidence, action binding, policy bundle, hashes, replay, and verify URLs.

Lifecycle Receipts attach

Execution receipts and outcomes prove what the caller attempted and whether the business result worked.

Packet Proof travels

Decision packets, hosted verification, CLI checks, and audit chains let reviewers inspect the record outside runtime storage.

Protocol map: from action gate to portable proof

The public API is one call at the action boundary, but the protocol trail is what makes it useful for buyers, auditors, support, and operations.

Input Action context

Question, workflow, source record, owner rule, and requested mutation.

Record Decision Record

Verdict, evidence, action binding, policy bundle, hashes, replay, and verify URL.

Execute Execution Receipt

Target system, target object, mutation, executor, status, and before/after hashes.

Observe Outcome Record

Business result, observed metrics, execution references, and outcome hash.

Learn Intelligence

Effectiveness, confidence, anomaly reports, benchmarks, and audit-chain links.

Decision Packet anatomy

A Decision Packet is the portable buyer-review artifact. It bundles the decision, what was attempted, what happened, and the proof needed to verify the export outside runtime storage.

Trust escalation: start with a Decision Record; add packet export and audit-chain verification only when a boundary needs portable buyer, support, security, or procurement review.

decision_packet_v1 packet_hash

Core record

decision_record carries verdict, evidence, action binding, policy bundle, record_hash, receipt_hash, replay, and verify URLs.

Execution

execution_receipts[] shows whether the authorized mutation was attempted, against which target system/object, and with before/after state hashes.

Outcome

outcome_records[] reports the business result, observed metrics, action references, and outcome hashes.

Intelligence

policy_effectiveness, confidence, anomaly, benchmark, and pattern metadata explain how outcomes inform future policy review.

Chain

audit_chain includes retained links, rolling Merkle root, link hashes, and verification hints when chain export is requested.

01 Packet hash

Recompute packet_hash over the canonical packet with packet_hash omitted.

02 Embedded record

Verify the included Decision Record hashes, policy bundle hash, and configured HMAC or Ed25519 receipt signature.

03 Lifecycle links

Check execution and outcome hashes against the record IDs, action binding, and receipt references.

04 Review proof

Validate intelligence report hashes and retained audit-chain links before forwarding the packet to support, security, or procurement.

Use Verification docs for the focused flow, or run npx @decide-fyi/sdk verify-packet decision-packet.json --summary.

Decision lifecycle: record, execute, outcome, intelligence

The core API is bigger than a yes/no response. It creates a protocol trail that starts before state changes and keeps learning after the downstream action happens.

01 Decision Record

POST /api/decide returns verdict, action binding, evidence, policy bundle hash, record hash, receipt hash, replay, and verification.

02 Execution Receipt

POST /api/decision/:id/execution records the target-system mutation, executor, execution status, and state hashes.

03 Outcome Record

POST /api/decision/:id/outcome reports the result, observed metrics, execution references, and outcome hash.

04 Policy Intelligence

Policy effectiveness, predictive confidence, anomaly reports, and opt-in benchmarks are derived from Outcome Records.

For the focused implementation path, use Decision Intelligence docs.

Implementation sequence

Use this path for the first technical review: prove the response shape publicly, request a production key, persist the decision record, then replay it when the action is questioned.

01 Run the sandbox

Confirm your action boundary returns the record shape your system can store before anything changes state.

Open playground

02 Request a production key

Production calls use x-api-key, monthly record tiers, quotas, telemetry, replay visibility, and a scoped action boundary.

Request access

03 Persist the record

Store the full Decision Record v1 object beside the downstream action.

Integration guides

04 Verify when challenged

Use the hosted verifier for exported records. Historical rulebook replay restores the immutable snapshot; current replay explicitly compares against current declared state.

Open verifier

Decision Record v1 API contract

The API is intentionally small: send decision context, receive a versioned decision record your system can store, replay, and attach to the action that follows.

Base URLhttps://www.decide.fyi

EndpointPOST /api/decide

Authx-api-key: $DECIDE_API_KEY

Versiondecision_record_v1

decision_record_version

Stable API contract label so callers can validate the response envelope.

verdict

Normalized yes, no, or review-style result for proceed, block, route, or escalate behavior.

application_verdict

Rulebook-defined business verdict such as APPROVE, DENY, or NEEDS_INPUT.

reason_code

Stable reason code from the matched rule or fail-closed validation path.

matched_rule_id

Stable identifier of the first matching rule after priority ordering.

rulebook

Rulebook schema version, id, version, and canonical hash used for the decision.

evaluator_version

Versioned evaluator that produced the binding rulebook result.

rulebook_contract

Runtime schema contract metadata: schema_url, schema_hash, schema version, and evaluator version.

runtime_binding

Production core and binding mode for the result: direct_declarative_rulebook or trusted_adapter_facts_then_declarative_rulebook, with declarative rulebook verdict authority and customer-supplied code rejected. Unsupported modes such as customer_executable_rulebook fail closed with RULEBOOK_BINDING_MODE_UNSUPPORTED. Caller-supplied output material fails closed with RULEBOOK_OUTPUT_MATERIAL_FORBIDDEN.

rulebook_registry

Immutable tenant-scoped snapshot metadata with a scope-bound attestation hash and Ed25519 signature when registry signing is configured. The stored rulebook body remains internal.

trusted_adapter

Exact adapter ID, version, implementation and manifest hashes, canonical input/output hashes, and the enforced one-shot worker execution contract.

adapter_facts

Schema-validated facts emitted by the pinned adapter before Rulebook v1 selects the binding outcome.

request_id

Short handle for logs, handoff, downstream metadata, and customer-facing traces.

decision_id

Stable ledger key used for lookup and replay.

policy_version

Declared rule or policy version used to produce the verdict.

idempotency_key

Caller retry or dedupe handle when supplied, mirrored into the stored record.

action_binding

Actor, system, resource, proposed action, subject, amount, or currency extracted from structured context.

evidence_manifest

Evidence codes plus source references when the caller or runtime provides them.

policy_bundle_hash

Hash of the policy bundle attestation, so reviewers can bind the record to the rule package used at decision time.

decision_confidence

Hashed confidence signal from caller-scoped Outcome Records, including score, level, similar decision count, and recommendation.

record_hash

Hash of the normalized Decision Record v1 envelope, including binding rulebook, registry, adapter, and adapter-fact lineage when present.

receipt_hash

Portable receipt hash over record_hash plus input, output, policy, action-binding, and evidence proof hashes.

receipt_signature

Optional HMAC or Ed25519 signature over the portable receipt when receipt signing is configured.

receipt_public_key_fingerprint

Fingerprint for Ed25519 public verification when the record can travel outside the caller's storage system.

replay_url

Replay endpoint for QA, disputes, rollout review, and verdict drift checks.

verify_url

Verification endpoint that recomputes the record and receipt hashes without rerunning upstream logic.

input_hash

Canonical request hash for dedupe and dispute review.

output_hash

Canonical response hash for audit and drift checks.

Response views

Every request creates the same canonical Decision Record v1 ledger entry. response_view only controls how much of that record the API returns to the caller.

View	Best for	Returned shape
`minimal`	Fast routing and agent/tool gates that only need proceed, block, or review.	`decision_id`, `request_id`, `verdict`, `application_verdict`, `reason_code`, `matched_rule_id`, rulebook lineage, `action`, hashes, signed receipt fields when configured, `verify_url`, `decision_url`, and `replay_url`.
`standard`	Production integrations that store the record beside a CRM, billing, queue, or workflow action.	Minimal fields plus evidence, policy fields, `policy_bundle`, `action_binding`, confidence details, input/output hashes, and creation timestamp.
`full` (default)	Audits, exports, replay labs, Krafthaus-style packet reviews, and integrations that want the full trust envelope immediately.	Standard fields plus `evidence_manifest`, `integrity`, and upstream response fields when available.

Body preference (AI-assisted legacy mode)

{
  "question": "Approve 15% annual-plan discount exception?",
  "mode": "single",
  "response_view": "minimal",
  "context": {
    "workflow": "pricing_exception",
    "source_record_id": "deal_1042",
    "requested_action": "approve_discount"
  }
}

Header preference

curl -i https://www.decide.fyi/api/decide \
  -H "content-type: application/json" \
  -H "x-api-key: $DECIDE_API_KEY" \
  -H "Prefer: return=standard" \
  -d @pricing_exception.json

Auth, limits, and safe defaults

The public playground is only for API-fit checks. Production traffic uses explicit keys, scoped rate limits, and fail-closed integration behavior for high-risk actions.

API key

Send x-api-key: $DECIDE_API_KEY on production requests. Do not expose the key in browser clients.

Rate limit

Starter default is 20 req/min per API key, surfaced through x-ratelimit-* headers.

Sandbox limit

Unauthenticated playground calls validate shape only and do not represent production quotas, telemetry, replay visibility, or retention.

Error behavior

For irreversible actions, fail closed, leave the source record in review, and retry only when your integration policy allows it.

Signed receipts

When HMAC or Ed25519 receipt signing is enabled, responses include receipt_signature and x-decision-receipt-signature for export-grade checks.

Storage rule

Persist the decision record before the caller proceeds, blocks, routes, or executes.

Review state

review is a first-class outcome, not a failure. Route it to the declared owner path.

Request API contract

Keep the payload small and explicit. The caller should describe the action boundary, pass structured context, and include caller-side identifiers when they exist.

Field or header	Required	Purpose
`question`	Legacy modes only	The decision boundary in plain language for AI-assisted `single`, `multi`, or `runtime` calls. Rulebook v1 calls may include it as descriptive metadata, but the binding production verdict comes from `rulebook` plus `context.inputs` or one trusted `adapter`.
`mode`	No	Use `rulebook` for deterministic binding verdicts. `single`, `multi`, and `runtime` remain AI-assisted legacy modes and are not the production determinism boundary. Omitted mode defaults to the advisory `single` path.
`rulebook`	Production binding	Rulebook v1 object with schema version, rulebook id, version, input schema, ordered declarative rules, and a default outcome. Customer executable rulebooks are rejected.
`binding_mode`	No	Optional explicit production binding: `direct_declarative_rulebook` or `trusted_adapter_facts_then_declarative_rulebook`.
`context`	No, but recommended	Workflow metadata plus `inputs` for Rulebook v1, or structured context for advisory legacy calls. Do not combine `context.inputs` with an `adapter` in one Rulebook request.
`response_view`	No	Optional response projection: `minimal`, `standard`, or `full`. It is stripped before the canonical input hash is computed.
`x-api-key`	Production only	Server-side production credential. Never expose it from browser clients.
`Prefer: return=...` / `x-decision-response-view`	No	Header alternative for choosing `minimal`, `standard`, or `full` without changing the JSON body.
`x-request-id`	No	Optional caller trace id. Store Decide's returned `request_id` even when you send your own.
`x-idempotency-key`	No	Optional retry handle. Same key plus same canonical payload replays the original record; same key plus a different payload returns `409`.

Store these fields with the action

The integration is valuable only if the decision record travels with the downstream action. Persist these fields in the system that proceeds, blocks, routes, or executes.

Field	Why it matters	Where it usually lands
`decision_record_version`	Validates the response shape your integration expects.	Decision record table, event schema, or typed integration object.
`request_id` / `decision_id`	Human-readable request handle plus stable lookup key for replay, dispute review, and evidence export.	CRM field, billing metadata, queue job, agent trace, or internal audit row.
`verdict` / `action`	Route the outcome without bespoke decision logic.	Approve / deny / review state in the calling system.
`evidence`	Explains the verdict with machine-readable checks.	Audit notes, evidence packet, decision trace, or operator memo.
`action_binding` / `idempotency_key`	Binds the verdict to the actor, system, resource, and proposed action that the caller was about to run.	Workflow metadata, CRM/billing custom fields, queue job metadata, or agent trace.
`evidence_manifest`	Separates verdict evidence codes from source references, snapshots, or retrieval metadata.	Evidence packet, audit export, or review console.
`policy_version` / `policy_bundle_hash` / `record_hash` / `receipt_hash`	Proves which declared rules produced the record and gives the record a portable tamper-evident receipt.	Immutable log row, event stream, or dispute packet.
`receipt_key_id` / `receipt_signature` / `receipt_public_key_fingerprint`	Lets an exported receipt be checked against an HMAC secret or Ed25519 public key without trusting the caller's storage system.	Dispute packet, external audit export, or customer-facing proof artifact.
`input_hash` / `output_hash` / `replay_url` / `verify_url`	Proves which payload and response created the action, then gives reviewers replay and tamper-check paths.	Immutable log row, event stream, or dispute packet.

Canonical proof run: pricing exception

The fastest way to understand Decide is one software action that should not happen without a recorded verdict.

Input Approve 15% annual-plan discount exception?

Context includes workflow, margin floor, owner rule, source key, and account segment.

Decision Return a rulebook-backed record

decision_record_version, verdict, request_id, decision_id, action_binding, policy_bundle_hash, record_hash, receipt_hash, verify_url, replay_url, and evidence are stored next to the workflow run.

Action Approve, review, or deny

The CRM, billing system, queue, or agent consumes the same API contract instead of reinventing decision logic.

For the complete sendable artifact, see /resources/live-proof.

Why this example uses pricing exceptions

The docs use pricing exceptions because the boundary is concrete: a business system wants to change CRM or billing state, but should first receive a recorded verdict. The same pattern applies to payouts, refunds, access changes, agent actions, routing, and internal approvals.

Concrete action

The caller can name exactly what will happen after the verdict.

System boundary

CRM, billing, and decision metadata already meet in one place.

Required proof

The full Decision Record v1 object must follow the action.

Owner

The workflow owner can define guardrails without replacing the whole process.

Expansion

The same API contract later applies to eligibility, routing, verification, and execution gates.

Limit

The public playground validates shape only; production keys add auth, quotas, telemetry, replay visibility, and retention controls.

Execution and outcome handling

Treat the verdict as a routing API contract. The API should make the next software action explicit, including when the correct answer is escalation. When the caller attempts the authorized mutation, record a target-system neutral decision_execution_v1 receipt at /api/decision/:id/execution. After the business result is known, report the result to /api/decision/:id/outcome.

Outcome	Caller behavior	Example action
`yes`	Proceed and persist the decision record with the action.	Approve the discount exception and attach `request_id` to CRM/billing metadata.
`no`	Block or deny, then expose the evidence checks to the operator or source system.	Deny a payout, refund, access change, or pricing exception.
`review`	Do not guess. Route to owner review or use a pre-declared review path.	Send the exception to RevOps when approve/review scores are equivalent.
`unknown` / missing evidence	Escalate and request more context before any irreversible action.	Hold billing update until owner, margin floor, or source evidence is present.
HTTP error	Fail closed for high-risk actions; retry only when your integration policy allows it.	Leave the source record in review state and log the failed request attempt.

Action Execution Receipt v1

curl -i https://www.decide.fyi/api/decision/dec_43b2/execution \
  -H "content-type: application/json" \
  -H "x-api-key: $DECIDE_API_KEY" \
  -H "x-idempotency-key: deal_1042_discount_15_execution" \
  -d '{
    "execution_status": "executed",
    "action_taken": "approve_discount",
    "target_system": "billing",
    "target_object_id": "sub_1042",
    "mutation": "discount.create",
    "execution_id": "billing_run_1042",
    "external_ref": "bill_1042",
    "decision_record_hash": "7f3a...",
    "decision_receipt_hash": "c91e...",
    "state_before_hash": "sha256:subscription_before_1042",
    "state_after_hash": "sha256:subscription_after_1042"
  }'

Execution fields to keep

{
  "decision_execution_version": "decision_execution_v1",
  "execution_receipt_id": "exec_71af...",
  "decision_id": "dec_43b2",
  "execution_status": "executed",
  "execution_hash": "f7a1...",
  "action_binding_hash": "2a40...",
  "action_binding_match": true,
  "state_before_hash": "sha256:subscription_before_1042",
  "state_after_hash": "sha256:subscription_after_1042",
  "reported_at": "2026-05-21T00:00:00.000Z"
}

Outcome Record v1

curl -i https://www.decide.fyi/api/decision/dec_43b2/outcome \
  -H "content-type: application/json" \
  -H "x-api-key: $DECIDE_API_KEY" \
  -H "x-idempotency-key: deal_1042_discount_15_outcome" \
  -d '{
    "outcome_status": "succeeded",
    "action_taken": "approve_discount",
    "action_executed": true,
    "target_system": "billing",
    "target_object_id": "sub_1042",
    "mutation": "discount.create",
    "external_ref": "bill_1042",
    "decision_record_hash": "7f3a...",
    "decision_receipt_hash": "c91e...",
    "observed_metrics": {
      "margin_after_discount": 0.182
    }
  }'

Outcome fields to keep

{
  "decision_outcome_version": "decision_outcome_v1",
  "outcome_id": "out_9a3c...",
  "decision_id": "dec_43b2",
  "outcome_status": "succeeded",
  "outcome_hash": "9d1a...",
  "outcome_input_hash": "4e1c...",
  "decision_record_hash": "7f3a...",
  "decision_receipt_hash": "c91e...",
  "reported_at": "2026-05-21T00:00:00.000Z"
}

Execution receipts are the core protocol proof that an authorized action was actually attempted. CRM sync, reference policy remotes, Krafthaus workflows, billing systems, queues, and agent tools are application layers that can all report the same execution shape. Once outcomes exist, new Decision Records include decision_confidence_v1: a hashed confidence signal with score, level, policy stability, similar decision count, and recommendation. GET /api/decision/policies/:policy_id/effectiveness returns scoped policy effectiveness metrics, GET /api/decision/policies/:policy_id/confidence returns a candidate verdict confidence baseline, GET /api/decision/policies/:policy_id/anomalies returns explainable anomaly reports, and GET /api/decision/policies/:policy_id/benchmarks returns opt-in anonymized cohort percentiles only after minimum privacy thresholds are met. POST /api/decision/:id/crm-sync records a hashed CRM write-back receipt when Decision Record fields are written to a CRM object.

Error API contract

For high-impact software actions, errors should never silently approve. Treat unavailable, unauthorized, and rate-limited calls as review or fail-closed states in the caller.

Status	Typical response	Caller behavior
`401` / `403`	`{"c":"unclear","v":"unauthorized","error":"DECIDE_API_UNAUTHORIZED"}`	Do not execute. Fix key scope, account status, or server-side auth before retrying.
`429`	`{"v":"rate_limited","retry_after":1}` or `{"v":"monthly_cap_exceeded"}`	Honor `Retry-After`. For irreversible actions, keep the source record in review until capacity is available.
`409`	`{"v":"idempotency_conflict","error":"DECIDE_API_IDEMPOTENCY_CONFLICT"}`	Do not execute. Reuse an idempotency key only with the same canonical payload, or create a new key for a new attempt.
`4xx`	Validation or malformed request error.	Do not retry blindly. Fix payload shape, missing fields, or unsupported mode.
`5xx` / upstream unavailable	Temporary runtime or upstream failure.	Retry with backoff only when your integration policy allows it; otherwise route to review.

Rate headersX-RateLimit-Limit

RemainingX-RateLimit-Remaining

Monthly capX-Usage-Monthly-Remaining

Decision handlex-decision-id

Receipt signaturex-decision-receipt-signature

Idempotencyx-idempotency-status

Open full error reference Review endpoint table

Decision API endpoints

These are the production endpoints required for the core integration. Reference applications are listed separately below so the API contract stays unambiguous.

For a compact endpoint-only page, use API reference.

Endpoint	Method	Purpose
`/api/decide`	POST	Return a Decision Record v1 object with `decision_id`, `request_id`, `runtime_binding`, `action_binding`, `policy_bundle_hash`, `source_hash`, `record_hash`, `receipt_hash`, `decision_confidence`, `replay_url`, `verify_url`, and runtime contract hashes. Use `response_view` or `Prefer: return=...` for minimal, standard, or full projections. Default guardrail is 20 req/min per API key and is surfaced via `x-ratelimit-*` headers.
`/api/decision/:id`	GET	Fetch a stored decision ledger entry by `decision_id`.
`/api/decision/:id/replay`	POST	Rulebook records default to tenant-scoped historical replay with the original canonical input, adapter invocation when present, and immutable snapshot. Adapter or evaluator lineage drift is rejected. Legacy records default to current replay.
`/api/decision/:id/diff`	POST	Replay/diff alias for rollout review, policy drift checks, and regression comparisons.
`/api/decision/:id/counterfactuals`	POST	Evaluate labeled simulation-only what-if scenarios and return `decision_counterfactuals_v1` with baseline-to-scenario verdict, action, policy version, and hash diffs.
`/api/decision/chains/:chain_id`	GET	Return `decision_chain_v1` head metadata, retained links, rolling Merkle root, and link verification for the caller-scoped cryptographic audit chain.
`/api/decision/:id/execution`	GET / POST	Record or list target-system neutral `decision_execution_v1` receipts after an authorized action is attempted. The response includes `execution_receipt_id`, `execution_hash`, execution status, target system/object, mutation, state hashes, `action_binding_hash`, and Decision Record hash links.
`/api/decision/:id/outcome`	GET / POST	Record or list Decision Outcome v1 records after the caller acts. The response includes `outcome_id`, `outcome_hash`, `outcome_input_hash`, execution references, observed metrics, and Decision Record hash links.
`/api/decision/:id/crm-sync`	GET / POST	Record or list Decision CRM Sync v1 receipts after a Decision Record is written to a CRM object. The response includes `sync_id`, `sync_hash`, CRM object references, mapped fields, and Decision Record hash links.
`/api/decision/:id/packet`	GET	Export `decision_packet_v1` with the Decision Record, optional input, execution receipts, Outcome Records, policy intelligence, audit-chain metadata, verification hints, and `packet_hash`.
`/api/decision/policies/:policy_id/effectiveness`	GET	Return `policy_effectiveness_v1` metrics derived from latest Outcome Records per decision in the caller's API-key scope, optionally filtered by `policy_version`.
`/api/decision/policies/:policy_id/confidence`	GET	Return `decision_confidence_v1` for a candidate verdict/action using latest Outcome Records per decision in the caller's API-key scope, optionally filtered by `policy_version`.
`/api/decision/policies/:policy_id/benchmarks`	GET	Return `decision_benchmark_v1` with caller metrics, anonymized opt-in cohort percentiles, comparison deltas, privacy thresholds, and `benchmark_hash` when the minimum cohort is met.
`/api/decision/policies/:policy_id/anomalies`	GET	Return `decision_anomaly_report_v1` with deterministic anomaly scores, reason codes, severity, baselines, and `anomaly_hash` from latest Outcome Records per decision.
`/api/decision/:id/verify`	GET / POST	Verify a stored or supplied Decision Record v1 by recomputing `record_hash`, including binding rulebook and adapter lineage, then checking `receipt_hash`, `policy_bundle_hash`, optional `receipt_signature`, and optional `input_hash`.
`/api/decision/verify`	GET / POST	Verify an exported Decision Record v1 packet directly from the request body, without depending on the hosted ledger.
`/api/decision/packet/verify`	GET / POST	Verify an exported Decision Packet v1 object, including `packet_hash`, embedded Decision Record verification, execution/outcome links, intelligence hashes, and retained chain links when present.
`/api/decision/receipt-keys`	GET	Return the active public Ed25519 receipt-verification key registry when portable public receipt signing is configured.
`/api/decision/policy-bundles`	GET	Return the active and historical policy bundle registry, including bundle hashes and source references.
`/api/decision/rulebooks`	GET	Resolve immutable scope-bound rulebook metadata, signed registry attestation when configured, and any bound trusted-adapter dependency. Listing and snapshot-body disclosure are unsupported.
`/api/decision/policy-patterns`	GET	Return first-party `decision_pattern_v1` templates for common workflows, including request, outcome, CRM sync, and SDK example hints.
`/api/decision/status`	GET	Return readiness for receipt signing, Rulebook v1 runtime contract metadata, policy bundle, rulebook and pattern registries, durable ledger, idempotency, auth, and backend wiring.

Offline verification

The verify endpoint is the online ledger check. For exported packets, the hosted verifier and repo verifier can recompute hashes and check receipt signatures without trusting the application that stored the record. The public key registry gives auditors a stable key source outside the record itself.

For the focused verification flow and diagrams, use Verification docs.

Hosted /verify

Paste or upload a Decision Record plus optional input and public key.

Best for buyer review and support packets.

API /api/decision/verify

POST an exported record from automation without depending on hosted ledger lookup.

Best for internal tools and audit workflows.

Packet /api/decision/packet/verify

Check packet hash, embedded record verification, execution, outcomes, intelligence, and retained chain links.

Best for complete proof exports.

CLI npx @decide-fyi/sdk verify

Run the same hash and signature checks in CI or from an exported artifact folder.

Best for release gates and conformance tests.

Hosted verifier

/verify accepts exported records, optional original input, optional public keys, and stored decision_id checks.

Policy bundle attestation

policy_bundle_hash binds the record to the bundle id, version, source, and canonicalized content hash.

Public verification

Ed25519 records carry a fingerprint and can be verified against /api/decision/receipt-keys or a supplied public key.

Private-key mode

HMAC signatures still work for internal systems that verify with DECIDE_RECEIPT_SIGNING_SECRET.

Decision Packet v1

/api/decision/:id/packet exports the portable proof bundle and /api/decision/packet/verify checks the packet hash plus embedded proof links.

Conformance fixtures

The SDK ships valid, tampered, and replay/diff fixtures so buyers can test verification without live API access.

Exported record check

npx @decide-fyi/sdk verify decision-record.json \
  --input decision-input.json \
  --key-registry https://www.decide.fyi/api/decision/receipt-keys \
  --json

Decision packet check

npx @decide-fyi/sdk verify-packet decision-packet.json \
  --key-registry https://www.decide.fyi/api/decision/receipt-keys \
  --summary

External public key

npx @decide-fyi/sdk verify decision-record.json \
  --input decision-input.json \
  --public-key decide-receipt-public.pem

Public key registry

curl -s https://www.decide.fyi/api/decision/receipt-keys

Verify in CI

npx @decide-fyi/sdk verify ./artifacts/decision-record.json \
  --input ./artifacts/decision-input.json \
  --key-registry https://www.decide.fyi/api/decision/receipt-keys \
  --json

Conformance fixture

npx @decide-fyi/sdk verify sdk/fixtures/valid-decision-record.json \
  --input sdk/fixtures/decision-input.json \
  --hmac-secret decide_conformance_hmac_secret_v1 \
  --json

Rulebook conformance runner

npx @decide-fyi/sdk rulebook-conformance \
  --index https://api.decide.fyi/conformance/rulebook-v1/index.json \
  --endpoint https://api.decide.fyi/api/decide \
  --summary

SDKs and libraries

The JavaScript package is published for server-side integrations, CLI verification, conformance fixtures, and copyable examples. Python examples use raw HTTPS requests today; there is no separate PyPI package advertised on this site yet.

Node/TypeScript SDK

Published npm latest: @decide-fyi/sdk@0.1.16. The package includes createDecideClient, decide, decisionPacket, recordExecution, recordOutcome, policy reports, counterfactuals, chains, offline verifier helpers, typed runtime binding metadata, the application-binding verifier, and the Rulebook v1 conformance runner.

Verifier CLI

npx @decide-fyi/sdk verify recomputes record hashes, receipt hashes, policy bundle hashes, and HMAC or Ed25519 receipt signatures. Add --application-binding to require decide_application_binding_v1 material before workflow-app handoff. npx @decide-fyi/sdk verify-packet checks Decision Packet v1 hashes and proof links. npx @decide-fyi/sdk rulebook-conformance runs the public Rulebook v1 fixture index against a target endpoint and validates semantic output, executable-payload rejection, rulebook_contract metadata, and repeat-run stability.

Packaged examples

Examples cover billing gates, webhook queues, agent actions, the lifecycle proof pack, execution receipts, outcome tracking, effectiveness, confidence, benchmarks, anomalies, chains, and counterfactuals.

Conformance fixtures

The package ships valid, tampered, input, replay/diff, and Rulebook v1 fixture-index tooling so buyers can test verification and endpoint conformance without live production access.

npm package npm registry metadata npm source tarball Public SDK notes GitHub source: access-controlled

Verified on June 12, 2026 against npm registry metadata: npm latest is 0.1.16 and the package tarball is reachable with published integrity data. npm package metadata declares git+https://github.com/nodeblur/decidesite.git with SDK source in /sdk; that GitHub repository is access-controlled, so public review should use the npm artifact or granted repository access.

Install

npm install @decide-fyi/sdk

Server-side call (AI-assisted legacy mode)

import { createDecideClient } from "@decide-fyi/sdk";

const decide = createDecideClient({ apiKey: process.env.DECIDE_API_KEY });
const record = await decide.decide({
  question: "Approve 15% annual-plan discount exception?",
  mode: "single",
  context: {
    workflow: "pricing_exception",
    source_record_id: "deal_1042",
    requested_action: "approve_discount"
  }
});

Application binding check

npx @decide-fyi/sdk verify app-record.json \
  --application-binding \
  --summary

import { verifyApplicationBinding } from "@decide-fyi/sdk";
const binding = verifyApplicationBinding(appRecord);

Reference applications

These public endpoints are source-backed applications built on the same recorded-decision pattern. They are useful proof assets, but they are not required for a core /api/decide integration. Hosted product examples built on Decide are linked in Reference assets.

Application	Endpoint	Purpose
Refund	`https://refund.decide.fyi/api/mcp`	MCP JSON-RPC for source-backed refund eligibility checks.
Refund record	`POST /api/v1/refund/eligibility?decision_record=1`	The same intake returned as Decision Record v1 with request-linked verification and historical replay.
Cancel	`https://cancel.decide.fyi/api/mcp`	MCP JSON-RPC for cancellation penalty checks.
Return	`https://return.decide.fyi/api/mcp`	MCP JSON-RPC for return eligibility checks.
Trial	`https://trial.decide.fyi/api/mcp`	MCP JSON-RPC for trial terms checks.

SDK-style examples

These compact examples show the legacy AI-assisted call shape. Use the Rulebook v1 quickstart above when the verdict must be deterministic and binding. Reference applications use the same decision record pattern when source-backed evidence is needed.

Node

const payload = {
  question: "Approve 15% annual-plan discount exception?",
  mode: "single",
  context: {
    workflow: "pricing_exception",
    source_record_id: "deal_1042",
    requested_action: "approve_discount",
    margin_floor: "passed",
    owner_rule: "verified"
  }
};

const res = await fetch("https://www.decide.fyi/api/decide", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": process.env.DECIDE_API_KEY,
    "x-idempotency-key": "deal_1042_discount_15"
  },
  body: JSON.stringify(payload)
});
const data = await res.json();
console.log(data.decision_record_version, data.verdict, data.decision_id, data.receipt_hash);

Python

import os
import requests

payload = {
    "question": "Approve 15% annual-plan discount exception?",
    "mode": "single",
    "context": {
        "workflow": "pricing_exception",
        "source_record_id": "deal_1042",
        "requested_action": "approve_discount",
        "margin_floor": "passed",
        "owner_rule": "verified"
    }
}

res = requests.post(
    "https://www.decide.fyi/api/decide",
    headers={
        "x-api-key": os.environ["DECIDE_API_KEY"],
        "x-idempotency-key": "deal_1042_discount_15",
    },
    json=payload,
    timeout=15,
)
data = res.json()
print(data.get("decision_record_version"), data.get("verdict"), data.get("decision_id"), data.get("receipt_hash"))

Deterministic replay and verify self-check

Run one Decision API call, verify the returned record hash and receipt hash, then replay the same decision_id. Rulebook records default to historical semantic reproduction from the immutable snapshot; the legacy lab below uses current-mode replay to inspect drift.

Question

Mode x-api-key (optional; required if auth is enabled)

No replay run yet.

Replay result

{
  "note": "Run replay check to populate."
}

Production cutover checklist

Use this sequence to move from API access to first live decision traffic without scope drift.

Window	Owner	Required output
Day 0-1	Workflow owner + Decide	Decision boundary selected, baseline KPI formulas frozen, escalation path confirmed.
Day 2-3	Platform/automation engineer	`/api/decide` wired into one macro/workflow with `request_id` persistence.
Day 4-5	Decision owner	Evidence payload contract validated on sample requests, exception classes reviewed.
Day 6-7	Ops owner + QA	First live-traffic readout, stored-record sample, replay checks, and audit evidence export confirmed.

Operational artifacts

Use these pages during security review and rollout planning. They support the API integration; they do not replace the core endpoint API contract.

Status

/resources/status shows runtime readiness, live endpoint checks, and public incident language.

Security

/resources/security documents transport, runtime controls, logging boundaries, and stated certification limits.

Integration guides

/resources/integrations shows how to place Decide in front of CRM, billing, automation, webhook, queue, and agent actions.

Developer examples

/resources/examples provides copyable cURL, JavaScript, Python, webhook, replay, and outcome-routing snippets.

Policy pattern catalog

/resources/patterns lists first-party Decision API templates for pricing exceptions, refund review, agent action gates, and CRM write-back gates.

Changelog

/resources/changelog records shipped API, docs, proof, pricing, and reliability surface updates.

Legal and commercial terms

/terms and /privacy cover public service and data handling terms. /resources/pilot-terms covers API access scope, billing, cancellation, and implementation boundaries.

FAQ

Short answers to common implementation blockers.

Is Decide only for pricing exceptions?

No. Pricing exceptions are the canonical proof run because the action boundary is easy to inspect. The API contract is general: send context, receive a recorded verdict, store the record with the action.

Are reference applications part of the core API?

No. Refund, cancellation, return, and trial endpoints are public proof applications. The core production integration is /api/decide, plus lookup and replay.

What should a caller do with review?

Treat review as a first-class outcome. Do not guess; route to the declared owner path and store the returned decision record.

Should API keys be used in browser clients?

No. Keep production keys server-side. Browser-visible playground calls are only for API-fit checks.

Can systems and AI agents share the same decision output?

Yes. Use one canonical Decision Record v1 API contract so both paths consume the same verdict, IDs, evidence, policy version, hashes, action, and replay URL.

Where should we start validation?

Use the playground to validate payload shape, then request API access and wire /api/decide into one production boundary before expanding.

Operational endpoints

These routes help with access, telemetry, exports, and payment lifecycle checks. They are operational support endpoints, not the core decision contract.

Route	Use	Readiness dependency
`/api/runtime-config`	Front-end runtime/commercial readiness config.	Payment links, booking URL, and access confirmation channel.
`/api/pilot`	API access request submission and confirmation trigger.	Webhook destination and confirmation provider config.
`/api/proof-metrics`	Access and activity snapshot used by authenticated proof views.	`x-metrics-token` for protected reads.
`/api/pilot-export`	CSV export for API access review and evidence packs.	Metrics token + proof metrics data availability.
`/api/stripe-webhook`	Stripe checkout lifecycle events (`checkout.session.*`) for payment-complete tracking.	`STRIPE_WEBHOOK_SIGNING_SECRET` in production.

Reference assets

Live proof artifact

/resources/live-proof shows the canonical pricing-exception request, response, replay artifact, downstream action, production handoff, and evaluation checklist.

Hosted application proof

Krafthaus is a hosted product layer built on Decide. It shows how Decision API records can power memo runs, packet reviews, policy-facing product pages, and execution-gate demos without becoming a dependency of the core API.

Machine-readable catalog

/docs.json contains endpoint, schema, and rate-limit metadata.

Vendor directory

/vendors and /vendors.json list supported vendors plus source links for reference applications.

Static source catalogs

/rules/policy-sources.json and category-specific variants list configured source URLs. Use /api/policy-alerts for live source-check freshness.

Reference source alerts

/resources/policy-alerts and /api/policy-alerts for scheduled source-page signal alerts with confidence labels.

Reference validation

Use the runtime examples, reference-alert feeds, and machine-readable specs on this page to validate payloads, responses, and replay behavior.

Security posture

Share /resources/security with procurement and security reviewers during access review.

Checkout return pages

Use /payment/success and /payment/cancel as Stripe post-checkout return destinations.