AgentAudit Docs

Quickstart

Get your first audit log into AgentAudit in under two minutes.

1. Create an account & get an API key

Sign up at agentaudit.online, then go to Dashboard → API Keys → Create Key. Your key starts with aa_.

2. Send your first log

curl -X POST https://agentaudit.online/api/v1/audit-logs \
  -H "X-API-Key: aa_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "llm_call",
    "prompt": "Summarise the latest sales report",
    "response": "Q1 revenue was $2.4M...",
    "metadata": { "model": "gpt-4o", "tokens": 340 }
  }'

from agentaudit import AgentAuditClient

client = AgentAuditClient(api_key="aa_your_key_here")

client.log(
    action="llm_call",
    prompt="Summarise the latest sales report",
    response="Q1 revenue was $2.4M...",
    metadata={"model": "gpt-4o", "tokens": 340}
)

import { AgentAuditClient } from 'agentaudit-client';

const client = new AgentAuditClient({ apiKey: 'aa_your_key_here' });

await client.log({
  action: 'llm_call',
  prompt: 'Summarise the latest sales report',
  response: 'Q1 revenue was $2.4M...',
  metadata: { model: 'gpt-4o', tokens: 340 },
});

3. Check your dashboard

Your log will appear in Dashboard → Recent Audit Logs within seconds. Any compliance violations will surface as alerts automatically.

Authentication

Two methods are supported depending on context.

Obtain a JWT

POST /api/v1/auth/login

{
  "email": "you@example.com",
  "password": "your_password"
}

// Response
{
  "accessToken": "eyJ...",
  "organization": { "id": "...", "email": "...", "plan": "free", "name": "Acme Corp" }
}

Create an API key

POST /api/v1/auth/api-keys
Authorization: Bearer <jwt>

{ "name": "production-agent" }

// Response
{
  "key": "aa_live_xxxxxxxxxxxxxxxx",  // shown once — save it
  "id": "key_...",
  "name": "production-agent"
}

Audit Logs

The core primitive. Log any agent action — LLM calls, tool use, decisions, guardrail checks — with a flexible schema.

Log a single event

// Example — guardrail check with trace context
{
  "action": "guardrail_check",
  "agentId": "writer-agent-1",
  "traceId": "run-1749300000000",
  "parentSpanId": "log_abc123",
  "prompt": "Draft email containing SSN: 123-45-6789",
  "response": "BLOCKED: PII detected",
  "metadata": {
    "rule": "pii_detection",
    "model": "gpt-4o",
    "latency_ms": 42
  }
}

// Response 201
{
  "id": "log_...",
  "action": "guardrail_check",
  "complianceFlags": ["CRITICAL_pii_detect_Block SSNs"],
  "enforcementAction": "block",
  "traceId": "run-1749300000000",
  "createdAt": "2026-10-25T12:00:00.000Z"
}

Retrieve logs

Supports query params: page, limit, action, agentId, traceId, startDate, endDate. Responds with { data, pagination: { page, limit, total, totalPages } }.

curl "https://agentaudit.online/api/v1/audit-logs?action=llm_call&limit=20" \
  -H "X-API-Key: aa_your_key_here"

logs = client.query_logs(action="llm_call", limit=20)

for entry in logs["data"]:
    print(entry["id"], entry["enforcementAction"])

const { data, pagination } = await client.queryLogs({
  action: 'llm_call',
  limit: 20,
});

Batch Logging

Submit up to 100 log entries in a single request. Ideal for high-throughput agents or flushing a local buffer at the end of a run.

curl -X POST https://agentaudit.online/api/v1/audit-logs/batch \
  -H "X-API-Key: aa_your_key_here" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "action": "llm_start",
      "traceId": "run-1749300000000",
      "prompt": "Analyse Q1 data",
      "metadata": { "model": "gpt-4o" }
    },
    {
      "action": "tool_use",
      "traceId": "run-1749300000000",
      "parentSpanId": "<id of llm_start log>",
      "metadata": { "tool": "code_interpreter" }
    },
    {
      "action": "llm_end",
      "traceId": "run-1749300000000",
      "response": "Q1 revenue grew 18% YoY",
      "metadata": { "tokens": 820 }
    }
  ]'

created = client.log_batch([
    {
        "action": "llm_start",
        "traceId": "run-1749300000000",
        "prompt": "Analyse Q1 data",
        "metadata": {"model": "gpt-4o"},
    },
    {
        "action": "tool_use",
        "traceId": "run-1749300000000",
        "metadata": {"tool": "code_interpreter"},
    },
    {
        "action": "llm_end",
        "traceId": "run-1749300000000",
        "response": "Q1 revenue grew 18% YoY",
        "metadata": {"tokens": 820},
    },
])

const { data, processed, errors } = await client.logBatch([
  { action: 'llm_start', traceId: 'run-1749300000000', prompt: 'Analyse Q1 data', metadata: { model: 'gpt-4o' } },
  { action: 'tool_use', traceId: 'run-1749300000000', metadata: { tool: 'code_interpreter' } },
  { action: 'llm_end', traceId: 'run-1749300000000', response: 'Q1 revenue grew 18% YoY', metadata: { tokens: 820 } },
]);

Distributed Tracing

Link every log in an agent run with a shared traceId. Use parentSpanId to express parent–child relationships between spans. The Trace Visualizer reconstructs the full tree from these fields.

Fetch a trace

Get parent chain

// Suggested traceId pattern — stable, sortable
const traceId = `run-${Date.now()}`;           // "run-1749300000000"
const traceId = `run-${crypto.randomUUID()}`;  // "run-550e8400-e29b..."

