Runtime API Reference

Overview

The FoxCommand Runtime API provides authenticated endpoints for governed execution, replay, simulation, comparison, and Governance RCA. Use this reference when you are ready to confirm exact request fields, response identifiers, errors, and current runtime limits.

Use the OpenAPI specification when importing the Runtime API shape into API tooling. The sequence below shows how a customer integration moves from the first governed execution to replay, simulation, comparison, and bounded attribution.

Before forming runtime requests, prepare Customer Configuration, Business Semantics, Decision Mapping, runtime credentials, and an evidence retention location. The Prior Authorization Workflow Example, Templates, and Artifact Validation Tools show how those preparation steps fit together.

Authentication

Every operational runtime POST request requires bearer authentication:

Authorization: Bearer <runtime-gateway-token>
Content-Type: application/json

The runtime validates the runtime bearer token before processing the request body. Your systems own credential storage, rotation procedures, access decisions, and log redaction. The current runtime API does not define OAuth, user management, external credential lifecycle routes, or authorization beyond this bearer-token gate.

Supported Endpoints

The customer integration workflow uses these endpoints:

Capability	Endpoint	Purpose
Governed Execution	`POST /governed-execution`	Submit a Governance Artifact or Governance Artifact reference with setup mapping and policy setup.
Replay	`POST /replay`	Replay a successful governed execution by `replay_reference`.
Simulation	`POST /simulate`	Evaluate candidate policy setup against replay-derived baseline material.
Comparison	`POST /compare`	Return structured baseline-versus-candidate evidence and a deterministic `comparison_id`.
Governance RCA	`POST /rca`	Return bounded attribution evidence for material outcome changes.

The OpenAPI specification also describes POST /execution-object and POST /execution-lineage for deployments where execution retrieval is enabled. Those retrieval endpoints are not required for the minimal integration path and may return unavailable responses when storage retrieval is not enabled.

Request Sequence

Use this sequence for the standard runtime workflow:

Call POST /governed-execution with selected information.
Store returned execution_id, contract_reference, and replay_reference.
Call POST /replay with replay_reference to verify the baseline.
Call POST /simulate with replay_reference and candidate_policy_setup to evaluate a candidate policy.
Call POST /compare with the same replay reference and candidate policy setup when structured evidence is needed.
Call POST /rca when bounded Governance RCA attribution is needed.

Minimal Governed Execution

POST /governed-execution requires either governance_artifact or governance_artifact_reference, plus setup_mapping and customer_policy_setup.

{
  "api_version": "v1",
  "governance_artifact": {
    "artifact_id": "GOV-RCM-PA-SYN-001",
    "source_operational_input_id": "RCM-PA-SYN-001",
    "review_context": {
      "requested_action": "review_for_policy_enforcement",
      "risk_level": "medium"
    },
    "policy_inputs": {
      "required_controls": ["site_of_care_review"]
    },
    "lineage": {},
    "data_classification": {
      "contains_phi": false,
      "contains_real_customer_data": false,
      "synthetic_only": true
    }
  },
  "setup_mapping": {
    "mapping_id": "mapping-prior-auth-review-v1",
    "mapping_version": "v1",
    "target_surface": "PRIOR_AUTH_REVIEW_v1",
    "surface_signal_mapping": {
      "review_disposition": {
        "source_path": "review_context.requested_action",
        "target_value": "requires_human_review"
      }
    }
  },
  "customer_policy_setup": {
    "policy_id": "policy-synthetic-prior-auth",
    "policy_version": "v1",
    "target_surface": "PRIOR_AUTH_REVIEW_v1",
    "rules": [
      {
        "rule_id": "review-required",
        "conditions": {
          "op": "EQUALS",
          "signal": "review_disposition",
          "value": "requires_human_review"
        },
        "outcome": "requires_human_review"
      }
    ]
  }
}

Successful response:

{
  "api_version": "v1",
  "execution_id": "exec-PRIOR_AUTH_REVIEW_v1-GOV-RCM-PA-SYN-001-policy-synthetic-prior-auth-v1",
  "status": "succeeded",
  "governed_outcome": {
    "result": "requires_human_review"
  },
  "references": {
    "surface": "PRIOR_AUTH_REVIEW_v1",
    "policy_id": "policy-synthetic-prior-auth",
    "policy_version": "v1",
    "source_artifact_id": "GOV-RCM-PA-SYN-001",
    "source_operational_input_id": "RCM-PA-SYN-001",
    "contract_reference": "contract-prior_auth_review_v1__GOV-RCM-PA-SYN-001__policy-synthetic-prior-auth__v1",
    "replay_reference": "replay-contract-prior_auth_review_v1__GOV-RCM-PA-SYN-001__policy-synthetic-prior-auth__v1"
  },
  "metadata": {
    "lineage": {},
    "data_classification": {
      "contains_phi": false,
      "contains_real_customer_data": false,
      "synthetic_only": true
    },
    "provenance_available": true
  },
  "errors": []
}

