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://your-domain.com/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
  }
}

Retrieve logs

Supports query params: limit, offset, agentId, action, traceId.

Batch Logging

Submit up to 50 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://your-domain.com/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 }
    }
  ]'

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.

Agents

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

Create an agent

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

{
  "name": "writer-agent",
  "metadata": { "version": "1.0", "team": "content" }
}

// Response
{
  "id": "agent_...",
  "name": "writer-agent",
  "organizationId": "org_...",
  "metadata": { "version": "1.0", "team": "content" },
  "createdAt": "2026-01-15T10:00:00.000Z"
}

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:

{
  "error": "Human-readable message",
  "status": 400
}