Product, agent, queue, or internal tool
Names the action under consideration and sends structured context from a server-side boundary.
API Reference
The recorded-decision API contract, without the full docs scroll.
Use this page when you need endpoint shape, auth behavior, response views, idempotency, rate limits, and the fields your application must store before it changes state.
Core flow
The API boundary is deliberately small: one server-side call, one versioned Decision Record, one downstream action that stores the record before proceeding.
POST /api/decide
Evaluates declared context, policy state, and response view without letting the caller mutate state first.
Decision Record v1
Returns verdict, evidence, action binding, policy bundle hash, record hash, receipt hash, replay, and verification links.
Proceed, block, or review
The caller persists the full record beside the action and then reports execution and outcome receipts.
Endpoint reference
The table below is the compact implementation surface. Status labels separate the first production boundary from proof, lifecycle data, and reference utility surfaces. The full canonical wording remains in the complete docs.
Endpoint maturity: start with stable core, add stable proof for reviewability, then connect data-dependent intelligence once execution and outcome reporting are live.
First-boundary integration
Create, fetch, replay, diff, verify, and check readiness for the Decision Record flow.
Verification surface
Use for portable verification, packet checks, and public receipt-key inspection.
Lifecycle intelligence
Becomes most useful once callers report execution receipts, outcomes, and review data.
Implementation helpers
Supports templates, policy-bundle review, and setup inspection without expanding the core path.
| Endpoint | Method | Status | Purpose |
|---|---|---|---|
/api/decide | POST | Stable core | Create a Decision Record v1 with verdict, evidence, action binding, hashes, replay, verify URLs, and optional confidence. |
/api/decision/:id | GET | Stable core | Fetch a stored decision ledger entry by decision_id. |
/api/decision/:id/replay | POST | Stable core | Replay the original input against current declared state and return drift information. |
/api/decision/:id/diff | POST | Stable core | Replay/diff alias for rollout review and regression comparison. |
/api/decision/:id/execution | GET / POST | Data-dependent | Record or list target-system neutral Action Execution Receipts. |
/api/decision/:id/outcome | GET / POST | Data-dependent | Record or list post-action Outcome Records linked to the original Decision Record. |
/api/decision/:id/crm-sync | GET / POST | Data-dependent | Record or list CRM write-back receipts for Decision Record fields. |
/api/decision/:id/packet | GET | Data-dependent | Export a portable Decision Packet v1 with record, receipts, outcomes, intelligence, and chain hints. |
/api/decision/packet/verify | GET / POST | Stable proof | Verify an exported Decision Packet v1 and embedded proof links. |
/api/decision/verify | GET / POST | Stable core | Verify an exported Decision Record without trusting hosted ledger storage. |
/api/decision/:id/verify | GET / POST | Stable core | Verify a stored or supplied record by recomputing record, receipt, bundle, and signature checks. |
/api/decision/chains/:chain_id | GET | Data-dependent | Inspect caller-scoped audit-chain links, retained records, and rolling Merkle root metadata. |
/api/decision/policies/:policy_id/effectiveness | GET | Data-dependent | Score policy outcomes from latest Outcome Records in the caller scope. |
/api/decision/policies/:policy_id/confidence | GET | Data-dependent | Return deterministic confidence baselines for a candidate verdict or action. |
/api/decision/policies/:policy_id/anomalies | GET | Data-dependent | Return explainable anomaly reports with reason codes and baselines. |
/api/decision/policies/:policy_id/benchmarks | GET | Data-dependent | Return opt-in anonymized benchmark percentiles after privacy thresholds are met. |
/api/decision/receipt-keys | GET | Stable proof | Return public Ed25519 receipt verification keys when portable signing is configured. |
/api/decision/policy-bundles | GET | Reference utility | Return active and historical policy bundle hashes and source references. |
/api/decision/policy-patterns | GET | Reference utility | Return first-party request, outcome, and CRM-sync templates for common workflows. |
/api/decision/status | GET | Stable core | Return readiness for signing, ledger, idempotency, registries, auth, and backend wiring. |
Response views
Every request creates the same canonical ledger entry. The view only changes how much of the record is returned immediately.
Fast routing
decision_id, request_id, verdict, action, hashes, signing fields, and verify/replay URLs.
Production integrations
Minimal fields plus evidence, policy fields, policy_bundle, action_binding, confidence details, input/output hashes, and timestamp.
Audits and exports
Standard fields plus evidence_manifest, integrity, and upstream response fields when available.
Body preference
{
"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.jsonAuth, limits, and fail-closed behavior
Server-side key
Production calls send x-api-key: $DECIDE_API_KEY. Do not expose production keys in browser clients.
Idempotency
Use x-idempotency-key. Same key plus same canonical payload returns the original record; different payload returns 409.
Rate and monthly caps
Watch X-RateLimit-*, Retry-After, and X-Usage-Monthly-* headers. High-risk actions should route to review when capacity is unavailable.
Default caller behavior
For irreversible software actions, unauthorized, rate-limited, capped, idempotency-conflicted, or upstream-unavailable calls should not silently approve. Keep the source record in review until the decision can be recorded.
Fields to store with the action
A Decision Record is useful only if it travels with the downstream mutation. Store the full object when possible; at minimum, preserve these fields.
Trace handles
decision_record_versionrequest_iddecision_ididempotency_key
Verdict and evidence
verdictandactionaction_bindingevidenceevidence_manifest
Hashes and replay
policy_versionandpolicy_bundle_hashrecord_hashandreceipt_hashreceipt_signatureverify_urlandreplay_url