API Reference

Real-time governance, compliance, and observability for autonomous AI agents. Evaluate every tool call before execution. Enforce custom policies. Detect multi-step threats. Stay audit-ready.

curl -s https://api.airg.nov-tia.com/health | jq .
# → { "status": "healthy", "version": "0.3.0" }

curl -s -X POST https://api.airg.nov-tia.com/actions/evaluate \
  -H "X-API-Key: airg_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "shell",
    "args": {"command": "rm -rf /"},
    "context": {"agent_id": "my-agent"}
  }' | jq .

# Python
pip install airg-client

# TypeScript
npm install @airg/governor-client

TOKEN=$(curl -s -X POST https://api.airg.nov-tia.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"your-username","password":"your-password"}' | jq -r .access_token)

import governor_client
from governor_client import evaluate_action, GovernorBlockedError

governor_client.GOVERNOR_URL = "https://api.airg.nov-tia.com"
governor_client.GOVERNOR_API_KEY = "airg_your_key_here"

try:
    decision = evaluate_action("shell", {"command": "ls -la"}, context={
        "agent_id": "my-agent",
        "session_id": "session-123",
        "allowed_tools": ["shell", "http_request", "file_read"],
    })
    print(f"{decision['decision']} — risk {decision['risk_score']}")
except GovernorBlockedError as e:
    print(f"Blocked: {e}")  # Do NOT execute

import { GovernorClient, GovernorBlockedError } from "@airg/governor-client";

const gov = new GovernorClient({
  baseUrl: "https://api.airg.nov-tia.com",
  apiKey: "airg_your_key_here",
});

try {
  const d = await gov.evaluate("shell", { command: "ls -la" }, {
    agent_id: "my-agent",
    allowed_tools: ["shell", "http_request"],
  });
  console.log(`${d.decision} — risk ${d.risk_score}`);
} catch (err) {
  if (err instanceof GovernorBlockedError) {
    console.error("Blocked:", err.message);
  }
}

GovernorClient gov = new GovernorClient.Builder()
    .baseUrl("https://api.airg.nov-tia.com")
    .apiKey("airg_your_key_here")
    .build();

try {
    GovernorDecision d = gov.evaluate("shell", Map.of("command", "ls -la"));
    System.out.println(d.getDecision() + " — risk " + d.getRiskScore());
} catch (GovernorBlockedError e) {
    System.err.println("Blocked: " + e.getMessage());
}

curl -s -X POST https://api.airg.nov-tia.com/actions/evaluate \
  -H "X-API-Key: airg_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "http_request",
    "args": {"method": "POST", "url": "https://api.example.com/data"},
    "context": {"agent_id": "data-agent", "allowed_tools": ["http_request"]}
  }' | jq .

curl -s -X POST https://api.airg.nov-tia.com/actions/verify \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action_id": 42,
    "tool": "file_write",
    "result": {
      "status": "success",
      "output": "Wrote 150 lines to config.py"
    },
    "context": {"agent_id": "my-agent"}
  }' | jq .

decision = evaluate_action("shell", {"command": "ls"}, context={
    "agent_id": "my-agent",
    "conversation_id": "conv-abc-123",
    "turn_id": 1,
    "prompt": "User asked me to list directory contents"
})

curl -s -X POST https://api.airg.nov-tia.com/conversations/turns/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {"conversation_id":"conv-123","turn_number":1,"role":"user","content":"List /tmp"},
    {"conversation_id":"conv-123","turn_number":2,"role":"assistant","content":"Running shell tool"}
  ]' | jq .

curl -s -X POST https://api.airg.nov-tia.com/traces/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spans": [
      {"trace_id":"t-001","span_id":"root","name":"Research Task","kind":"agent",
       "start_time":"2026-02-28T12:00:00Z","end_time":"2026-02-28T12:00:05Z"},
      {"trace_id":"t-001","span_id":"llm-1","parent_span_id":"root",
       "name":"GPT-4 reasoning","kind":"llm",
       "start_time":"2026-02-28T12:00:01Z","end_time":"2026-02-28T12:00:03Z"}
    ]
  }' | jq .

