API Reference

Gate a request through OPA policy. If allowed, mints a TrustAtom™ (Ed25519-signed, SHA-256 hashed receipt) and writes to Neo4j. If denied, returns the policy reasoning with no TrustAtom.

{
  "env": "SANDBOX",
  "tenant_id": "demo-tenant",
  "decision_id": "dec_001",
  "principal_id": "human_tester",
  "agent_id": "agent_gatekeeper",
  "action": "READ_EVIDENCE",
  "resource_id": "neo4j:trustgraph",
  "request_category": "GRAPH_READ"
}

{
  "input": { "action": "READ_EVIDENCE", "request_category": "GRAPH_READ", "..." },
  "decision": {
    "decision": "ALLOW",
    "reasons": ["action_in_safe_categories"],
    "policy_version": "sandbox-fallback-v1"
  },
  "trustatom": {
    "id": "ta_c7f2a1b3",
    "evidence_hash": "8a4f2e...d901c3",
    "signature_b64": "XkL9bQ...72NjYw==",
    "minted_at": "2026-02-26T13:56:40Z"
  },
  "neo4j": { "written": true },
  "timing": { "gate_ms": 12, "sign_ms": 3, "graph_ms": 8, "total_ms": 23 }
}

{
  "input": { "action": "EXPORT_INTEGRATION", "..." },
  "decision": {
    "decision": "DENY",
    "reasons": ["action_not_in_safe_categories"],
    "policy_version": "sandbox-fallback-v1"
  },
  "trustatom": null,
  "neo4j": { "written": false }
}

Verify the Ed25519 signature and SHA-256 evidence hash of a TrustAtom receipt. Can be called by auditors independently — no knowledge of the private key required.

{
  "evidence_hash": "8a4f2e...d901c3",
  "signature_b64": "XkL9bQ...72NjYw==",
  "receipt_payload": { "..." }
}

{
  "ok": true,
  "signature": { "valid": true, "algorithm": "Ed25519" },
  "evidence_hash": {
    "match": true,
    "expected": "8a4f2e...d901c3",
    "computed": "8a4f2e...d901c3"
  }
}

Parse a natural language query into a structured IntentPacket. Uses weighted phrase matching (no LLM required).

{ "text": "Show me denied decisions from the last 7 days" }

{
  "ok": true,
  "intent": {
    "intent_type": "query_trust_graph",
    "confidence": 0.85,
    "text": "Show me denied decisions from the last 7 days",
    "scope_constraints": { "time_range": "7d", "decision_type": "DENY" },
    "clarifications_needed": []
  }
}

A²C Collaborative Exploration — Claude investigates trust decisions and explains policy reasoning in natural language. Supports streaming (SSE) and full-response modes.

{ "text": "Why was EXPORT_INTEGRATION denied?", "output_format": "stream" }

data: {"chunk": "Looking at decision dec_0x4f21..."}
data: {"chunk": " The policy gate evaluated your request..."}
data: [DONE]

{ "text": "Why was EXPORT_INTEGRATION denied?", "output_format": "full" }

{ "ok": true, "response": "The EXPORT_INTEGRATION action was denied because..." }

Generate a policy explanation for a specific decision by ID. Returns human-readable reasoning plus compliance framework alignment.

{
  "decision_id": "dec_001",
  "mode": "why_allowed"
}

Modes: why_allowed · why_denied · constraints · similar_decisions

{
  "ok": true,
  "explanation": {
    "summary": "READ_EVIDENCE was allowed under sandbox-fallback-v1 because the action falls within GRAPH_READ safe categories.",
    "policy_rules": ["action_in_safe_categories", "request_category_allowed"],
    "compliance_alignment": {
      "nist_csf": ["PR.AC-1: Access control enforced"],
      "soc2": ["CC6.1: Logical access controls"]
    }
  }
}

Dashboard counts — total decisions, allow/deny split, TrustAtom count, principal and agent counts.

{
  "ok": true,
  "decision_count": 127,
  "allowed_count": 119,
  "denied_count": 8,
  "trustatom_count": 119,
  "principal_count": 5,
  "agent_count": 3
}