// Python
import time
trace_id = f"run-{int(time.time() * 1000)}"

Find your trace IDs in Dashboard → Recent Audit Logs, then paste them into the Trace Visualizer to replay the full agent chain.

Compliance Rules

Rules are evaluated automatically against every incoming log. Violations trigger alerts and optionally fire webhook or email notifications.

Install a compliance pack

Packs are curated rule sets for common frameworks. Available pack IDs:

• hipaa — Healthcare (HIPAA-aligned PII & PHI detection)
• finance — Financial services (PCI-DSS, sensitive data)
• gdpr — GDPR / EU data protection

POST /api/v1/compliance-rules/packs
Authorization: Bearer <jwt>

{ "packId": "gdpr" }

Alerts

Alerts are created automatically when a compliance rule fires. You can list, filter, and resolve them via API or from the dashboard.

Both accept JWT or X-API-Key auth.

curl "https://agentaudit.online/api/v1/alerts?resolved=false" \
  -H "X-API-Key: aa_your_key_here"

curl -X PATCH https://agentaudit.online/api/v1/alerts/alert_id/resolve \
  -H "X-API-Key: aa_your_key_here"

alerts = client.get_alerts(is_resolved=False)

# Resolve an alert
client.resolve_alert(alert_id)

const alerts = await client.getAlerts({ isResolved: false });

// Resolve an alert
await client.resolveAlert(alertId);

Agents

Register named agents so you can filter audit logs and alerts by agent, and attach policies directly to individual agents.

Create an agent

Accepts JWT or X-API-Key auth.

curl -X POST https://agentaudit.online/api/v1/agents \
  -H "X-API-Key: aa_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "writer-agent", "type": "custom", "description": "Drafts emails" }'

// Response 201
{
  "id": "9f1c...-uuid",
  "name": "writer-agent",
  "organizationId": "org_...",
  "createdAt": "2026-10-25T12:00:00.000Z"
}

agent = client.register_agent(
    name="writer-agent",
    agent_type="custom",
    description="Drafts emails",
)
agent_id = agent["id"]

const agent = await client.registerAgent({
  name: 'writer-agent',
  type: 'custom',
  description: 'Drafts emails',
});
const agentId = agent.id;

Once an agent is registered, pass its id as agentId in any audit log to link the log to that agent.

Policies

Policies are named, versioned bundles of compliance rules. Attach a policy to an agent and every log from that agent is evaluated against it automatically.

Attach a policy to an agent

POST /api/v1/policies/:id/agents
Authorization: Bearer <jwt>

{ "agentId": "agent_..." }

Clone a compliance pack into a policy

Available pack IDs: hipaa, gdpr, finance

POST /api/v1/policies/clone-pack
Authorization: Bearer <jwt>

{ "packId": "hipaa", "name": "HIPAA Policy v1" }

Reports

Generate downloadable compliance and audit reports for any time window. Reports are created asynchronously — poll GET /api/v1/reports/:id until status is ready, then call the download endpoint.

Request a report

POST /api/v1/reports
Authorization: Bearer <jwt>

{
  "type": "compliance_summary",
  "from": "2026-01-01T00:00:00Z",
  "to": "2026-03-31T23:59:59Z"
}

// Response
{
  "id": "report_...",
  "status": "pending",
  "type": "compliance_summary",
  "createdAt": "2026-04-01T09:00:00.000Z"
}

Billing

Billing is managed through Stripe. Use the checkout endpoint to start a paid subscription and the portal endpoint to let users manage or cancel it.

Get available plan prices

Public endpoint — no authentication required. Returns the Stripe price IDs currently configured for each paid plan. Use these IDs when creating a checkout session.

// Response
{
  "pro":      "price_...",
  "business": "price_..."
}

Create a checkout session

Requires JWT authentication. Redirects the user to Stripe Checkout to subscribe to the chosen plan.

// Request
{
  "priceId": "price_..."
}

// Response
{
  "sessionId": "cs_...",
  "url": "https://checkout.stripe.com/..."
}

Get subscription status

Requires JWT authentication. Returns the current plan and subscription details for your organisation.

Open the billing portal

Requires JWT authentication. Returns a short-lived Stripe Customer Portal URL where the user can update payment methods, change plans, or cancel.

All Endpoints

Auth

Audit Logs

Compliance

Alerts

Agents

Policies

Reports

Billing

Errors

All errors return JSON with a consistent shape. requestId is present on server errors — include it when contacting support:

{
  "error": "Human-readable message",
  "code": "bad_request",
  "requestId": "6c899479-c61a-4aee-bb0f-7279b10eaee2"
}

Rate limiting

Rate-limited API responses carry RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy headers. Current limits use separate per-IP buckets (with IPv6 subnet grouping) per 15-minute window:

Clients behind the same gateway or NAT share these budgets, even with different API keys. A new key does not reset the bucket. On HTTP 429, honor Retry-After and use bounded exponential backoff with jitter. These are request budgets, not guaranteed throughput; health checks and static pages are outside the API limiters.

Monthly quota

Audit-log writes count against your plan's monthly quota (apiUsed/apiQuota on your profile). When the quota is exhausted, writes fail with 402 and quota_exceeded until the next billing window or an upgrade.

Idempotency

Write endpoints are not idempotent — every POST /audit-logs creates a new row, so retry only on network errors or 5xx, never after a 2xx you may have missed. Use a stable traceId if you need to correlate retries in your own telemetry.

Alert webhooks

Webhook delivery is a single attempt with a 5 second timeout. Failures are logged and reported to our error monitoring but are not retried — keep your endpoint lightweight and return 2xx quickly.