decide-fyi Counterfactuals API
Simulation-only what-if analysis for stored Decision Records.
Simulation-only what-if analysis for stored Decision Records.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/decide-fyi:decide-fyi-counterfactuals-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Decide Decision Counterfactuals API
summary: Decision protocol for state-changing software actions.
description: Call Decide before products, agents, queues, billing systems, CRMs, or internal tools change state. The API returns a signed Decision Record v1 object with policy bundle attestation, evidence, action binding, replay, verification handles, portable Decision Packet v1 exports, simulation-only counterfactual analysis, cryptographic audit chains, Action Execution Receipts, Outcome Records, CRM Sync Records, predictive confidence, first-party policy pattern templates, policy effectiveness metrics, opt-in anonymized benchmarks, and explainable anomaly reports derived from reported outcomes.
version: 1.13.0
x-decision-protocol-version: decision_protocol_v1
x-decision-record-version: decision_record_v1
x-decision-packet-version: decision_packet_v1
servers:
- url: https://www.decide.fyi
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Counterfactuals
description: Simulation-only what-if analysis for stored Decision Records.
paths:
/api/decision/{decision_id}/counterfactuals:
post:
tags:
- Counterfactuals
operationId: createDecisionCounterfactuals
summary: Evaluate what-if scenarios for a stored decision
description: 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.
parameters:
- $ref: '#/components/parameters/DecisionId'
- $ref: '#/components/parameters/DecisionResponseView'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CounterfactualRequest'
examples:
pricingDiscountScenarios:
summary: Compare discount levels
value:
response_view: standard
scenarios:
- scenario_id: discount_10_percent
label: 10% discount
context_patch:
discount_percent: 10
- scenario_id: discount_25_percent
label: 25% discount
context_patch:
discount_percent: 25
margin_floor: review_required
responses:
'200':
description: Counterfactual report
headers:
x-decision-counterfactuals-version:
schema:
type: string
const: decision_counterfactuals_v1
x-decision-counterfactual-hash:
schema:
type: string
x-decision-counterfactual-scenarios:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/DecisionCounterfactualsResult'
'400':
description: Missing or invalid scenarios
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Decision not found in the authenticated caller scope
'422':
description: Base input unavailable
components:
schemas:
RuntimeBinding:
type: object
required:
- production_core
- binding_mode
- verdict_authority
- customer_supplied_code
properties:
production_core:
type: string
const: hybrid_declarative_rulebook_with_trusted_adapters
binding_mode:
type: string
enum:
- direct_declarative_rulebook
- trusted_adapter_facts_then_declarative_rulebook
verdict_authority:
type: string
const: declarative_rulebook
adapter_authority:
type: string
const: facts_only
customer_supplied_code:
type: string
const: rejected
additionalProperties: false
TrustedAdapterAttestation:
type: object
required:
- manifest_version
- adapter_id
- version
- implementation_revision
- implementation_hash
- manifest_hash
- input_hash
- output_hash
- execution_isolation
- capability_enforcement
- execution_timeout_ms
properties:
manifest_version:
type: string
const: trusted_adapter_manifest_v1
adapter_id:
type: string
version:
type: string
implementation_revision:
type: string
implementation_hash:
type: string
pattern: ^[a-f0-9]{64}$
manifest_hash:
type: string
pattern: ^[a-f0-9]{64}$
input_hash:
type: string
pattern: ^[a-f0-9]{64}$
output_hash:
type: string
pattern: ^[a-f0-9]{64}$
execution_isolation:
type: string
const: worker_thread_one_shot_v1
capability_enforcement:
type: string
const: ambient_capability_deny_v2
execution_timeout_ms:
type: integer
minimum: 1
additionalProperties: false
DecisionCounterfactualsResult:
type: object
required:
- ok
- decision_counterfactuals_version
- source_decision_id
- simulation_only
- baseline
- scenarios
- counterfactual_hash
properties:
ok:
type: boolean
decision_counterfactuals_version:
type: string
const: decision_counterfactuals_v1
generated_at:
type: string
source_decision_id:
type: string
simulation_only:
type: boolean
const: true
baseline:
type: object
additionalProperties: true
scenario_count:
type: integer
evaluated_count:
type: integer
changed_count:
type: integer
scenarios:
type: array
items:
type: object
properties:
scenario_id:
type: string
label:
type: string
status:
type: string
enum:
- evaluated
- failed
simulation_only:
type: boolean
changed:
type: boolean
verdict:
type: string
action:
type: string
input_hash:
type: string
output_hash:
type: string
record_hash:
type: string
receipt_hash:
type: string
diff:
type: object
additionalProperties: true
decision:
$ref: '#/components/schemas/DecisionRecord'
scenario_hash:
type: string
additionalProperties: true
data_quality:
type: object
additionalProperties: true
counterfactual_hash:
type: string
additionalProperties: true
RulebookRegistryMetadata:
type: object
required:
- rulebook_registry_version
- schema_version
- rulebook_id
- version
- hash
- evaluator_version
- hash_algorithm
- canonicalization
- scope_hash
- registry_attestation
- registered_at
properties:
rulebook_registry_version:
type: string
const: decision_rulebook_registry_v1
schema_version:
type: string
const: rulebook_v1
rulebook_id:
type: string
version:
type: string
hash:
type: string
minLength: 64
maxLength: 64
evaluator_version:
type: string
trusted_adapter:
$ref: '#/components/schemas/TrustedAdapterDependency'
hash_algorithm:
type: string
const: sha256
canonicalization:
type: string
const: json.sort_deep.v1
scope_hash:
type: string
pattern: ^[a-f0-9]{64}$
registry_attestation:
$ref: '#/components/schemas/RegistryAttestation'
registered_at:
type: string
format: date-time
additionalProperties: false
RulebookOutcome:
type: object
required:
- decision
- verdict
- action
- reason_code
properties:
decision:
type: string
enum:
- 'yes'
- 'no'
- review
verdict:
type: string
pattern: ^[A-Z][A-Z0-9_]{1,79}$
action:
type: string
minLength: 1
maxLength: 160
reason_code:
type: string
pattern: ^[A-Z][A-Z0-9_]{1,79}$
additionalProperties: false
CounterfactualRequest:
type: object
required:
- scenarios
properties:
base_input:
$ref: '#/components/schemas/DecisionRequest'
input:
$ref: '#/components/schemas/DecisionRequest'
response_view:
type: string
enum:
- minimal
- standard
- full
scenarios:
type: array
minItems: 1
maxItems: 8
items:
$ref: '#/components/schemas/CounterfactualScenario'
additionalProperties: true
PolicyBundle:
type: object
properties:
id:
type: string
version:
type: string
hash:
type: string
hash_algorithm:
type: string
default: sha256
canonicalization:
type: string
default: json.sort_deep.v1
source:
type: string
status:
type: string
effective_at:
type: string
deprecated_at:
type: string
changelog:
type: string
content_hash:
type: string
additionalProperties: true
DecisionRecord:
type: object
required:
- decision_protocol_version
- decision_record_version
- decision_id
- request_id
- verdict
- record_hash
- receipt_hash
- verify_url
- replay_url
properties:
decision_protocol_version:
type: string
const: decision_protocol_v1
decision_record_version:
type: string
const: decision_record_v1
response_view:
type: string
enum:
- minimal
- standard
- full
decision_id:
type: string
maxLength: 600
request_id:
type: string
idempotency_key:
type: string
c:
type: string
v:
type: string
verdict:
type: string
application_verdict:
type: string
description: Purpose-specific bounded verdict produced by Rulebook v1, such as APPROVE, BLOCK, REVIEW, or NEEDS_INPUT.
evaluator_version:
type: string
description: Versioned evaluator that produced the binding rulebook result.
rulebook_contract:
$ref: '#/components/schemas/RulebookContract'
action:
type: string
reason_code:
type: string
matched_rule_id:
type:
- string
- 'null'
rulebook:
type: object
properties:
schema_version:
type: string
const: rulebook_v1
id:
type: string
version:
type: string
hash:
type: string
additionalProperties: true
rulebook_registry:
$ref: '#/components/schemas/RulebookRegistryMetadata'
runtime_binding:
$ref: '#/components/schemas/RuntimeBinding'
trusted_adapter:
$ref: '#/components/schemas/TrustedAdapterAttestation'
adapter_facts:
type: object
description: Schema-validated facts emitted by the pinned trusted adapter before Rulebook v1 evaluation.
additionalProperties: true
action_binding:
$ref: '#/components/schemas/ActionBinding'
evidence:
type: array
items:
type: string
evidence_manifest:
$ref: '#/components/schemas/EvidenceManifest'
policy_id:
type: string
policy_version:
type: string
policy_hash:
type: string
source_hash:
type: string
description: Backend lineage hash returned in the full Decision Record response when the upstream decision engine supplies it.
policy_bundle:
$ref: '#/components/schemas/PolicyBundle'
policy_bundle_hash:
type: string
confidence:
$ref: '#/components/schemas/DecisionConfidence'
decision_confidence:
$ref: '#/components/schemas/DecisionConfidence'
confidence_hash:
type: string
input_hash:
type: string
output_hash:
type: string
record_hash:
type: string
description: 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:
type: string
description: Portable receipt hash over record_hash plus input/output, policy, action-binding, and evidence-manifest proof hashes.
receipt_key_id:
type: string
receipt_signature:
type: string
receipt_signature_algorithm:
type: string
enum:
- hmac-sha256
- ed25519
receipt_public_key:
type: string
receipt_public_key_fingerprint:
type: string
integrity:
$ref: '#/components/schemas/Integrity'
verify_url:
type: string
replay_url:
type: string
created_at:
type: string
audit_chain:
$ref: '#/components/schemas/AuditChain'
chain_url:
type: string
additionalProperties: true
DecisionConfidence:
type: object
required:
- ok
- decision_confidence_version
- score
- level
- recommendation
- confidence_hash
properties:
ok:
type: boolean
decision_confidence_version:
type: string
const: decision_confidence_v1
generated_at:
type: string
source:
type: string
const: decision_outcomes
scope:
type: string
const: caller_api_key
decision_id:
type:
- string
- 'null'
policy_id:
type:
- string
- 'null'
policy_version:
type:
- string
- 'null'
verdict:
type: string
action:
type:
- string
- 'null'
score:
type: number
minimum: 0
maximum: 1
level:
type: string
enum:
- high
- medium
- low
- weak
- insufficient_data
based_on:
type: integer
similar_decisions:
type: integer
policy_stability:
type: string
enum:
- high
- medium
- low
- insufficient_data
recommendation:
type: string
enum:
- collect_more_outcomes
- high_confidence_proceed
- high_confidence_block
- high_confidence_review
- proceed_with_monitoring
- route_for_review
- monitor
metrics:
type: object
additionalProperties: true
baseline:
type: object
additionalProperties: true
data_quality:
type: object
additionalProperties: true
reasons:
type: array
items:
type: object
additionalProperties: true
confidence_hash:
type: string
additionalProperties: true
AuditChain:
type: object
required:
- decision_chain_version
- chain_id
- chain_position
- leaf_hash
- merkle_root
- link_hash
properties:
decision_chain_version:
type: string
const: decision_chain_v1
chain_id:
type: string
chain_position:
type: integer
previous_link_hash:
type:
- string
- 'null'
leaf_hash:
type: string
merkle_root:
type: string
merkle_strategy:
type: string
const: rolling_sha256_pair_v1
link_hash:
type: string
chain_url:
type: string
created_at:
type: string
entry_type:
type: string
additionalProperties: true
RulebookRule:
type: object
required:
- rule_id
- condition
- outcome
properties:
rule_id:
type: string
pattern: ^[a-z][a-z0-9_.:-]{1,119}$
priority:
type: integer
minimum: -1000
maximum: 1000
default: 0
condition:
$ref: '#/components/schemas/RulebookCondition'
outcome:
$ref: '#/components/schemas/RulebookOutcome'
additionalProperties: false
RulebookCondition:
oneOf:
- type: object
required:
- all
properties:
all:
type: array
minItems: 1
maxItems: 32
items:
$ref: '#/components/schemas/RulebookCondition'
additionalProperties: false
- type: object
required:
- any
properties:
any:
type: array
minItems: 1
maxItems: 32
items:
$ref: '#/components/schemas/RulebookCondition'
additionalProperties: false
- type: object
required:
- not
properties:
not:
$ref: '#/components/schemas/RulebookCondition'
additionalProperties: false
- type: object
required:
- field
- operator
properties:
field:
type: string
pattern: ^[A-Za-z_][A-Za-z0-9_.-]{0,159}$
operator:
type: string
enum:
- exists
- not_exists
- eq
- neq
- gt
- gte
- lt
- lte
- in
- not_in
- contains
- not_contains
value: {}
additionalProperties: false
RegistryAttestation:
type: object
required:
- registry_attestation_version
- status
- attestation_hash
properties:
registry_attestation_version:
type: string
const: decision_registry_attestation_v1
status:
type: string
enum:
- signed
- unsigned
attestation_hash:
type: string
pattern: ^[a-f0-9]{64}$
key_id:
type: string
signature_algorithm:
type: string
const: ed25519
signature:
type: string
pattern: '^ed25519:'
public_key:
type: string
public_key_fingerprint:
type: string
pattern: ^[a-f0-9]{64}$
additionalProperties: false
CounterfactualScenario:
type: object
required:
- scenario_id
properties:
scenario_id:
type: string
label:
type: string
description:
type: string
input:
$ref: '#/components/schemas/DecisionRequest'
request:
$ref: '#/components/schemas/DecisionRequest'
patch:
type: object
additionalProperties: true
context_patch:
type: object
additionalProperties: true
question:
type: string
mode:
type: string
additionalProperties: true
TrustedAdapterDependency:
type: object
required:
- manifest_version
- adapter_id
- version
- implementation_revision
- implementation_hash
- manifest_hash
properties:
manifest_version:
type: string
const: trusted_adapter_manifest_v1
adapter_id:
type: string
version:
type: string
implementation_revision:
type: string
implementation_hash:
type: string
pattern: ^[a-f0-9]{64}$
manifest_hash:
type: string
pattern: ^[a-f0-9]{64}$
additionalProperties: false
RulebookContract:
type: object
required:
- schema_version
- schema_url
- schema_hash
- evaluator_version
properties:
schema_version:
type: string
const: rulebook_v1
schema_url:
type: string
const: https://api.decide.fyi/schemas/rulebook-v1.schema.json
schema_hash:
type: string
pattern: ^[a-f0-9]{64}$
description: SHA-256 hash of the published Rulebook v1 JSON Schema enforced by the runtime.
evaluator_version:
type: string
const: decide_rulebook_v1
additionalProperties: false
Integrity:
type: object
properties:
canonicalization:
type: string
decision_protocol_version:
type: string
hash_algorithm:
type: string
input_hash:
type: string
output_hash:
type: string
policy_hash:
type: string
policy_bundle_hash:
type: string
record_hash:
type: string
receipt_hash:
type: string
replay_url:
type: string
verify_url:
type: string
signature:
type: object
additionalProperties: true
additionalProperties: true
DecisionRequest:
type: object
anyOf:
- required:
- question
- required:
- prompt
- context
- required:
- mode
- rulebook
- context
properties:
mode:
const: rulebook
properties:
question:
type: string
mode:
type: string
enum:
- single
- multi
- runtime
- rulebook
prompt:
type: string
stem:
type: string
options:
type: array
minItems: 2
maxItems: 8
items:
type: string
context:
type:
- object
- string
additionalProperties: true
response_view:
type: string
enum:
- minimal
- standard
- full
rulebook:
$ref: '#/components/schemas/RulebookV1'
adapter:
$ref: '#/components/schemas/TrustedAdapterInvocation'
additionalProperties: false
TrustedAdapterInvocation:
type: object
required:
- adapter_id
- version
- manifest_hash
- input
properties:
adapter_id:
type: string
pattern: ^[a-z][a-z0-9_.:-]{1,119}$
version:
type: string
pattern: ^[0-9]+\.[0-9]+\.[0-9]+$
manifest_hash:
type: string
pattern: ^[a-f0-9]{64}$
input:
type: object
additionalProperties: true
additionalProperties: false
ActionBinding:
type: object
properties:
actor:
type: string
system:
type: string
resource:
type: string
proposed_action:
type: string
subject:
type: string
amount:
type: string
currency:
type: string
target_system:
type: string
target_object_id:
type: string
mutation:
type: string
expires_at:
type: string
execution_state:
type: string
execution_id:
type: string
additionalProperties: true
EvidenceSource:
type: object
properties:
id:
type: string
type:
type: string
vendor:
type: string
title:
type: string
url:
type: string
policy_ref:
type: string
observed_at:
type: string
retrieval_id:
type: string
hash:
type: string
snapshot_hash:
type: string
content_hash:
type: string
version:
type: string
additionalProperties: true
RulebookInputSchema:
type: object
properties:
required:
type: array
items:
type: string
pattern: ^[A-Za-z_][A-Za-z0-9_.-]{0,159}$
properties:
type: object
additionalProperties:
type: object
required:
- type
properties:
type:
type: string
enum:
- string
- number
- integer
- boolean
- array
- object
- 'null'
additionalProperties: false
additionalProperties: false
ErrorResponse:
type: object
properties:
c:
type: string
v:
type: string
request_id:
type: string
error:
type: string
message:
type: string
additionalProperties: true
RulebookV1:
type: object
required:
- schema_version
- rulebook_id
- version
- rules
- default_outcome
properties:
schema_version:
type: string
const: rulebook_v1
rulebook_id:
type: string
pattern: ^[a-z][a-z0-9_.:-]{1,119}$
version:
type: string
minLength: 1
maxLength: 80
input_schema:
$ref: '#/components/schemas/RulebookInputSchema'
rules:
type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/RulebookRule'
default_outcome:
$ref: '#/components/schemas/RulebookOutcome'
additionalProperties: false
EvidenceManifest:
type: object
properties:
codes:
type: array
items:
type: string
sources:
type: array
items:
$ref: '#/components/schemas/EvidenceSource'
additionalProperties: false
responses:
Unauthorized:
description: API key missing, invalid, inactive, or unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
parameters:
DecisionId:
name: decision_id
in: path
required: true
schema:
type: string
maxLength: 600
DecisionResponseView:
name: x-decision-response-view
in: header
required: false
schema:
type: string
enum:
- minimal
- standard
- full
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key