---
title: "Evaluate what-if scenarios for a stored decision"
method: POST
path: "/api/decision/{decision_id}/counterfactuals"
tags: ["Counterfactuals"]
---

# Evaluate what-if scenarios for a stored decision

`POST /api/decision/{decision_id}/counterfactuals`

## Request

- Base URL: `https://www.decide.fyi`
- URL: `https://www.decide.fyi/api/decision/{decision_id}/counterfactuals`
- Auth: API key in header `x-api-key`

Runs labeled simulation-only scenarios against the current Decision API runtime. Counterfactuals do not authorize downstream mutation; use the returned diffs for planning, rollout review, and policy tuning.

## Path parameters

- `decision_id` string, required

## Headers

- `x-decision-response-view` 'minimal' | 'standard' | 'full'

## Request body

- CounterfactualRequest
  - `base_input` union
    - object
      - `question` string, required
      - `mode` 'single' | 'multi' | 'runtime' | 'rulebook'
      - `prompt` string
      - `stem` string
      - `options` string[]
      - `context` union
        - object
        - string
      - `response_view` 'minimal' | 'standard' | 'full'
      - `rulebook` RulebookV1
        - `schema_version` 'rulebook_v1', required
        - `rulebook_id` string, required
        - `version` string, required
        - `input_schema` RulebookInputSchema
          - `required` string[]
          - `properties` object
        - `rules` RulebookRule[], required
          - `rule_id` string, required
          - `priority` integer
          - `condition` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `default_outcome` RulebookOutcome, required
          - `decision` 'yes' | 'no' | 'review', required
          - `verdict` string, required
          - `action` string, required
          - `reason_code` string, required
      - `adapter` TrustedAdapterInvocation
        - `adapter_id` string, required
        - `version` string, required
        - `manifest_hash` string, required
        - `input` object, required
    - object
      - `question` string
      - `mode` 'single' | 'multi' | 'runtime' | 'rulebook'
      - `prompt` string, required
      - `stem` string
      - `options` string[]
      - `context` union, required
        - object
        - string
      - `response_view` 'minimal' | 'standard' | 'full'
      - `rulebook` RulebookV1
        - `schema_version` 'rulebook_v1', required
        - `rulebook_id` string, required
        - `version` string, required
        - `input_schema` RulebookInputSchema
          - `required` string[]
          - `properties` object
        - `rules` RulebookRule[], required
          - `rule_id` string, required
          - `priority` integer
          - `condition` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `default_outcome` RulebookOutcome, required
          - `decision` 'yes' | 'no' | 'review', required
          - `verdict` string, required
          - `action` string, required
          - `reason_code` string, required
      - `adapter` TrustedAdapterInvocation
        - `adapter_id` string, required
        - `version` string, required
        - `manifest_hash` string, required
        - `input` object, required
    - object
      - `mode` 'rulebook', required
      - `question` string
      - `prompt` string
      - `stem` string
      - `options` string[]
      - `context` union, required
        - object
        - string
      - `response_view` 'minimal' | 'standard' | 'full'
      - `rulebook` RulebookV1, required
        - `schema_version` 'rulebook_v1', required
        - `rulebook_id` string, required
        - `version` string, required
        - `input_schema` RulebookInputSchema
          - `required` string[]
          - `properties` object
        - `rules` RulebookRule[], required
          - `rule_id` string, required
          - `priority` integer
          - `condition` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `default_outcome` RulebookOutcome, required
          - `decision` 'yes' | 'no' | 'review', required
          - `verdict` string, required
          - `action` string, required
          - `reason_code` string, required
      - `adapter` TrustedAdapterInvocation
        - `adapter_id` string, required
        - `version` string, required
        - `manifest_hash` string, required
        - `input` object, required
  - `input` union
    - object
      - `question` string, required
      - `mode` 'single' | 'multi' | 'runtime' | 'rulebook'
      - `prompt` string
      - `stem` string
      - `options` string[]
      - `context` union
        - object
        - string
      - `response_view` 'minimal' | 'standard' | 'full'
      - `rulebook` RulebookV1
        - `schema_version` 'rulebook_v1', required
        - `rulebook_id` string, required
        - `version` string, required
        - `input_schema` RulebookInputSchema
          - `required` string[]
          - `properties` object
        - `rules` RulebookRule[], required
          - `rule_id` string, required
          - `priority` integer
          - `condition` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `default_outcome` RulebookOutcome, required
          - `decision` 'yes' | 'no' | 'review', required
          - `verdict` string, required
          - `action` string, required
          - `reason_code` string, required
      - `adapter` TrustedAdapterInvocation
        - `adapter_id` string, required
        - `version` string, required
        - `manifest_hash` string, required
        - `input` object, required
    - object
      - `question` string
      - `mode` 'single' | 'multi' | 'runtime' | 'rulebook'
      - `prompt` string, required
      - `stem` string
      - `options` string[]
      - `context` union, required
        - object
        - string
      - `response_view` 'minimal' | 'standard' | 'full'
      - `rulebook` RulebookV1
        - `schema_version` 'rulebook_v1', required
        - `rulebook_id` string, required
        - `version` string, required
        - `input_schema` RulebookInputSchema
          - `required` string[]
          - `properties` object
        - `rules` RulebookRule[], required
          - `rule_id` string, required
          - `priority` integer
          - `condition` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `default_outcome` RulebookOutcome, required
          - `decision` 'yes' | 'no' | 'review', required
          - `verdict` string, required
          - `action` string, required
          - `reason_code` string, required
      - `adapter` TrustedAdapterInvocation
        - `adapter_id` string, required
        - `version` string, required
        - `manifest_hash` string, required
        - `input` object, required
    - object
      - `mode` 'rulebook', required
      - `question` string
      - `prompt` string
      - `stem` string
      - `options` string[]
      - `context` union, required
        - object
        - string
      - `response_view` 'minimal' | 'standard' | 'full'
      - `rulebook` RulebookV1, required
        - `schema_version` 'rulebook_v1', required
        - `rulebook_id` string, required
        - `version` string, required
        - `input_schema` RulebookInputSchema
          - `required` string[]
          - `properties` object
        - `rules` RulebookRule[], required
          - `rule_id` string, required
          - `priority` integer
          - `condition` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `default_outcome` RulebookOutcome, required
          - `decision` 'yes' | 'no' | 'review', required
          - `verdict` string, required
          - `action` string, required
          - `reason_code` string, required
      - `adapter` TrustedAdapterInvocation
        - `adapter_id` string, required
        - `version` string, required
        - `manifest_hash` string, required
        - `input` object, required
  - `response_view` 'minimal' | 'standard' | 'full'
  - `scenarios` CounterfactualScenario[], required
    - `scenario_id` string, required
    - `label` string
    - `description` string
    - `input` union
      - object
        - `question` string, required
        - `mode` 'single' | 'multi' | 'runtime' | 'rulebook'
        - `prompt` string
        - `stem` string
        - `options` string[]
        - `context` union
          - object
          - string
        - `response_view` 'minimal' | 'standard' | 'full'
        - `rulebook` RulebookV1
          - `schema_version` 'rulebook_v1', required
          - `rulebook_id` string, required
          - `version` string, required
          - `input_schema` RulebookInputSchema
            - `required` string[]
            - `properties` object
          - `rules` RulebookRule[], required
            - `rule_id` string, required
            - `priority` integer
            - `condition` union, required
              - …
            - `outcome` RulebookOutcome, required
              - …
          - `default_outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `adapter` TrustedAdapterInvocation
          - `adapter_id` string, required
          - `version` string, required
          - `manifest_hash` string, required
          - `input` object, required
      - object
        - `question` string
        - `mode` 'single' | 'multi' | 'runtime' | 'rulebook'
        - `prompt` string, required
        - `stem` string
        - `options` string[]
        - `context` union, required
          - object
          - string
        - `response_view` 'minimal' | 'standard' | 'full'
        - `rulebook` RulebookV1
          - `schema_version` 'rulebook_v1', required
          - `rulebook_id` string, required
          - `version` string, required
          - `input_schema` RulebookInputSchema
            - `required` string[]
            - `properties` object
          - `rules` RulebookRule[], required
            - `rule_id` string, required
            - `priority` integer
            - `condition` union, required
              - …
            - `outcome` RulebookOutcome, required
              - …
          - `default_outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `adapter` TrustedAdapterInvocation
          - `adapter_id` string, required
          - `version` string, required
          - `manifest_hash` string, required
          - `input` object, required
      - object
        - `mode` 'rulebook', required
        - `question` string
        - `prompt` string
        - `stem` string
        - `options` string[]
        - `context` union, required
          - object
          - string
        - `response_view` 'minimal' | 'standard' | 'full'
        - `rulebook` RulebookV1, required
          - `schema_version` 'rulebook_v1', required
          - `rulebook_id` string, required
          - `version` string, required
          - `input_schema` RulebookInputSchema
            - `required` string[]
            - `properties` object
          - `rules` RulebookRule[], required
            - `rule_id` string, required
            - `priority` integer
            - `condition` union, required
              - …
            - `outcome` RulebookOutcome, required
              - …
          - `default_outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `adapter` TrustedAdapterInvocation
          - `adapter_id` string, required
          - `version` string, required
          - `manifest_hash` string, required
          - `input` object, required
    - `request` union
      - object
        - `question` string, required
        - `mode` 'single' | 'multi' | 'runtime' | 'rulebook'
        - `prompt` string
        - `stem` string
        - `options` string[]
        - `context` union
          - object
          - string
        - `response_view` 'minimal' | 'standard' | 'full'
        - `rulebook` RulebookV1
          - `schema_version` 'rulebook_v1', required
          - `rulebook_id` string, required
          - `version` string, required
          - `input_schema` RulebookInputSchema
            - `required` string[]
            - `properties` object
          - `rules` RulebookRule[], required
            - `rule_id` string, required
            - `priority` integer
            - `condition` union, required
              - …
            - `outcome` RulebookOutcome, required
              - …
          - `default_outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `adapter` TrustedAdapterInvocation
          - `adapter_id` string, required
          - `version` string, required
          - `manifest_hash` string, required
          - `input` object, required
      - object
        - `question` string
        - `mode` 'single' | 'multi' | 'runtime' | 'rulebook'
        - `prompt` string, required
        - `stem` string
        - `options` string[]
        - `context` union, required
          - object
          - string
        - `response_view` 'minimal' | 'standard' | 'full'
        - `rulebook` RulebookV1
          - `schema_version` 'rulebook_v1', required
          - `rulebook_id` string, required
          - `version` string, required
          - `input_schema` RulebookInputSchema
            - `required` string[]
            - `properties` object
          - `rules` RulebookRule[], required
            - `rule_id` string, required
            - `priority` integer
            - `condition` union, required
              - …
            - `outcome` RulebookOutcome, required
              - …
          - `default_outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `adapter` TrustedAdapterInvocation
          - `adapter_id` string, required
          - `version` string, required
          - `manifest_hash` string, required
          - `input` object, required
      - object
        - `mode` 'rulebook', required
        - `question` string
        - `prompt` string
        - `stem` string
        - `options` string[]
        - `context` union, required
          - object
          - string
        - `response_view` 'minimal' | 'standard' | 'full'
        - `rulebook` RulebookV1, required
          - `schema_version` 'rulebook_v1', required
          - `rulebook_id` string, required
          - `version` string, required
          - `input_schema` RulebookInputSchema
            - `required` string[]
            - `properties` object
          - `rules` RulebookRule[], required
            - `rule_id` string, required
            - `priority` integer
            - `condition` union, required
              - …
            - `outcome` RulebookOutcome, required
              - …
          - `default_outcome` RulebookOutcome, required
            - `decision` 'yes' | 'no' | 'review', required
            - `verdict` string, required
            - `action` string, required
            - `reason_code` string, required
        - `adapter` TrustedAdapterInvocation
          - `adapter_id` string, required
          - `version` string, required
          - `manifest_hash` string, required
          - `input` object, required
    - `patch` object
    - `context_patch` object
    - `question` string
    - `mode` string

## Response `200`

Counterfactual report

- DecisionCounterfactualsResult
  - `ok` boolean, required
  - `decision_counterfactuals_version` 'decision_counterfactuals_v1', required
  - `generated_at` string
  - `source_decision_id` string, required
  - `simulation_only` true, required
  - `baseline` object, required
  - `scenario_count` integer
  - `evaluated_count` integer
  - `changed_count` integer
  - `scenarios` object[], required
    - `scenario_id` string
    - `label` string
    - `status` 'evaluated' | 'failed'
    - `simulation_only` boolean
    - `changed` boolean
    - `verdict` string
    - `action` string
    - `input_hash` string
    - `output_hash` string
    - `record_hash` string
    - `receipt_hash` string
    - `diff` object
    - `decision` DecisionRecord
      - `decision_protocol_version` 'decision_protocol_v1', required
      - `decision_record_version` 'decision_record_v1', required
      - `response_view` 'minimal' | 'standard' | 'full'
      - `decision_id` string, required
      - `request_id` string, required
      - `idempotency_key` string
      - `c` string
      - `v` string
      - `verdict` string, required
      - `application_verdict` string: Purpose-specific bounded verdict produced by Rulebook v1, such as APPROVE, BLOCK, REVIEW, or NEEDS_INPUT.
      - `evaluator_version` string: Versioned evaluator that produced the binding rulebook result.
      - `rulebook_contract` RulebookContract
        - `schema_version` 'rulebook_v1', required
        - `schema_url` 'https://api.decide.fyi/schemas/rulebook-v1.schema.json', required
        - `schema_hash` string, required: SHA-256 hash of the published Rulebook v1 JSON Schema enforced by the runtime.
        - `evaluator_version` 'decide_rulebook_v1', required
      - `action` string
      - `reason_code` string
      - `matched_rule_id` string, nullable
      - `rulebook` object
        - `schema_version` 'rulebook_v1'
        - `id` string
        - `version` string
        - `hash` string
      - `rulebook_registry` RulebookRegistryMetadata
        - `rulebook_registry_version` 'decision_rulebook_registry_v1', required
        - `schema_version` 'rulebook_v1', required
        - `rulebook_id` string, required
        - `version` string, required
        - `hash` string, required
        - `evaluator_version` string, required
        - `trusted_adapter` TrustedAdapterDependency
          - `manifest_version` 'trusted_adapter_manifest_v1', required
          - `adapter_id` string, required
          - `version` string, required
          - `implementation_revision` string, required
          - `implementation_hash` string, required
          - `manifest_hash` string, required
        - `hash_algorithm` 'sha256', required
        - `canonicalization` 'json.sort_deep.v1', required
        - `scope_hash` string, required
        - `registry_attestation` RegistryAttestation, required
          - `registry_attestation_version` 'decision_registry_attestation_v1', required
          - `status` 'signed' | 'unsigned', required
          - `attestation_hash` string, required
          - `key_id` string
          - `signature_algorithm` 'ed25519'
          - `signature` string
          - `public_key` string
          - `public_key_fingerprint` string
        - `registered_at` string, date-time, required
      - `runtime_binding` RuntimeBinding
        - `production_core` 'hybrid_declarative_rulebook_with_trusted_adapters', required
        - `binding_mode` 'direct_declarative_rulebook' | 'trusted_adapter_facts_then_declarative_rulebook', required
        - `verdict_authority` 'declarative_rulebook', required
        - `adapter_authority` 'facts_only'
        - `customer_supplied_code` 'rejected', required
      - `trusted_adapter` TrustedAdapterAttestation
        - `manifest_version` 'trusted_adapter_manifest_v1', required
        - `adapter_id` string, required
        - `version` string, required
        - `implementation_revision` string, required
        - `implementation_hash` string, required
        - `manifest_hash` string, required
        - `input_hash` string, required
        - `output_hash` string, required
        - `execution_isolation` 'worker_thread_one_shot_v1', required
        - `capability_enforcement` 'ambient_capability_deny_v2', required
        - `execution_timeout_ms` integer, required
      - `adapter_facts` object: Schema-validated facts emitted by the pinned trusted adapter before Rulebook v1 evaluation.
      - `action_binding` ActionBinding
        - `actor` string
        - `system` string
        - `resource` string
        - `proposed_action` string
        - `subject` string
        - `amount` string
        - `currency` string
        - `target_system` string
        - `target_object_id` string
        - `mutation` string
        - `expires_at` string
        - `execution_state` string
        - `execution_id` string
      - `evidence` string[]
      - `evidence_manifest` EvidenceManifest
        - `codes` string[]
        - `sources` EvidenceSource[]
          - `id` string
          - `type` string
          - `vendor` string
          - `title` string
          - `url` string
          - `policy_ref` string
          - `observed_at` string
          - `retrieval_id` string
          - `hash` string
          - `snapshot_hash` string
          - `content_hash` string
          - `version` string
      - `policy_id` string
      - `policy_version` string
      - `policy_hash` string
      - `source_hash` string: Backend lineage hash returned in the full Decision Record response when the upstream decision engine supplies it.
      - `policy_bundle` PolicyBundle
        - `id` string
        - `version` string
        - `hash` string
        - `hash_algorithm` string
        - `canonicalization` string
        - `source` string
        - `status` string
        - `effective_at` string
        - `deprecated_at` string
        - `changelog` string
        - `content_hash` string
      - `policy_bundle_hash` string
      - `confidence` DecisionConfidence
        - `ok` boolean, required
        - `decision_confidence_version` 'decision_confidence_v1', required
        - `generated_at` string
        - `source` 'decision_outcomes'
        - `scope` 'caller_api_key'
        - `decision_id` string, nullable
        - `policy_id` string, nullable
        - `policy_version` string, nullable
        - `verdict` string
        - `action` string, nullable
        - `score` number, required
        - `level` 'high' | 'medium' | 'low' | 'weak' | 'insufficient_data', required
        - `based_on` integer
        - `similar_decisions` integer
        - `policy_stability` 'high' | 'medium' | 'low' | 'insufficient_data'
        - `recommendation` 'collect_more_outcomes' | 'high_confidence_proceed' | 'high_confidence_block' | 'high_confidence_review' | 'proceed_with_monitoring' | 'route_for_review' | 'monitor', required
        - `metrics` object
        - `baseline` object
        - `data_quality` object
        - `reasons` object[]
        - `confidence_hash` string, required
      - `decision_confidence` DecisionConfidence
        - `ok` boolean, required
        - `decision_confidence_version` 'decision_confidence_v1', required
        - `generated_at` string
        - `source` 'decision_outcomes'
        - `scope` 'caller_api_key'
        - `decision_id` string, nullable
        - `policy_id` string, nullable
        - `policy_version` string, nullable
        - `verdict` string
        - `action` string, nullable
        - `score` number, required
        - `level` 'high' | 'medium' | 'low' | 'weak' | 'insufficient_data', required
        - `based_on` integer
        - `similar_decisions` integer
        - `policy_stability` 'high' | 'medium' | 'low' | 'insufficient_data'
        - `recommendation` 'collect_more_outcomes' | 'high_confidence_proceed' | 'high_confidence_block' | 'high_confidence_review' | 'proceed_with_monitoring' | 'route_for_review' | 'monitor', required
        - `metrics` object
        - `baseline` object
        - `data_quality` object
        - `reasons` object[]
        - `confidence_hash` string, required
      - `confidence_hash` string
      - `input_hash` string
      - `output_hash` string
      - `record_hash` string, required: Tamper-evident hash of the normalized Decision Record v1 envelope, including binding application verdict, reason, matched rule, rulebook lineage, registry attestation, trusted adapter attestation, and adapter facts when present.
      - `receipt_hash` string, required: Portable receipt hash over record_hash plus input/output, policy, action-binding, and evidence-manifest proof hashes.
      - `receipt_key_id` string
      - `receipt_signature` string
      - `receipt_signature_algorithm` 'hmac-sha256' | 'ed25519'
      - `receipt_public_key` string
      - `receipt_public_key_fingerprint` string
      - `integrity` Integrity
        - `canonicalization` string
        - `decision_protocol_version` string
        - `hash_algorithm` string
        - `input_hash` string
        - `output_hash` string
        - `policy_hash` string
        - `policy_bundle_hash` string
        - `record_hash` string
        - `receipt_hash` string
        - `replay_url` string
        - `verify_url` string
        - `signature` object
      - `verify_url` string, required
      - `replay_url` string, required
      - `created_at` string
      - `audit_chain` AuditChain
        - `decision_chain_version` 'decision_chain_v1', required
        - `chain_id` string, required
        - `chain_position` integer, required
        - `previous_link_hash` string, nullable
        - `leaf_hash` string, required
        - `merkle_root` string, required
        - `merkle_strategy` 'rolling_sha256_pair_v1'
        - `link_hash` string, required
        - `chain_url` string
        - `created_at` string
        - `entry_type` string
      - `chain_url` string
    - `scenario_hash` string
  - `data_quality` object
  - `counterfactual_hash` string, required

## Other responses

- `400`: Missing or invalid scenarios
- `401`: API key missing, invalid, inactive, or unauthorized
- `404`: Decision not found in the authenticated caller scope
- `422`: Base input unavailable

---

[API](https://skmtc.dev/decide/apis/decide-decision-api.md) · [All operations](https://skmtc.dev/decide/apis/decide-decision-api/llms.txt) · [OpenAPI document](https://skmtc.dev/decide/apis/decide-decision-api/revisions/caf1d3069dfd?raw)