Replay Request

Use the replay_reference returned by governed execution:

{
  "replay_reference": "replay-contract-prior_auth_review_v1__GOV-RCM-PA-SYN-001__policy-synthetic-prior-auth__v1"
}

Successful Replay returns status, replay_status, execution_id, contract_reference, replay_outcome, and errors.

Candidate Policy Requests

POST /simulate, POST /compare, and POST /rca all use a replay reference plus candidate policy setup:

{
  "replay_reference": "replay-contract-prior_auth_review_v1__GOV-RCM-PA-SYN-001__policy-synthetic-prior-auth__v1",
  "candidate_policy_setup": {
    "policy_id": "candidate-more-info",
    "policy_version": "candidate-v1",
    "target_surface": "PRIOR_AUTH_REVIEW_v1",
    "rules": [
      {
        "rule_id": "candidate-more-info-rule",
        "conditions": {
          "op": "EQUALS",
          "signal": "review_disposition",
          "value": "requires_human_review"
        },
        "outcome": "request_more_information"
      }
    ],
    "outcome_references": {
      "request_more_information": {
        "surface_outcome_reference": "request_more_information"
      }
    }
  }
}

Comparison may also include customer correlation metadata:

{
  "replay_reference": "replay-contract-prior_auth_review_v1__GOV-RCM-PA-SYN-001__policy-synthetic-prior-auth__v1",
  "candidate_policy_setup": {
    "policy_id": "candidate-more-info",
    "policy_version": "candidate-v1",
    "target_surface": "PRIOR_AUTH_REVIEW_v1",
    "rules": [
      {
        "conditions": {
          "op": "EQUALS",
          "signal": "review_disposition",
          "value": "requires_human_review"
        },
        "outcome": "request_more_information"
      }
    ]
  },
  "customer_correlation_metadata": {
    "experiment_id": "customer-exp-001",
    "customer_case_id": "customer-case-001"
  }
}

Comparison returns schema_version: "comparison.v1", comparison_id, replay relationship fields, comparison_result, and any supplied customer_correlation_metadata unchanged.

Identifier Meanings

execution_id identifies runtime execution evidence.
contract_reference identifies runtime contract evidence where returned; it is not access to a contract body.
replay_reference identifies replay material created by governed execution and used by later workflow calls.
comparison_id identifies deterministic Comparison evidence. It is derived from comparison material and candidate policy setup, not from customer correlation metadata.

Policy Rule Shape

Policy setup includes policy_id, policy_version, target_surface, and rules. Each rule includes conditions and outcome; rule_id is customer-visible metadata.

Supported condition operators include:

EQUALS with signal and value.
NOT_EQUALS with signal and value.
AND with a non-empty nested conditions list.
OR with a non-empty nested conditions list.

Use precedence when candidate rules can conflict. Use default_outcome when the policy should produce a fallback outcome.

Error Handling

Runtime responses return bounded errors when submitted material is missing, malformed, unsupported, unknown, non-admissible, or cannot be validated.

Common status concepts include:

Governed Execution: succeeded, non_admissible, unsupported_surface, unsupported_version, validation_failed.
Replay: succeeded, invalid, not_found, invalid_material, validation_failed.
Simulation: succeeded, invalid, not_found, invalid_material, invalid_candidate_policy, non_admissible, validation_failed.
Governance RCA: succeeded, failed.

Use errors to correct request material or preparation. Do not depend on execution bodies, stored replay material, service logs, cached outputs, tracebacks, module names, or non-response runtime details.

Current Limits

The current runtime API is a bounded validation surface. It does not define production hosting, OAuth, SDKs, user management, tenancy, billing, quotas, storage retention, backup restore behavior, public internet safety, durable simulation storage, durable RCA storage, or lifecycle automation.

Replay, Simulation, Comparison, and Governance RCA depend on replay material created by successful governed execution. Replay references from prior runtime sessions are not guaranteed to resolve unless the deployment preserves the replay material.

Runtime Workflow

Use this API sequence when your required material, runtime credentials, and replay evidence are available for the next capability call. Use the runtime request and response examples to compare concrete payloads, and use the OpenAPI specification when importing the Runtime API shape into API tooling.