API Reference

Krapheno REST API

The Krapheno API enforces AI decision governance at runtime. External AI systems (Krudis) submit decisions for policy evaluation, receive ALLOW / ESCALATE / BLOCK verdicts, and inscribe results permanently to the SmritiTree hash chain.

Base URL: https://api.krapheno.comAuth: x-api-key headerFormat: application/json

Three-Step Agent Registration Sequence

External AI systems must follow this exact sequence. Calls out of order will fail.

1. POST /register-intent → returns intent_id (legislative key required)

2. POST /register-capabilities → declares agent capability scope

3. POST /agents/run → activates the governed agent session

POST/register-intentLegislative API key

Declare an agent intent before any decision is proposed. Returns an intent_id that must accompany all subsequent decisions in this governance session.

Request Body

{
  "agency_id": "string",
  "description": "string"        // human-readable intent description
}

Response

{
  "intent_id": "string",         // attach to all decisions in this session
  "created_at": "ISO 8601"
}

Notes

Required first call in the three-step agent registration sequence. Intent declaration creates the governance context within which decisions are evaluated.

POST/decisions/proposeAgency API key

Propose a decision for policy evaluation. SmritiTree evaluates the payload against thresholds.md and returns a verdict before any execution occurs.

Request Body

{
  "intent_id": "string",
  "decision_type": "string",     // e.g. "budget_change", "targeting_change"
  "payload": {
    // decision-specific parameters
    // e.g. for budget_change:
    "change_pct": 20,
    "confidence": 0.91,
    "sample_size": 1200
  },
  "agent_id": "string"
}

Response

{
  "verdict": "ALLOW | ESCALATE | BLOCK",
  "decision_node_id": "string",
  "mic_fired": boolean,
  "mic_conditions": [
    {
      "mic_id": "MIC-01",
      "condition": "string",
      "passed": boolean
    }
  ],
  "governance_utilization": number   // 0–100, how close to policy boundary
}

Notes

This is the policy enforcement point. Verdicts are deterministic — same payload against same policy version always produces same verdict. The governance_utilization score distinguishes confident decisions (low utilization) from marginal ones (high utilization).

POST/v1/decisions/inscribeAgency API key

Write a governed decision permanently to the SmritiTree hash chain. Returns the decision_id and record_hash proving the record exists at this point in the chain.

Request Body

{
  "intent_id": "string",
  "decision_node_id": "string",  // from /decisions/propose response
  "verdict": "ALLOW | ESCALATE | BLOCK",
  "payload": { },                // same payload submitted to propose
  "agent_id": "string",
  "agency_id": "string"
}

Response

{
  "decision_id": "string",       // e.g. "dec_57ee07f6..."
  "record_hash": "string",       // SHA-256 hash of this node
  "prior_hash": "string",        // SHA-256 hash of the preceding node
  "mic_fired": boolean,
  "verdict": "ALLOW | ESCALATE | BLOCK",
  "inscribed_at": "ISO 8601"
}

Notes

The record_hash and prior_hash together prove chain integrity. Any modification to a historical record invalidates all subsequent hashes. The governance_utilization row is populated on every inscribe call.

GET/v1/client/:token/summaryClient portal token

Retrieve the governed decision summary for a client portal. Returns recent decisions, verdicts, and governance statistics visible to the agency operator.

Response

{
  "agency_id": "string",
  "decisions_this_month": number,
  "total_decisions": number,
  "false_winners_caught": number,
  "recent_decisions": [
    {
      "decision_id": "string",
      "verdict": "ALLOW | ESCALATE | BLOCK",
      "decision_type": "string",
      "reasoning": "string",
      "record_hash": "string",
      "created_at": "ISO 8601"
    }
  ]
}

Notes

The :token is a client-scoped read key. It provides no write access.

GET/v1/decisions/:id/forensicsAgency API key

Retrieve the full forensic audit record for a single governed decision. Returns verdict, all MIC conditions evaluated, governance utilization score, and hash proof.

Response

{
  "decision_id": "string",
  "verdict": "ALLOW | ESCALATE | BLOCK",
  "decision_type": "string",
  "payload": { },
  "mic_conditions": [
    {
      "mic_id": "string",
      "label": "string",
      "threshold": number,
      "actual_value": number,
      "passed": boolean
    }
  ],
  "governance_utilization": number,
  "record_hash": "string",
  "prior_hash": "string",
  "inscribed_at": "ISO 8601",
  "intent_id": "string",
  "agent_id": "string"
}

Notes

Use this endpoint to explain any non-ALLOW verdict. The mic_conditions array identifies exactly which constraint fired and the actual value that triggered it. The record_hash provides cryptographic proof the record has not been modified since inscription.

GET/v1/governance/efficiency/:agency_idAgency API key

Retrieve the Governance Efficiency Score for an agency. Aggregates utilization across all governed decisions to produce a single performance signal.

Response

{
  "agency_id": "string",
  "efficiency_score_pct": number,  // 0–100
  "amber_band_pct": number,        // % of decisions in 60–85% utilization range
  "total_decisions_scored": number,
  "period": "string"
}

Notes

The amber band (60–85% utilization) represents optimal governance — the agent operates confidently within policy without excessive conservatism. Scores consistently below 40% suggest overly loose policy. Scores consistently above 90% suggest the agent is operating at its limits.

POST/escalations/:threadId/resolveAgency API key

Resolve a human review thread. Approve or reject a decision that received an ESCALATE verdict. The resolution is recorded permanently in SmritiTree.

Request Body

{
  "resolution": "APPROVE | REJECT",
  "resolved_by": "string",         // human actor identifier
  "notes": "string"                // optional resolution reasoning
}

Response

{
  "thread_id": "string",
  "resolution": "APPROVE | REJECT",
  "resolved_at": "ISO 8601",
  "record_hash": "string"          // hash of the resolution node
}

Notes

Human overrides are themselves governed — the resolution is inscribed to SmritiTree with its own hash node. This preserves the causal chain: original decision → ESCALATE verdict → human resolution → final outcome.

Ready to govern your first decision?

The live demo portal shows real governed decisions from the SmritiTree hash chain.

Open Live Demo Learn the Concepts