API documentation

1. 1. Register the agent — Guardian issues an identity with an authorization scope, data-access ceiling and trust score.
2. 2. Submit the action — before your agent executes something consequential, send the action to Guardian.
3. 3. Act on the decision — allowed proceeds, alert proceeds with a recorded warning, blocked must not run.

Send the key as a bearer token. Keys are scoped — ingest requires events:write and guard mode requires guard:write.

Authorization: Bearer gd_live_9f2c41d08b7a4e5c9a1b3d6f2e8c0a74

Production keys are prefixed gd_live_ and sandbox keys gd_test_. Revoke a key at any time from the API keys page; revocations apply immediately.

Both SDKs wrap the endpoints below — guard() before an action executes, report() for batches of completed actions — with timeouts, typed errors and friendly field names. On a network failure they throw, so you choose whether to fail open or closed.

npm install @theaiguardians/sdk

import { Guardian } from "@theaiguardians/sdk";

const guardian = new Guardian(process.env.GUARDIAN_API_KEY);

// Before your agent runs anything consequential:
const decision = await guardian.guard({
  agentId: "agt_5d21aa91",
  action: "Charge customer card via Stripe",
  target: "stripe.charges.create",
  dataClassification: "confidential",
});

if (!decision.execute) return; // blocked by policy — do not run the action

pip install ai-guardian

import os
from guardian import Guardian

guardian = Guardian(os.environ["GUARDIAN_API_KEY"])

# Before your agent runs anything consequential:
decision = guardian.guard(
    agent_id="agt_5d21aa91",
    action="Charge customer card via Stripe",
    target="stripe.charges.create",
    data_classification="confidential",
)

if not decision["execute"]:
    ...  # blocked by policy — do not run the action

Both read GUARDIAN_API_KEY from the environment (or take the key directly), and honor GUARDIAN_BASE_URL to point at another environment. The npm package ships its own TypeScript types; the pip package is a single module with no third-party dependencies.

# Ubuntu / Debian
sudo apt update && sudo apt install -y python3-pip nodejs npm
pip install ai-guardian        # Python SDK
npm install @theaiguardians/sdk  # JavaScript / TypeScript SDK
export GUARDIAN_API_KEY="gd_live_..."   # Windows: set GUARDIAN_API_KEY=gd_live_...

Call the guard the moment your agent is about to run something consequential. Guardian scores the action, applies your enabled policies, records the decision and answers synchronously — blocked means the action must not run; execute carries the same signal for the loop in your runtime.

Requires a key with the guard:write scope and the Developer plan or above. Every guard call counts toward your monthly event quota, exactly like an ingested event, so the audit trail stays complete.

curl -X POST "https://theaiguardians.com/functions/guardianGuard" \
  -H "Authorization: Bearer gd_live_9f2c41d08b7a4e5c9a1b3d6f2e8c0a74" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_ID",
    "event_type": "tool_call",
    "action": "Charge customer card via Stripe",
    "target": "stripe.charges.create",
    "data_classification": "confidential",
    "summary": "Agent attempted to charge a card from the CRM thread."
  }'

{
  "decision": "blocked",
  "execute": false,
  "risk_score": 74,
  "risk_factors": [
    "Confidential data in scope",
    "Block payment actions"
  ],
  "matched_policies": ["Block payment actions"],
  "agent_id": "agt_5d21aa91",
  "event_id": "evt_8c21f4a9",
  "quota": { "tier": "starter", "monthly_limit": 50000, "used": 1204 }
}

Guardian scores every action 0–100 from its event type, data classification, destination, authorization scope, agent autonomy and trust score, and the volume of data involved. Then your enabled policies are evaluated.

A matched block policy always wins and cannot be downgraded. Each policy carries a score floor — the minimum score recorded when it matches — so the score, the matched policies and the decision always agree.

Verify the X-Guardian-Signature header against the endpoint secret before acting on any payload.

import crypto from 'node:crypto';

const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.GUARDIAN_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

const received = req.headers['x-guardian-signature'] || '';

if (expected.length === received.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
  // authentic delivery — safe to act on
}

Subscribed event names: guardian.event.blocked, guardian.event.alert, guardian.threat.opened, guardian.threat.resolved, guardian.agent.quarantined, guardian.usage.threshold.