Governance

Memory audit trails, compliance scanning, and executive dashboards.

Endpoints

Method	Path	Auth	Description
GET	/v1/governance/memory/audit	API Key	Memory change history
GET	/v1/governance/memory/stats	API Key	Operation counts by type
GET	/v1/governance/memory/compliance	API Key	PII and policy scan
GET	/v1/governance/sleep-time/report	API Key	Sleep-time refinement history
GET	/v1/governance/summary	API Key	Executive dashboard
POST	/v1/governance/policy/dry-run	API Key	Policy dry-run evaluation
GET	/v1/governance/lineage/{request_id}	API Key	The WHY answer for one request
GET	/v1/governance/lineage	API Key	Trace/request reconstruction
GET	/v1/governance/audit/chain/verify	API Key	Hash-chain + provenance verify

Policy dry-run

Evaluate a policy context against the tenant's current ruleset without enforcement. Useful for testing policies before activating them.

curl -X POST "https://api.brainstormrouter.com/v1/governance/policy/dry-run" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{"action": "POST:/v1/chat/completions", "agentId": "agent-007", "modelName": "gpt-4"}'

Request body

Field	Type	Required	Description
action	string	Yes	Action string
actor	object	No	{ type, id } actor identity
target	string	No	Target resource path
category	string	No	Category (e.g., routing)
agentId	string	No	Agent identifier
toolName	string	No	Tool name
modelName	string	No	Model name

Response

{
  "decision": "deny",
  "matchedRule": {
    "id": "deny-gpt4",
    "description": "Block GPT-4 usage",
    "action": "deny"
  },
  "ruleCount": 3,
  "mode": "active"
}

Returns decision: "allow" with matchedRule: null when no rules match or no ruleset is configured.

Memory audit

Query the full change history for memory operations.

curl "https://api.brainstormrouter.com/v1/governance/memory/audit?limit=50&operation=append" \
  -H "Authorization: Bearer br_live_..."

Query parameters

Param	Type	Default	Description
memory_key	string	tenant ID	Memory scope
limit	number	100 (max 500)	Results to return
since	number	—	Unix timestamp (ms)
operation	string	—	Filter: append, replace, delete, pin, evict

Response

{
  "entries": [
    {
      "id": "audit-uuid",
      "timestamp": "2025-02-20T10:30:00.000Z",
      "operation": "append",
      "block": "human",
      "entry_id": "entry-uuid",
      "fact_after": "User prefers dark mode",
      "actor": "agent",
      "reason": "Extracted from conversation"
    }
  ],
  "count": 1
}

Compliance scan

curl https://api.brainstormrouter.com/v1/governance/memory/compliance \
  -H "Authorization: Bearer br_live_..."

{
  "total_entries": 42,
  "violations_found": 1,
  "compliant": false,
  "violations": [
    {
      "entry_id": "entry-uuid",
      "block": "general",
      "fact_preview": "Contact email is john@example...",
      "issues": ["possible_email"]
    }
  ]
}

Executive summary

curl https://api.brainstormrouter.com/v1/governance/summary \
  -H "Authorization: Bearer br_live_..."

{
  "memory": {
    "total_entries": 42,
    "pinned_entries": 5,
    "blocks": [
      { "block": "human", "entries": 12, "limit": 50, "utilization": 24 },
      { "block": "project", "entries": 18, "limit": 50, "utilization": 36 }
    ],
    "pii_violations": 1,
    "compliant": false
  },
  "activity_24h": { "append": 8, "replace": 2, "delete": 1 }
}

Sleep-time report

curl "https://api.brainstormrouter.com/v1/governance/sleep-time/report?since=1708387200000" \
  -H "Authorization: Bearer br_live_..."

Decision lineage

Durable, tamper-evident decision lineage bound to the audit chain. See Committed Lineage for the model and Decision Provenance — Chain Payload v2 for the normative commitment + test vectors. All three routes require governance.read.

The WHY answer

GET /v1/governance/lineage/{request_id} returns the committed audit row's verified block (chain hashes + a provenance recompute), the synchronous policy_context deny reason, the Inc 3 grant_context pointer, the durable lineage row + its causal neighbors, the coverage enum, and any anomalies. The response echoes the request's traceparent and x-br-request-id headers.

curl "https://api.brainstormrouter.com/v1/governance/lineage/req_01HXXXXXX" \
  -H "Authorization: Bearer br_live_..."

{
  "request_id": "req_01HXXXXXX",
  "coverage": "captured",
  "verified": {
    "outcome": "denied",
    "event_hash": "…",
    "chain_schema_version": 2,
    "provenance_check": "ok",
    "provenance_digest": "b96591a0…",
    "trace_id": "0af7651916cd43dd8448eb211c80319c",
    "edge_provenance": "caller_asserted",
    "trace_inbound_trusted": false
  },
  "policy_context": { "reason_code": "scope_denied", "deny_rule": "no-gpt4" },
  "grant_context": null,
  "lineage": { "binding": "bound", "edge_label": "verified", "...": "..." },
  "causal_neighbors": [],
  "anomalies": ["authority_without_causation"]
}

coverage ∈ captured | sampled_out | dropped | aggregated | pre_rollout | expired_by_retention. provenance_check ∈ ok | redacted | missing_lineage | expired_by_retention | sampled_out | failed.

Trace / request reconstruction

GET /v1/governance/lineage?trace_id=… (or ?request_id=…) reconstructs a causal episode ordered by span parentage. Every record carries an edge_label (verified | claimed | unverified) derived from the row's committed fields — one wire shape in all modes. Add ?live=true to read the recent in-memory ring buffer through the same mapper.

curl "https://api.brainstormrouter.com/v1/governance/lineage?trace_id=0af7651916cd43dd8448eb211c80319c" \
  -H "Authorization: Bearer br_live_..."

Chain + provenance verify

GET /v1/governance/audit/chain/verify verifies the hash chain and adds per-row provenanceChecks[] recomputing provenanceDigest from the stored columns + the bound lineage bytes. The provenance recompute is best-effort and never flips the chain result.