API Documentation

Chromia Verified AI Insurance API

Quick Start

Integrate your AI agent with Atbash Dashboard in 3 steps. Every action your agent takes will be judged for safety, scored, and recorded immutably on the Chromia blockchain.

1

Submit Actions

POST to /judge with each action your agent takes

2

Get Verdicts

Receive GREEN/YELLOW/RED safety verdicts in real-time

3

Pull Reports

GET risk reports and incident timelines via /insurance

Submit Action for Safety Judgment

POST/.netlify/functions/judge

Submit an AI agent action for on-chain safety evaluation. Returns a verdict (GREEN/YELLOW/RED) with reasoning. Cached actions return instantly; uncached actions take 5-30 seconds.

Request Body

json
{
  "action": {
    "action": "Send email to user@example.com with order confirmation",
    "context": "E-commerce checkout flow"
  },
  "publicKey": "03c1f231e767f93212f2e474ac3145ae50923bddce53e069548d4d11b851be4378"
}

Request Fields

FieldTypeDescription
action.action*stringThe action text to evaluate (max 1000 chars)
action.contextstringOptional context for the action (max 1000 chars)
publicKeystring66-char hex secp256k1 pubkey for ECIES encryption

Response (200)

json
{
  "status": "answered",
  "verdict": "green",
  "reason": "Action is a standard email...",
  "judgmentId": "j-a1b2c3d4-...",
  "onChain": true,
  "cached": false,
  "responseTimeMs": 4200
}
Security Note

If you provide a publicKey, the action text is ECIES-encrypted before storage on-chain. Only the holder of the corresponding private key can decrypt it. The AI still evaluates the plaintext for safety — encryption protects the data at rest on the blockchain.

Poll for Verdict

GET/.netlify/functions/judge?id={judgmentId}

If the POST returns status: "pending", poll this endpoint every 2 seconds until the verdict is ready.

bash
curl "https://chromia-verified-ai-chat.netlify.app/.netlify/functions/judge?id=j-a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Insurance API

Read-only endpoints for risk reports, agent scores, and incident timelines. All data is queried directly from the Chromia blockchain.

Agent Risk Report

GET/.netlify/functions/insurance?action=agent-report&agent={pubkey}

Full insurance-ready risk report for a single agent. Includes verdict breakdown, risk score, average response time, and policy details.

bash
curl "https://chromia-verified-ai-chat.netlify.app/.netlify/functions/insurance?action=agent-report&agent=03c1f231e767f93212f2e474ac3145ae50923bddce53e069548d4d11b851be4378"

Organization Risk Report

GET/.netlify/functions/insurance?action=org-report&org={name}&pubkey={requester}

Aggregate risk report across all agents in an organization. Requires org admin pubkey for authorization.

bash
curl "https://chromia-verified-ai-chat.netlify.app/.netlify/functions/insurance?action=org-report&org=acme-corp&pubkey=03c1f231..."

Agent Incident Timeline

GET/.netlify/functions/insurance?action=agent-incidents&agent={pubkey}&limit=50

Chronological list of all YELLOW and RED incidents for an agent. Essential for insurance claims evidence.

bash
curl "https://chromia-verified-ai-chat.netlify.app/.netlify/functions/insurance?action=agent-incidents&agent=03c1f231...&limit=50"

Agent Score

GET/.netlify/functions/insurance?action=agent-score&agent={pubkey}

Quick lookup of an agent's current risk score and verdict counts.

Platform Safety Stats

GET/.netlify/functions/insurance?action=safety-stats

Global platform statistics: total judgments, verdict distribution, cache performance.

Integration Example

Here's how to integrate safety checks into your AI agent's action pipeline:

typescript
// Before your agent executes any action:
async function safeAction(action: string, context: string) {
  const res = await fetch("https://chromia-verified-ai-chat.netlify.app/.netlify/functions/judge", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      action: { action, context },
      publicKey: YOUR_AGENT_PUBKEY, // optional ECIES encryption
    }),
  });
  const data = await res.json();

  // If pending, poll until resolved
  if (data.status === "pending") {
    let verdict = null;
    for (let i = 0; i < 30; i++) {
      await new Promise(r => setTimeout(r, 2000));
      const poll = await fetch(`https://chromia-verified-ai-chat.netlify.app/.netlify/functions/judge?id=${data.judgmentId}`);
      const result = await poll.json();
      if (result.status === "answered") { verdict = result; break; }
    }
    if (!verdict) return { allowed: false, reason: "Safety check timed out" };
    return { allowed: verdict.verdict !== "red", verdict };
  }

  return { allowed: data.verdict !== "red", verdict: data };
}

// Usage in your agent:
const check = await safeAction(
  "Transfer $500 to account ending in 4321",
  "User requested wire transfer via chat"
);
if (!check.allowed) {
  console.log("Action blocked:", check.verdict.reason);
  return; // Don't execute
}
// Proceed with action...

Direct Blockchain Queries

You can also query the Chromia blockchain directly using the postchain-client SDK. This bypasses the Netlify API and gives you access to all on-chain data.

typescript
import { createClient } from "postchain-client";

const client = await createClient({
  nodeUrlPool: "https://node6.testnet.chromia.com:7740",
  blockchainRid: "633EE395FFE3B6FE6E9112A6E0523BAA15495AD01FE26AB617F7EF79C8E17446",
});

// Get agent risk report
const report = await client.query("get_agent_risk_report", {
  agent_pubkey: Buffer.from("03c1f231...", "hex"),
});

// Get incident timeline
const incidents = await client.query("get_agent_incident_timeline", {
  agent_pubkey: Buffer.from("03c1f231...", "hex"),
  max_count: 50,
});

// Get org-level report (requires org admin auth)
const orgReport = await client.query("get_org_risk_report", {
  org_name: "acme-corp",
  requester_pubkey: Buffer.from("03c1f231...", "hex"),
});

Blockchain RID: 633EE395FFE3B6FE6E9112A6E0523BAA15495AD01FE26AB617F7EF79C8E17446

DashboardHome