POST /execute
Runs a payload through all nine pipeline stages and returns the sealed ExecutionManifest plus a server-side run_id.
Request
POST /execute
Content-Type: application/json
X-Verdifax-Key: vfx_... (required once any keys exist)
Body
The request body contains:
{
"program_id": "string, 64-char lowercase hex (required)",
"route_id": "string, non-empty (required)",
"registry_record_hash": "string, 64-char lowercase hex (required)",
"payload": "string, UTF-8 plaintext (required, or use payload_text)",
"payload_text": "string, alternative to payload (required, or use payload)",
"attested_context": "object (optional), caller-supplied attestation metadata",
"request_substance": "object (optional), AttestedContext category 1: decision facts and substance",
"authorization_chain": "object (optional), AttestedContext category 2: approvals, delegation, audit trail",
"regulatory_scaffolding": "object (optional), AttestedContext category 3: data classification, export control",
"causal_graph": "object (optional), AttestedContext category 4: side effects and external actions"
}
Payload variants: Exactly one of payload (UTF-8 string) or payload_text (alternative name for the same field) is required. All others are required.
attested_context schema (only these fields):
attested(boolean)actor_id(string)actor_role(string)authorization_policy(string)actor_signature(string, base64)model_provider(string)model_name(string)model_version(string)model_temperature(float)prompt_hash(string, 64-hex)decision_kind(string)decision_result(string)decision_note(string)
Example request (financial disbursement scenario)
{
"program_id": "64aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"route_id": "payments-disbursement-demo",
"registry_record_hash": "64bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"payload": "Evaluate payment request: $250K USD wire to vendor acme-corp for Q2 services contract #4521.",
"attested_context": {
"attested": true,
"actor_id": "tenant-demo-acme",
"actor_role": "ops_manager",
"model_provider": "openai",
"model_name": "gpt-4o-mini",
"model_version": "2024-07-18",
"model_temperature": 0.1,
"prompt_hash": "64cccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"decision_kind": "financial_disbursement",
"decision_result": "approved",
"decision_note": "vendor in approved list, amount within limit, contract exists"
},
"request_substance": {
"vendor_id": "acme-corp",
"amount_usd": 250000,
"contract_id": "4521",
"category": "professional_services"
},
"authorization_chain": {
"approvers": [
{
"order": 1,
"actor_id": "finance-team",
"actor_role": "finance_reviewer",
"approved_at": "2026-05-03T14:22:10Z",
"approved_request_hash": "64dddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"signature": "...",
"comment": "Amount authorized"
}
],
"threshold_checks": [{"name": "vendor_approved_list", "result": true}],
"human_in_loop": {
"required": true,
"performed": true,
"performed_by": "compliance-officer",
"performed_at": "2026-05-03T14:23:45Z",
"review_mode": "automated_with_exception",
"review_outcome": "approved"
}
},
"regulatory_scaffolding": {
"data_classification": {
"commercial": ["PII", "FINANCIAL_DATA"]
}
},
"causal_graph": {
"effect_log": [
{
"effect_kind": "payment_instruction",
"target": "stripe_api_v3",
"status": "queued",
"issued_at": "2026-05-03T14:24:00Z",
"ack_hash": "64eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
}
]
}
}
Response
The response shape depends on the outcome state. All responses include ok (boolean) and run_id (integer).
OK (request admitted and executed)
200 OK:
{
"ok": true,
"run_id": 63,
"duration_ms": 3,
"duration_micros": 3140,
"manifest": {
"EnvelopeID": "env-...",
"EnvelopeHash": "...",
"SequenceID": "seq-...",
"TransportHash": "...",
"EpaHash": "...",
"EfaHash": "...",
"ExecutionIDs": ["...", "...", "...", "...", "...", "..."],
"AerHash": "...",
"TranscriptHash": "...",
"HardwareAttestationHash": "...",
"LeakageBundleHash": "...",
"FormalVerifierStatus": "<formal-verifier success token, scaffold today>",
"ZkspBindingHash": "...",
"MigrationTokenHash": "...",
"ReplayFingerprint": "...",
"PoteProofHash": "...",
"LogEntryID": "rekor-...",
"RegistryArtifactCount": 18,
"FinalVfaHash": "...",
"IndependentVerified": true,
"ManifestHash": "6c1428f81519c5bb..."
},
"allow_token": {
"envelope_id": "env-...",
"fired_rule_id": "rule-default-allow",
"decision_reason_code": "POLICY_ADMITTED",
"policy_hash": "...",
"evaluation_hash": "...",
"allow_clock": "2026-05-03T14:24:00Z",
"evaluator_version": "pepg-0.3.0",
"version": "vfa.allow_token.v1",
"hash": "..."
}
}
PEPG Deny (policy rejected before execution)
200 OK with deny outcome:
{
"ok": false,
"run_id": 64,
"duration_ms": 1,
"duration_micros": 890,
"manifest": {
"EnvelopeID": "env-...",
"partial": true
},
"deny_receipt": {
"envelope_id": "env-...",
"fired_rule_id": "rule_classification_exceeded",
"decision_reason_code": "CLASSIFICATION_EXCEEDED",
"policy_hash": "...",
"evaluation_hash": "...",
"mcd_finding_hash": "",
"deny_clock": "2026-05-03T14:24:00Z",
"evaluator_version": "pepg-0.3.0",
"version": "vfa.deny_receipt.v1",
"hash": "..."
}
}
For MCD-driven denies, mcd_finding_hash is populated (non-empty string). The decision reason code will be MCD_SIGNATURE_MATCH.
CCV Halt (per-run budget breach)
200 OK with halt outcome:
{
"ok": false,
"run_id": 65,
"duration_ms": 12,
"duration_micros": 12450,
"manifest": {
"partial": true,
"halted_at_phase": "DKEC"
},
"ccv_halt_receipt": {
"envelope_id": "env-...",
"halt_reason_code": "BUDGET_EXHAUSTED",
"constraint_type": "token_budget",
"budget_limit": 100000,
"consumed_at_halt": 100045,
"budget_hash": "...",
"allow_token_hash": "...",
"partial_execution_hash": "...",
"halt_clock": "2026-05-03T14:24:12Z",
"evaluator_version": "ccv-0.3.0",
"version": "vfa.ccv_halt.v1",
"hash": "..."
}
}
MACC Halt (cumulative budget breach)
200 OK with halt outcome:
{
"ok": false,
"run_id": 76,
"duration_ms": 2,
"duration_micros": 2100,
"manifest": {
"partial": true,
"halted_at_phase": "PEPG"
},
"macc_halt_receipt": {
"envelope_id": "env-...",
"tenant_id": "tenant-demo-acme",
"halt_reason_code": "CUMULATIVE_BUDGET_EXCEEDED",
"constraint_type": "cumulative_token_budget",
"budget_limit": 1000000,
"cumulative_at_halt": 1000245,
"per_run_consumption": 250,
"window_start": "2026-05-03T00:00:00Z",
"budget_hash": "...",
"allow_token_hash": "...",
"halt_clock": "2026-05-03T14:24:00Z",
"evaluator_version": "macc-0.3.0",
"version": "vfa.macc_halt.v1",
"hash": "..."
}
}
Error responses
For validation errors and network issues:
400 Bad Request, invalid input (bad hex, missing field, malformed JSON).
401 Unauthorized, API keys are provisioned and the header is absent or invalid.
429 Too Many Requests, rate limit exceeded.
See Errors for the full envelope and stage-specific 422 responses.
Example
curl -s -X POST http://localhost:9090/execute \
-H "Content-Type: application/json" \
-H "X-Verdifax-Key: vfx_..." \
-d '{
"program_id": "64aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"route_id": "payments-disbursement-demo",
"registry_record_hash": "64bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"payload": "Evaluate payment request: $250K USD wire to vendor acme-corp for Q2 services contract #4521.",
"attested_context": {
"attested": true,
"actor_id": "tenant-demo-acme",
"actor_role": "ops_manager",
"model_provider": "openai",
"model_name": "gpt-4o-mini",
"decision_kind": "financial_disbursement",
"decision_result": "approved"
}
}' | python3 -m json.tool
Determinism
Identical inputs always produce identical responses. Same payload, same program_id, same route_id, same registry_record_hash → byte-for-byte identical ManifestHash.
Continue
- Sealed artifacts, how to fetch the outcome-specific artifacts
GET /runs/{id}/verify- Errors