Recent decisions with TrustAtom IDs, ordered by timestamp descending. Query param: limit (default 20, max 100).

Denied decisions with policy reasoning. Query param: limit (default 20, max 100).

Full lineage for a single decision: Decision node + linked TrustAtom + PolicyEvaluation + DecisionTrace + Principal + Agent.

Time-range filtered decisions with DCT metadata. Defaults to last 24 hours if no range given.

Query params: since_ms · until_ms · limit (default 100)

{
  "ok": true,
  "decisions": [{
    "decision_id": "dec_001",
    "action": "READ_EVIDENCE",
    "decision": "ALLOW",
    "timestamp_ms": 1740488200000,
    "dct_env": "SANDBOX",
    "dct_risk_score": 0.05,
    "dct_compliance_tags": "NIST:ID,NIST:DE,SOC2:CC6.1"
  }],
  "count": 1,
  "range": { "since_ms": 1740401800000, "until_ms": 1740488200000 }
}

Per-agent decision statistics: total, allow count, deny count, deny rate. Query param: limit (default 20).

{
  "ok": true,
  "agents": [{
    "agent_id": "agent_gatekeeper",
    "total": 50,
    "allowed": 42,
    "denied": 8,
    "deny_rate": 0.16
  }]
}

Decisions with DCT risk score above threshold — anomaly surface for security review. Query params: threshold (default 0.7) · limit (default 50).

{
  "ok": true,
  "decisions": [{
    "decision_id": "dec_003",
    "action": "DEPLOY",
    "dct_risk_score": 0.9,
    "decision": "DENY"
  }],
  "threshold": 0.7
}

Which compliance framework tags are most covered by decisions — shows audit coverage distribution.

{
  "ok": true,
  "coverage": [
    { "tag": "NIST:ID", "count": 45 },
    { "tag": "SOC2:CC6.1", "count": 38 },
    { "tag": "MITRE:T1078", "count": 12 }
  ]
}

DCT parent→child chain traversal. Follows dct_parent_decision_id links to reconstruct the full causal chain of decisions.

{
  "ok": true,
  "root": "dec_parent_001",
  "chain": [
    { "decision_id": "dec_parent_001", "action": "GRAPH_READ", "decision": "ALLOW" },
    { "decision_id": "dec_child_002", "action": "CODE_GENERATION", "decision": "ALLOW" }
  ],
  "depth": 2
}

Autonomous code generation — gates the task through OPA policy, calls the Claude API, and mints a TrustAtom for the generated code artifact.

{
  "task": "Write a function to validate email addresses",
  "constraints": { "language": "python", "max_lines": 50 },
  "mutations": 3,
  "env": "SANDBOX",
  "tenant_id": "demo-tenant",
  "principal_id": "human_dev",
  "agent_id": "claude_code_agent"
}

{
  "status": "OK",
  "envelope": { "code": "def validate_email(email: str)...", "tests": "..." },
  "gate_decision": { "decision": "ALLOW", "policy_version": "sandbox-fallback-v1" },
  "trustatom": { "id": "ta_...", "evidence_hash": "...", "signature_b64": "..." }
}

Map raw event telemetry to NICE/MITRE skill types for workforce competency tracking.

{
  "events": [
    { "event_type": "port_scan" },
    { "event_type": "phishing_email" },
    { "event_type": "lateral_movement" }
  ]
}

{ "ok": true, "mapped": [ "..." ], "unmapped_count": 0 }

List all available test scenarios from the /app/scenarios directory.

Execute all scenarios against the policy engine and return aggregate results.

Run both a DENY and an ALLOW evaluation in one call — mints a TrustAtom for the ALLOW case. Useful for testing the full pipeline without building a request body.

{
  "deny": { "input": { "..." }, "decision": { "decision": "DENY", "..." } },
  "allow": {
    "input": { "..." },
    "decision": { "decision": "ALLOW", "..." },
    "trustatom": { "id": "ta_...", "signature_b64": "...", "..." }
  }
}

Health check. Returns service status and degradation mode of each dependency.

{ "ok": true, "service": "cwn-app", "version": "v4", "neo4j": "ok", "opa": "ok" }