# Terminal
curl -N -H "Authorization: Bearer $TOKEN" \
  https://api.airg.nov-tia.com/actions/stream

# JavaScript
const es = new EventSource(
  "https://api.airg.nov-tia.com/actions/stream?token=" + jwt
);
es.addEventListener("action_evaluated", (e) => {
  const { tool, decision, risk_score } = JSON.parse(e.data);
  console.log(`${tool}: ${decision} (risk ${risk_score})`);
});

- policy_id: shell-dangerous
  description: "Block destructive shell commands"
  tool: "shell"
  severity: critical
  action: block
  args_regex: "(rm\\s+-rf|mkfs|dd\\s+if=|shutdown|reboot)"

curl -s -X PATCH https://api.airg.nov-tia.com/policies/governance-mode \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"governance_mode": "deny-by-default"}' | jq .

curl -s -X POST https://api.airg.nov-tia.com/policies/allowlist \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": ["search_kb", "summarize", "send_email"],
    "agent_id": "support-agent-1",
    "note": "Approved tools for customer support workflow"
  }' | jq .

curl -s -X PUT https://api.airg.nov-tia.com/policies/severity-weights \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "blast_radius": 0.40,
    "reversibility": 0.30,
    "data_sensitivity": 0.30
  }' | jq .

curl -s -X POST https://api.airg.nov-tia.com/policies/severity/calculate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "blast_radius": 90,
    "reversibility": 70,
    "data_sensitivity": 100,
    "action": "block"
  }' | jq .

# Create an organization-wide policy
curl -s -X POST https://api.airg.nov-tia.com/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "block-external-uploads",
    "description": "Block HTTP uploads to external domains",
    "severity": 85,
    "action": "block",
    "match_json": {
      "tool": "http_request",
      "url_regex": "^https?://(?!internal\\.company\\.com)"
    },
    "agent_id": null
  }' | jq .

# Create an agent-specific policy using rubric scoring
curl -s -X POST https://api.airg.nov-tia.com/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "support-review-pii-email",
    "description": "Review support-agent emails that include sensitive identifiers",
    "blast_radius": 70,
    "reversibility": 60,
    "data_sensitivity": 95,
    "action": "review",
    "match_json": {
      "tool": "send_email",
      "args_regex": "(SSN|passport|credit card|patient)"
    },
    "agent_id": "support-agent-1"
  }' | jq .

# Toggle on/off
curl -s -X PATCH https://api.airg.nov-tia.com/policies/block-external-uploads/toggle \
  -H "Authorization: Bearer $TOKEN" | jq .

# Partial update
curl -s -X PATCH https://api.airg.nov-tia.com/policies/block-external-uploads \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "severity": 95}' | jq .

{
  "receipt_id": "surge-a1b2c3d4e5f67890",
  "sequence": 42,
  "timestamp": "2026-03-04T12:00:00+00:00",
  "tool": "shell",
  "decision": "block",
  "risk_score": 95,
  "explanation": "Dangerous command: rm -rf",
  "policy_ids": ["shell-dangerous"],
  "chain_pattern": null,
  "agent_id": "agent_001",
  "session_id": "sess_abc",
  "sovereign": {
    "deployment_id": "novtia-uk-prod-001",
    "jurisdiction": "GB",
    "operator": "Acme Services",
    "infrastructure": "on-premise",
    "data_residency": "GB",
    "classification": "OFFICIAL"
  },
  "compliance": {
    "eu_ai_act": ["Art.9", "Art.12", "Art.13", "Art.15"],
    "nist_ai_rmf": ["GOVERN-1.1", "MAP-1.1", "MEASURE-2.1", "MANAGE-1.1"],
    "owasp_llm": ["LLM06"]
  },
  "digest": "a1b2c3...sha256",
  "previous_digest": "f9e8d7...sha256",
  "merkle_root": null
}

curl -s -X POST https://api.airg.nov-tia.com/notifications/channels \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "security-alerts",
    "channel_type": "slack",
    "config_json": {"webhook_url": "https://hooks.slack.com/services/T.../B.../..."},
    "is_active": true
  }' | jq .

https://api.airg.nov-tia.com