{ "openapi": "3.1.0", "info": { "title": "Decide Decision 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.10.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": "Decision Protocol", "description": "Core decide, replay, diff, verification, readiness, and registry endpoints." }, { "name": "Counterfactuals", "description": "Simulation-only what-if analysis for stored Decision Records." }, { "name": "Verification", "description": "Hosted and exported Decision Record verification." }, { "name": "Registries", "description": "Receipt key and policy bundle registries." }, { "name": "Policy Patterns", "description": "First-party Decision API pattern templates for common state-changing integrations." }, { "name": "Action Execution", "description": "Record target-system neutral receipts proving whether the action authorized by a Decision Record was executed, skipped, failed, blocked, or reverted." }, { "name": "Outcome Tracking", "description": "Report and read what happened after a Decision Record authorized or routed an action." }, { "name": "CRM Sync", "description": "Record CRM write-back and inbound sync receipts linked to Decision Records." }, { "name": "Effectiveness", "description": "Outcome-based policy effectiveness scoring scoped to the caller API key." }, { "name": "Confidence", "description": "Predictive decision confidence from caller-scoped Outcome Records." }, { "name": "Benchmarks", "description": "Opt-in anonymized cross-customer benchmarks with minimum privacy thresholds." }, { "name": "Anomalies", "description": "Explainable outcome-based anomaly reports scoped to the caller API key." }, { "name": "Audit Chain", "description": "Caller-scoped cryptographic audit trails with rolling Merkle roots and retained-link verification." }, { "name": "Decision Packets", "description": "Portable Decision Packet v1 exports that bundle a Decision Record with execution, outcome, intelligence, and audit-chain proof material." } ], "paths": { "/api/decide": { "post": { "tags": [ "Decision Protocol" ], "operationId": "createDecision", "summary": "Create a Decision Record", "description": "Returns a Decision Record v1 object. Same idempotency key plus same canonical payload replays the original record; same key plus different payload returns a 409 conflict.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/DecisionResponseView" }, { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/Prefer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionRequest" }, "examples": { "pricingException": { "summary": "Pricing exception before billing mutation", "value": { "question": "Approve 15% annual-plan discount exception?", "mode": "single", "context": { "workflow": "pricing_exception", "source_record_id": "deal_1042", "requested_action": "approve_discount", "target_system": "billing", "target_object_id": "sub_1042", "mutation": "discount.create", "margin_floor": "passed", "owner_rule": "verified" } } } } } } }, "responses": { "200": { "description": "Decision Record projection", "headers": { "x-decision-id": { "schema": { "type": "string" } }, "x-decision-record-hash": { "schema": { "type": "string" } }, "x-decision-receipt-hash": { "schema": { "type": "string" } }, "x-decision-confidence-score": { "schema": { "type": "string" } }, "x-decision-confidence-level": { "schema": { "type": "string" } }, "x-decision-confidence-hash": { "schema": { "type": "string" } }, "x-idempotency-status": { "schema": { "type": "string", "enum": [ "created", "replayed" ] } }, "x-decision-verify-url": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionRecord" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamFailure" } } } }, "/api/decision/status": { "get": { "tags": [ "Decision Protocol" ], "operationId": "getDecisionStatus", "summary": "Read Decision API readiness", "security": [], "responses": { "200": { "description": "Ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionStatus" } } } }, "503": { "description": "Degraded readiness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionStatus" } } } } } } }, "/api/decision/policy-bundles": { "get": { "tags": [ "Registries" ], "operationId": "listPolicyBundles", "summary": "Read the policy bundle registry", "security": [], "parameters": [ { "name": "hash", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional policy bundle hash to resolve a single bundle." } ], "responses": { "200": { "description": "Policy bundle registry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyBundleRegistry" } } } }, "404": { "description": "Bundle hash not found" } } } }, "/api/decision/policy-patterns": { "get": { "tags": [ "Policy Patterns" ], "operationId": "listPolicyPatterns", "summary": "Read the policy pattern registry", "description": "Returns first-party Decision API pattern templates. Pass pattern_id for a single pattern or tag to filter the registry.", "security": [], "parameters": [ { "name": "pattern_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional pattern id or policy id to resolve a single policy pattern." }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional tag filter for the registry view." } ], "responses": { "200": { "description": "Policy pattern registry or single policy pattern", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DecisionPatternRegistry" }, { "$ref": "#/components/schemas/DecisionPatternResponse" } ] } } } }, "404": { "description": "Pattern not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/decision/receipt-keys": { "get": { "tags": [ "Registries" ], "operationId": "listReceiptKeys", "summary": "Read the public receipt key registry", "security": [], "responses": { "200": { "description": "Receipt key registry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptKeyRegistry" } } } } } } }, "/api/decision/verify": { "get": { "tags": [ "Verification" ], "operationId": "describeRecordVerification", "summary": "Describe exported-record verification", "security": [], "responses": { "200": { "description": "Verification endpoint metadata" } } }, "post": { "tags": [ "Verification" ], "operationId": "verifyExportedDecisionRecord", "summary": "Verify an exported Decision Record", "description": "Verifies a Decision Record supplied in the request body without requiring a hosted ledger lookup.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRecordRequest" } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResult" } } } } } } }, "/api/decision/packet/verify": { "get": { "tags": [ "Decision Packets", "Verification" ], "operationId": "describeDecisionPacketVerification", "summary": "Describe Decision Packet verification", "security": [], "responses": { "200": { "description": "Decision Packet verification endpoint metadata" } } }, "post": { "tags": [ "Decision Packets", "Verification" ], "operationId": "verifyDecisionPacket", "summary": "Verify an exported Decision Packet", "description": "Verifies a Decision Packet v1 object supplied in the request body, including packet hash, embedded Decision Record verification, execution and outcome hash links, intelligence report hashes, and retained audit-chain links when present.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyDecisionPacketRequest" } } } }, "responses": { "200": { "description": "Decision Packet verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResult" } } } } } } }, "/api/decision/{decision_id}": { "get": { "tags": [ "Decision Protocol" ], "operationId": "getDecision", "summary": "Fetch a stored decision", "parameters": [ { "$ref": "#/components/parameters/DecisionId" } ], "responses": { "200": { "description": "Stored decision ledger entry" }, "404": { "description": "Decision not found" } } } }, "/api/decision/{decision_id}/verify": { "get": { "tags": [ "Verification" ], "operationId": "verifyStoredDecision", "summary": "Verify a stored decision", "parameters": [ { "$ref": "#/components/parameters/DecisionId" } ], "responses": { "200": { "description": "Ledger verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResult" } } } }, "404": { "description": "Decision not found" } } }, "post": { "tags": [ "Verification" ], "operationId": "verifyStoredOrSuppliedDecision", "summary": "Verify a stored or supplied decision", "parameters": [ { "$ref": "#/components/parameters/DecisionId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRecordRequest" } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResult" } } } } } } }, "/api/decision/{decision_id}/packet": { "get": { "tags": [ "Decision Packets" ], "operationId": "getDecisionPacket", "summary": "Export a portable Decision Packet", "description": "Returns a Decision Packet v1 export for a stored Decision Record, optionally including original input, retained audit-chain links, execution receipts, outcome records, and policy intelligence summaries.", "parameters": [ { "$ref": "#/components/parameters/DecisionId" }, { "name": "include_input", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "include_chain", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "include_intelligence", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "execution_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20 } }, { "name": "outcome_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20 } }, { "name": "chain_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20 } } ], "responses": { "200": { "description": "Decision Packet export", "headers": { "x-decision-packet-version": { "schema": { "type": "string", "const": "decision_packet_v1" } }, "x-decision-packet-hash": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionPacket" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Decision not found" } } } }, "/api/decision/{decision_id}/replay": { "post": { "tags": [ "Decision Protocol" ], "operationId": "replayDecision", "summary": "Replay a stored decision under current policy", "parameters": [ { "$ref": "#/components/parameters/DecisionId" }, { "$ref": "#/components/parameters/DecisionResponseView" } ], "responses": { "200": { "description": "Replay summary and current decision projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayResult" } } } } } } }, "/api/decision/{decision_id}/diff": { "post": { "tags": [ "Decision Protocol" ], "operationId": "diffDecision", "summary": "Replay/diff alias for a stored decision", "parameters": [ { "$ref": "#/components/parameters/DecisionId" }, { "$ref": "#/components/parameters/DecisionResponseView" } ], "responses": { "200": { "description": "Replay/diff summary and current decision projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayResult" } } } } } } }, "/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" }, "404": { "description": "Decision not found" }, "422": { "description": "Base input unavailable" } } } }, "/api/decision/{decision_id}/execution": { "post": { "tags": [ "Action Execution" ], "operationId": "recordDecisionExecution", "summary": "Record a Decision Action Execution receipt", "description": "Creates a hashed Action Execution Receipt linked to the original Decision Record and action binding. Same idempotency key plus same canonical execution payload replays the original receipt; same key plus different payload returns a 409 conflict.", "parameters": [ { "$ref": "#/components/parameters/DecisionId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionExecutionRequest" }, "examples": { "billingExecution": { "summary": "Billing mutation execution receipt", "value": { "execution_status": "executed", "action_taken": "apply_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", "executor": { "type": "service", "id": "billing-worker" } } } } } } }, "responses": { "200": { "description": "Idempotent replay of an existing Action Execution Receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionExecutionResult" } } } }, "201": { "description": "Action Execution Receipt recorded", "headers": { "x-decision-execution-id": { "schema": { "type": "string" } }, "x-decision-execution-hash": { "schema": { "type": "string" } }, "x-idempotency-status": { "schema": { "type": "string", "enum": [ "created", "replayed" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionExecutionResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } } }, "get": { "tags": [ "Action Execution" ], "operationId": "listDecisionExecutions", "summary": "List Action Execution Receipts for a decision", "parameters": [ { "$ref": "#/components/parameters/DecisionId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "Action Execution Receipt list", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "decision_id", "count", "executions" ], "properties": { "ok": { "type": "boolean" }, "decision_id": { "type": "string" }, "count": { "type": "integer" }, "executions": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionExecution" } } }, "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/decision/{decision_id}/outcome": { "post": { "tags": [ "Outcome Tracking" ], "operationId": "recordDecisionOutcome", "summary": "Record a Decision Outcome", "description": "Creates a hashed Outcome Record linked to the original Decision Record. Same idempotency key plus same canonical outcome payload replays the original outcome; same key plus different payload returns a 409 conflict.", "parameters": [ { "$ref": "#/components/parameters/DecisionId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionOutcomeRequest" }, "examples": { "billingMutation": { "summary": "Billing mutation outcome", "value": { "outcome_status": "succeeded", "action_taken": "apply_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 } } } } } } }, "responses": { "200": { "description": "Idempotent replay of an existing Decision Outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionOutcomeResult" } } } }, "201": { "description": "Decision Outcome recorded", "headers": { "x-decision-outcome-id": { "schema": { "type": "string" } }, "x-decision-outcome-hash": { "schema": { "type": "string" } }, "x-idempotency-status": { "schema": { "type": "string", "enum": [ "created", "replayed" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionOutcomeResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } } }, "get": { "tags": [ "Outcome Tracking" ], "operationId": "listDecisionOutcomes", "summary": "List Decision Outcomes for a decision", "parameters": [ { "$ref": "#/components/parameters/DecisionId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "Decision Outcome list", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "decision_id", "count", "outcomes" ], "properties": { "ok": { "type": "boolean" }, "decision_id": { "type": "string" }, "count": { "type": "integer" }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionOutcome" } } }, "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/decision/{decision_id}/crm-sync": { "post": { "tags": [ "CRM Sync" ], "operationId": "recordDecisionCrmSync", "summary": "Record a Decision CRM Sync receipt", "description": "Creates a hashed CRM Sync Record linked to the original Decision Record. Same idempotency key plus same canonical CRM sync payload replays the original sync receipt; same key plus different payload returns a 409 conflict.", "parameters": [ { "$ref": "#/components/parameters/DecisionId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionCrmSyncRequest" }, "examples": { "salesforceWriteback": { "summary": "Salesforce opportunity write-back", "value": { "sync_status": "written", "sync_direction": "writeback", "crm_provider": "salesforce", "crm_object_type": "Opportunity", "crm_object_id": "006xx000004TmiQAAS", "crm_record_url": "https://example.my.salesforce.com/006xx000004TmiQAAS", "decision_record_hash": "7f3a...", "decision_receipt_hash": "c91e...", "decision_verdict": "yes", "decision_action": "approve_discount", "policy_id": "pricing_exception", "policy_version": "v3" } } } } } }, "responses": { "200": { "description": "Idempotent replay of an existing Decision CRM Sync receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionCrmSyncResult" } } } }, "201": { "description": "Decision CRM Sync recorded", "headers": { "x-decision-crm-sync-id": { "schema": { "type": "string" } }, "x-decision-crm-sync-hash": { "schema": { "type": "string" } }, "x-idempotency-status": { "schema": { "type": "string", "enum": [ "created", "replayed" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionCrmSyncResult" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } } }, "get": { "tags": [ "CRM Sync" ], "operationId": "listDecisionCrmSyncs", "summary": "List Decision CRM Sync receipts for a decision", "parameters": [ { "$ref": "#/components/parameters/DecisionId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "Decision CRM Sync receipt list", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "decision_id", "count", "crm_syncs" ], "properties": { "ok": { "type": "boolean" }, "decision_id": { "type": "string" }, "count": { "type": "integer" }, "crm_syncs": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionCrmSync" } } }, "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/decision/policies/{policy_id}/effectiveness": { "get": { "tags": [ "Effectiveness" ], "operationId": "getPolicyEffectiveness", "summary": "Read outcome-based policy effectiveness", "description": "Returns policy_effectiveness_v1 metrics derived from the latest Decision Outcome per decision within the caller API-key scope. Proxy false-positive/false-negative rates are outcome proxies, not causal ML claims.", "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 180 } }, { "name": "policy_version", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 180 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 500 } }, { "name": "min_sample", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 10 } } ], "responses": { "200": { "description": "Policy effectiveness metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyEffectiveness" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/decision/policies/{policy_id}/confidence": { "get": { "tags": [ "Confidence" ], "operationId": "getPolicyConfidence", "summary": "Read predictive policy confidence", "description": "Returns decision_confidence_v1 for a candidate verdict/action using latest Decision Outcome records within the caller API-key scope. Scores are deterministic confidence signals, not causal ML claims.", "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 180 } }, { "name": "policy_version", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 180 } }, { "name": "verdict", "in": "query", "required": false, "schema": { "type": "string", "default": "yes" } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 140 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1000 } }, { "name": "min_sample", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 10 } } ], "responses": { "200": { "description": "Decision confidence baseline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionConfidence" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/decision/policies/{policy_id}/benchmarks": { "get": { "tags": [ "Benchmarks" ], "operationId": "getPolicyBenchmarks", "summary": "Read anonymized policy benchmarks", "description": "Returns decision_benchmark_v1 with caller metrics and opt-in anonymized cohort percentiles when minimum cohort privacy thresholds are met. Raw customer records are never exposed.", "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 180 } }, { "name": "policy_version", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 180 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 250000, "default": 5000 } }, { "name": "min_cohort_scopes", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 2, "maximum": 10000, "default": 3 } }, { "name": "min_cohort_decisions", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 5, "maximum": 1000000, "default": 30 } } ], "responses": { "200": { "description": "Anonymized policy benchmark report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionBenchmark" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/decision/policies/{policy_id}/anomalies": { "get": { "tags": [ "Anomalies" ], "operationId": "getPolicyAnomalies", "summary": "Read outcome-based policy anomalies", "description": "Returns decision_anomaly_report_v1 derived from the latest Decision Outcome per decision within the caller API-key scope. Scores are deterministic outcome-signal heuristics with explainable reason codes, not model predictions.", "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 180 } }, { "name": "policy_version", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 180 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1000 } }, { "name": "min_sample", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 10 } }, { "name": "threshold", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.35 } }, { "name": "max_items", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 25 } } ], "responses": { "200": { "description": "Policy anomaly report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAnomalyReport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/decision/chains/{chain_id}": { "get": { "tags": [ "Audit Chain" ], "operationId": "getDecisionChain", "summary": "Read a Decision Record audit chain", "description": "Returns decision_chain_v1 head metadata, retained chain links, rolling Merkle root, and verification checks for the caller API-key scoped audit chain.", "parameters": [ { "name": "chain_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 180 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } } ], "responses": { "200": { "description": "Decision chain report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionChain" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Requested chain does not match caller scope" }, "404": { "description": "Decision chain not found" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "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" ] } }, "IdempotencyKey": { "name": "x-idempotency-key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 300 } }, "RequestId": { "name": "x-request-id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 160 } }, "Prefer": { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string", "examples": [ "return=minimal", "return=standard", "return=full" ] } } }, "responses": { "Unauthorized": { "description": "API key missing, invalid, inactive, or unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "IdempotencyConflict": { "description": "Same idempotency key was reused with a different canonical payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit or monthly cap exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UpstreamFailure": { "description": "Upstream decision engine unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "DecisionRequest": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string" }, "mode": { "type": "string", "examples": [ "single", "multi" ] }, "context": { "type": [ "object", "string" ], "additionalProperties": true }, "response_view": { "type": "string", "enum": [ "minimal", "standard", "full" ] } }, "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" }, "action": { "type": "string" }, "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" }, "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" }, "receipt_hash": { "type": "string" }, "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 }, "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 }, "EvidenceManifest": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceSource" } } }, "additionalProperties": false }, "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 }, "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 }, "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 }, "VerifyRecordRequest": { "type": "object", "required": [ "record" ], "properties": { "record": { "$ref": "#/components/schemas/DecisionRecord" }, "decision": { "$ref": "#/components/schemas/DecisionRecord" }, "input": { "type": "object", "additionalProperties": true }, "request": { "type": "object", "additionalProperties": true }, "public_key": { "type": "string" } }, "additionalProperties": true }, "VerifyDecisionPacketRequest": { "type": "object", "required": [ "packet" ], "properties": { "packet": { "$ref": "#/components/schemas/DecisionPacket" }, "decision_packet": { "$ref": "#/components/schemas/DecisionPacket" }, "input": { "type": "object", "additionalProperties": true }, "public_key": { "type": "string" } }, "additionalProperties": true }, "DecisionPacket": { "type": "object", "required": [ "ok", "decision_protocol_version", "decision_packet_version", "decision_record", "packet_manifest", "packet_hash" ], "properties": { "ok": { "type": "boolean" }, "decision_protocol_version": { "type": "string", "const": "decision_protocol_v1" }, "decision_packet_version": { "type": "string", "const": "decision_packet_v1" }, "generated_at": { "type": "string" }, "decision_id": { "type": [ "string", "null" ] }, "record_hash": { "type": [ "string", "null" ] }, "receipt_hash": { "type": [ "string", "null" ] }, "policy_id": { "type": [ "string", "null" ] }, "policy_version": { "type": [ "string", "null" ] }, "decision_record": { "$ref": "#/components/schemas/DecisionRecord" }, "input": { "type": "object", "additionalProperties": true }, "executions": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionExecution" } }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionOutcome" } }, "policy_intelligence": { "type": "object", "properties": { "effectiveness": { "anyOf": [ { "$ref": "#/components/schemas/PolicyEffectiveness" }, { "type": "null" } ] }, "anomalies": { "anyOf": [ { "$ref": "#/components/schemas/PolicyAnomalyReport" }, { "type": "null" } ] } }, "additionalProperties": true }, "audit_chain": { "anyOf": [ { "$ref": "#/components/schemas/DecisionChain" }, { "type": "null" } ] }, "verification_hints": { "type": "object", "additionalProperties": true }, "packet_manifest": { "type": "object", "additionalProperties": true }, "packet_hash": { "type": "string" } }, "additionalProperties": true }, "VerificationResult": { "type": "object", "required": [ "ok", "verified", "checks" ], "properties": { "ok": { "type": "boolean" }, "decision_id": { "type": "string" }, "source": { "type": "string" }, "verified": { "type": "boolean" }, "checks": { "type": "object", "additionalProperties": { "type": [ "boolean", "null" ] } }, "expected": { "type": "object", "additionalProperties": true }, "actual": { "type": "object", "additionalProperties": true }, "policy_bundle": { "$ref": "#/components/schemas/PolicyBundle" }, "record_hash": { "type": [ "string", "null" ] }, "receipt_hash": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "DecisionStatus": { "type": "object", "required": [ "ok", "status", "decision_protocol_version", "checks" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ready", "degraded", "error" ] }, "decision_protocol_version": { "type": "string" }, "decision_record_version": { "type": "string" }, "checks": { "type": "object", "additionalProperties": true }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": true }, "PolicyBundleRegistry": { "type": "object", "required": [ "ok", "status", "bundles", "registry_hash" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "current_policy_bundle_hash": { "type": [ "string", "null" ] }, "current": { "$ref": "#/components/schemas/PolicyBundle" }, "bundles": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyBundle" } }, "registry_hash": { "type": "string" } }, "additionalProperties": true }, "DecisionPattern": { "type": "object", "required": [ "decision_pattern_version", "pattern_id", "policy_id", "pattern_hash" ], "properties": { "decision_pattern_version": { "type": "string", "const": "decision_pattern_v1" }, "pattern_id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "policy_id": { "type": "string" }, "recommended_policy_version": { "type": "string" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "required_context_fields": { "type": "array", "items": { "type": "string" } }, "recommended_context_fields": { "type": "array", "items": { "type": "string" } }, "evidence_codes": { "type": "array", "items": { "type": "string" } }, "decision_request_template": { "$ref": "#/components/schemas/DecisionRequest" }, "outcome_template": { "type": "object", "additionalProperties": true }, "crm_sync_template": { "type": "object", "additionalProperties": true }, "sdk_examples": { "type": "array", "items": { "type": "string" } }, "pattern_hash": { "type": "string" } }, "additionalProperties": true }, "DecisionPatternRegistry": { "type": "object", "required": [ "ok", "decision_pattern_registry_version", "patterns", "registry_hash" ], "properties": { "ok": { "type": "boolean" }, "decision_protocol_version": { "type": "string" }, "decision_record_version": { "type": "string" }, "decision_pattern_registry_version": { "type": "string", "const": "decision_pattern_registry_v1" }, "source": { "type": "string" }, "status": { "type": "string" }, "count": { "type": "integer" }, "patterns": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionPattern" } }, "registry_hash": { "type": "string" }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": true }, "DecisionPatternResponse": { "type": "object", "required": [ "ok", "policy_pattern" ], "properties": { "ok": { "type": "boolean" }, "policy_pattern": { "$ref": "#/components/schemas/DecisionPattern" } }, "additionalProperties": true }, "ReceiptKeyRegistry": { "type": "object", "required": [ "ok", "status", "keys" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "current_key_id": { "type": [ "string", "null" ] }, "keys": { "type": "array", "items": { "type": "object", "properties": { "key_id": { "type": "string" }, "algorithm": { "type": "string" }, "public_key": { "type": "string" }, "public_key_fingerprint": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "ReplayResult": { "type": "object", "required": [ "ok", "replay", "decision" ], "properties": { "ok": { "type": "boolean" }, "replay": { "type": "object", "additionalProperties": true }, "decision": { "$ref": "#/components/schemas/DecisionRecord" } }, "additionalProperties": true }, "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 }, "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 }, "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 }, "ErrorResponse": { "type": "object", "properties": { "c": { "type": "string" }, "v": { "type": "string" }, "request_id": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "DecisionOutcomeRequest": { "type": "object", "required": [ "outcome_status" ], "properties": { "decision_id": { "type": "string", "maxLength": 600 }, "outcome_status": { "type": "string", "description": "Normalized to succeeded, failed, reverted, reviewed, skipped, unknown, or a compact custom status." }, "action_taken": { "type": "string" }, "action_executed": { "type": "boolean" }, "target_system": { "type": "string" }, "target_object_id": { "type": "string" }, "mutation": { "type": "string" }, "external_ref": { "type": "string" }, "decision_record_hash": { "type": "string" }, "decision_receipt_hash": { "type": "string" }, "observed_metrics": { "type": "object", "additionalProperties": true }, "evidence_refs": { "type": "array", "items": { "type": [ "object", "string" ], "additionalProperties": true } }, "executed_at": { "type": "string" }, "reported_at": { "type": "string" } }, "additionalProperties": true }, "DecisionOutcome": { "type": "object", "required": [ "decision_protocol_version", "decision_outcome_version", "outcome_id", "decision_id", "outcome_status", "outcome_hash", "reported_at" ], "properties": { "decision_protocol_version": { "type": "string", "const": "decision_protocol_v1" }, "decision_outcome_version": { "type": "string", "const": "decision_outcome_v1" }, "outcome_id": { "type": "string" }, "decision_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "outcome_status": { "type": "string" }, "action_executed": { "type": "boolean" }, "action_taken": { "type": "string" }, "target_system": { "type": "string" }, "target_object_id": { "type": "string" }, "mutation": { "type": "string" }, "external_ref": { "type": "string" }, "decision_record_hash": { "type": "string" }, "decision_receipt_hash": { "type": "string" }, "decision_verdict": { "type": "string" }, "decision_action": { "type": "string" }, "policy_id": { "type": "string" }, "policy_version": { "type": "string" }, "policy_bundle_hash": { "type": "string" }, "action_binding": { "$ref": "#/components/schemas/ActionBinding" }, "observed_metrics": { "type": "object", "additionalProperties": true }, "evidence_refs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "outcome_input_hash": { "type": "string" }, "outcome_hash": { "type": "string" }, "integrity": { "type": "object", "additionalProperties": true }, "executed_at": { "type": "string" }, "reported_at": { "type": "string" }, "decision_found": { "type": "boolean" }, "decision_url": { "type": "string" }, "verify_url": { "type": "string" } }, "additionalProperties": true }, "DecisionOutcomeResult": { "type": "object", "required": [ "ok", "decision_id", "outcome" ], "properties": { "ok": { "type": "boolean" }, "idempotency_status": { "type": "string" }, "decision_id": { "type": "string" }, "outcome": { "$ref": "#/components/schemas/DecisionOutcome" } }, "additionalProperties": true }, "DecisionCrmSyncRequest": { "type": "object", "required": [ "sync_status", "crm_provider", "crm_object_type", "crm_object_id" ], "properties": { "decision_id": { "type": "string", "maxLength": 600 }, "sync_status": { "type": "string", "description": "Normalized to queued, written, failed, skipped, stale, unknown, or a compact custom status." }, "sync_direction": { "type": "string", "enum": [ "writeback", "inbound", "bidirectional" ] }, "crm_provider": { "type": "string", "examples": [ "salesforce", "hubspot", "generic" ] }, "crm_object_type": { "type": "string" }, "crm_object_id": { "type": "string" }, "crm_record_url": { "type": "string" }, "field_mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "mapped_fields": { "type": "object", "additionalProperties": true }, "decision_record_hash": { "type": "string" }, "decision_receipt_hash": { "type": "string" }, "decision_verdict": { "type": "string" }, "decision_action": { "type": "string" }, "policy_id": { "type": "string" }, "policy_version": { "type": "string" }, "crm_revision": { "type": "string" }, "crm_modified_at": { "type": "string" }, "reported_at": { "type": "string" } }, "additionalProperties": true }, "DecisionCrmSync": { "type": "object", "required": [ "decision_protocol_version", "decision_crm_sync_version", "sync_id", "decision_id", "sync_status", "crm_target", "sync_hash", "reported_at" ], "properties": { "decision_protocol_version": { "type": "string", "const": "decision_protocol_v1" }, "decision_crm_sync_version": { "type": "string", "const": "decision_crm_sync_v1" }, "sync_id": { "type": "string" }, "decision_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "sync_direction": { "type": "string" }, "sync_status": { "type": "string" }, "crm_target": { "type": "object", "additionalProperties": true }, "field_mapping": { "type": "object", "additionalProperties": true }, "mapped_fields": { "type": "object", "additionalProperties": true }, "decision_values": { "type": "object", "additionalProperties": true }, "sync_input_hash": { "type": "string" }, "sync_hash": { "type": "string" }, "integrity": { "type": "object", "additionalProperties": true }, "reported_at": { "type": "string" }, "decision_found": { "type": "boolean" }, "decision_url": { "type": "string" }, "verify_url": { "type": "string" } }, "additionalProperties": true }, "DecisionCrmSyncResult": { "type": "object", "required": [ "ok", "decision_id", "crm_sync" ], "properties": { "ok": { "type": "boolean" }, "idempotency_status": { "type": "string" }, "decision_id": { "type": "string" }, "crm_sync": { "$ref": "#/components/schemas/DecisionCrmSync" } }, "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 }, "DecisionBenchmark": { "type": "object", "required": [ "ok", "decision_benchmark_version", "policy_id", "privacy", "your_metrics", "cross_customer", "recommendation", "benchmark_hash" ], "properties": { "ok": { "type": "boolean" }, "decision_benchmark_version": { "type": "string", "const": "decision_benchmark_v1" }, "generated_at": { "type": "string" }, "source": { "type": "string", "const": "decision_outcomes" }, "scope": { "type": "string", "const": "caller_api_key_plus_anonymized_opt_in_cohort" }, "policy_id": { "type": "string" }, "policy_version": { "type": [ "string", "null" ] }, "privacy": { "type": "object", "properties": { "anonymized": { "type": "boolean" }, "raw_records_exposed": { "type": "boolean", "const": false }, "caller_excluded_from_cohort": { "type": "boolean" }, "opt_in_required": { "type": "boolean" }, "enabled": { "type": "boolean" }, "minimum_cohort_scopes": { "type": "integer" }, "minimum_cohort_decisions": { "type": "integer" } }, "additionalProperties": true }, "your_metrics": { "type": "object", "additionalProperties": true }, "cross_customer": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "insufficient_cohort", "no_cohort_data", "disabled" ] }, "cohort_scopes": { "type": "integer" }, "cohort_decisions": { "type": "integer" }, "threshold_met": { "type": "boolean" }, "metrics": { "type": [ "object", "null" ], "additionalProperties": true }, "percentiles": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": true }, "comparison": { "type": [ "object", "null" ], "additionalProperties": true }, "recommendation": { "type": "string", "enum": [ "benchmark_unavailable", "within_cohort_range", "review_policy_outcomes", "tighten_approval_policy", "reduce_manual_review_pressure" ] }, "benchmark_hash": { "type": "string" } }, "additionalProperties": true }, "PolicyEffectiveness": { "type": "object", "required": [ "ok", "policy_effectiveness_version", "policy_id", "decisions_analyzed", "metrics", "effectiveness_hash", "recommendation" ], "properties": { "ok": { "type": "boolean" }, "policy_effectiveness_version": { "type": "string", "const": "policy_effectiveness_v1" }, "generated_at": { "type": "string" }, "policy_id": { "type": "string" }, "policy_version": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "decision_outcomes" }, "minimum_sample_size": { "type": "integer" }, "decisions_analyzed": { "type": "integer" }, "outcomes_analyzed": { "type": "integer" }, "distinct_decisions": { "type": "integer" }, "by_status": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_verdict": { "type": "object", "additionalProperties": { "type": "integer" } }, "metrics": { "type": "object", "properties": { "success_rate": { "type": [ "number", "null" ] }, "failure_rate": { "type": [ "number", "null" ] }, "revert_rate": { "type": [ "number", "null" ] }, "review_rate": { "type": [ "number", "null" ] }, "skipped_rate": { "type": [ "number", "null" ] }, "unknown_rate": { "type": [ "number", "null" ] }, "terminal_coverage": { "type": [ "number", "null" ] }, "executed_rate": { "type": [ "number", "null" ] } }, "additionalProperties": true }, "proxy_quality": { "type": "object", "properties": { "estimated_false_positive_rate": { "type": [ "number", "null" ] }, "estimated_false_negative_rate": { "type": [ "number", "null" ] }, "note": { "type": "string" } }, "additionalProperties": true }, "effectiveness_score": { "type": [ "number", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "status": { "type": "string", "enum": [ "scored", "insufficient_data" ] }, "recommendation": { "type": "string", "enum": [ "insufficient_data", "review_policy", "monitor", "healthy" ] }, "window": { "type": "object", "additionalProperties": true }, "data_quality": { "type": "object", "additionalProperties": true }, "effectiveness_hash": { "type": "string" } }, "additionalProperties": true }, "PolicyAnomalyReason": { "type": "object", "required": [ "code", "message", "weight" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "weight": { "type": "number" }, "observed": { "type": "object", "additionalProperties": true }, "baseline": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "PolicyAnomaly": { "type": "object", "required": [ "decision_id", "outcome_id", "anomaly_score", "severity", "reasons" ], "properties": { "decision_id": { "type": "string" }, "outcome_id": { "type": "string" }, "anomaly_score": { "type": "number" }, "severity": { "type": "string", "enum": [ "normal", "low", "medium", "high" ] }, "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyAnomalyReason" } }, "decision_verdict": { "type": "string" }, "outcome_status": { "type": "string" }, "action_executed": { "type": [ "boolean", "null" ] }, "policy_id": { "type": "string" }, "policy_version": { "type": [ "string", "null" ] }, "target_system": { "type": [ "string", "null" ] }, "target_object_id": { "type": [ "string", "null" ] }, "mutation": { "type": [ "string", "null" ] }, "reported_at": { "type": [ "string", "null" ] }, "outcome_hash": { "type": [ "string", "null" ] }, "decision_url": { "type": [ "string", "null" ] }, "verify_url": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "PolicyAnomalyReport": { "type": "object", "required": [ "ok", "decision_anomaly_report_version", "policy_id", "decisions_analyzed", "summary", "baseline", "anomalies", "anomaly_hash", "recommendation" ], "properties": { "ok": { "type": "boolean" }, "decision_anomaly_report_version": { "type": "string", "const": "decision_anomaly_report_v1" }, "generated_at": { "type": "string" }, "policy_id": { "type": "string" }, "policy_version": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "decision_outcomes" }, "minimum_sample_size": { "type": "integer" }, "anomaly_threshold": { "type": "number" }, "max_anomalies_returned": { "type": "integer" }, "decisions_analyzed": { "type": "integer" }, "outcomes_analyzed": { "type": "integer" }, "distinct_decisions": { "type": "integer" }, "status": { "type": "string", "enum": [ "scored", "insufficient_data" ] }, "recommendation": { "type": "string", "enum": [ "collect_more_outcomes", "review_high_anomalies", "monitor_anomalies", "stable" ] }, "summary": { "type": "object", "properties": { "anomaly_count": { "type": "integer" }, "returned_count": { "type": "integer" }, "high_count": { "type": "integer" }, "medium_count": { "type": "integer" }, "low_count": { "type": "integer" }, "max_score": { "type": [ "number", "null" ] } }, "additionalProperties": true }, "baseline": { "type": "object", "additionalProperties": true }, "anomalies": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyAnomaly" } }, "window": { "type": "object", "additionalProperties": true }, "data_quality": { "type": "object", "additionalProperties": true }, "anomaly_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 }, "DecisionChainLink": { "type": "object", "required": [ "decision_chain_version", "chain_id", "chain_position", "leaf_hash", "merkle_root", "link_hash", "decision_id", "record_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" ] }, "previous_merkle_root": { "type": [ "string", "null" ] }, "leaf_hash": { "type": "string" }, "merkle_root": { "type": "string" }, "merkle_strategy": { "type": "string", "const": "rolling_sha256_pair_v1" }, "link_hash": { "type": "string" }, "entry_type": { "type": "string" }, "decision_id": { "type": "string" }, "record_hash": { "type": "string" }, "receipt_hash": { "type": [ "string", "null" ] }, "policy_id": { "type": [ "string", "null" ] }, "policy_version": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "verify_url": { "type": "string" }, "chain_url": { "type": "string" } }, "additionalProperties": true }, "DecisionChain": { "type": "object", "required": [ "ok", "decision_chain_version", "chain_id", "chain_size", "merkle_root", "head", "retained_links", "verification" ], "properties": { "ok": { "type": "boolean" }, "decision_chain_version": { "type": "string", "const": "decision_chain_v1" }, "chain_id": { "type": "string" }, "chain_size": { "type": "integer" }, "merkle_strategy": { "type": "string", "const": "rolling_sha256_pair_v1" }, "merkle_root": { "type": [ "string", "null" ] }, "head_link_hash": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" }, "head": { "$ref": "#/components/schemas/DecisionChainLink" }, "retained_links": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionChainLink" } }, "verification": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "DecisionExecutionRequest": { "type": "object", "required": [ "execution_status" ], "properties": { "decision_id": { "type": "string", "maxLength": 600 }, "execution_status": { "type": "string", "description": "Normalized to queued, executed, failed, skipped, reverted, blocked, reviewed, unknown, or a compact custom status." }, "execution_result": { "type": "string" }, "action_taken": { "type": "string" }, "target_system": { "type": "string" }, "target_object_id": { "type": "string" }, "mutation": { "type": "string" }, "execution_id": { "type": "string" }, "external_ref": { "type": "string" }, "executor": { "type": "object", "additionalProperties": true }, "decision_record_hash": { "type": "string" }, "decision_receipt_hash": { "type": "string" }, "action_binding": { "$ref": "#/components/schemas/ActionBinding" }, "action_binding_hash": { "type": "string" }, "state_before_hash": { "type": "string" }, "state_after_hash": { "type": "string" }, "state_before_ref": { "type": "string" }, "state_after_ref": { "type": "string" }, "evidence_refs": { "type": "array", "items": { "type": [ "object", "string" ], "additionalProperties": true } }, "executed_at": { "type": "string" }, "reported_at": { "type": "string" } }, "additionalProperties": true }, "DecisionExecution": { "type": "object", "required": [ "decision_protocol_version", "decision_execution_version", "execution_receipt_id", "decision_id", "execution_status", "execution_hash", "reported_at" ], "properties": { "decision_protocol_version": { "type": "string", "const": "decision_protocol_v1" }, "decision_execution_version": { "type": "string", "const": "decision_execution_v1" }, "execution_receipt_id": { "type": "string" }, "decision_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "execution_status": { "type": "string" }, "execution_result": { "type": "string" }, "action_taken": { "type": "string" }, "target_system": { "type": "string" }, "target_object_id": { "type": "string" }, "mutation": { "type": "string" }, "external_ref": { "type": "string" }, "execution_id": { "type": "string" }, "executor": { "type": "object", "additionalProperties": true }, "decision_record_hash": { "type": "string" }, "decision_receipt_hash": { "type": "string" }, "decision_verdict": { "type": "string" }, "decision_action": { "type": "string" }, "policy_id": { "type": "string" }, "policy_version": { "type": "string" }, "policy_bundle_hash": { "type": "string" }, "action_binding": { "$ref": "#/components/schemas/ActionBinding" }, "action_binding_hash": { "type": "string" }, "action_binding_match": { "type": [ "boolean", "null" ] }, "state_before_hash": { "type": "string" }, "state_after_hash": { "type": "string" }, "state_before_ref": { "type": "string" }, "state_after_ref": { "type": "string" }, "evidence_refs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "execution_input_hash": { "type": "string" }, "execution_hash": { "type": "string" }, "integrity": { "type": "object", "additionalProperties": true }, "executed_at": { "type": "string" }, "reported_at": { "type": "string" }, "decision_found": { "type": "boolean" }, "decision_url": { "type": "string" }, "verify_url": { "type": "string" } }, "additionalProperties": true }, "DecisionExecutionResult": { "type": "object", "required": [ "ok", "decision_id", "execution" ], "properties": { "ok": { "type": "boolean" }, "idempotency_status": { "type": "string" }, "decision_id": { "type": "string" }, "execution": { "$ref": "#/components/schemas/DecisionExecution" } }, "additionalProperties": true } } } }