AuditTrail API Reference

Complete REST + WebSocket surface for AuditTrail v3.45.0.

Base URL: /api/v1 (all REST routes; the SCIM provisioning endpoints are the only exception — they live under /scim/v2 per the SCIM spec). Request and response bodies are JSON unless noted (CSV / PDF exports stream files).

Authentication & authorization

AuditTrail accepts several credential types depending on the route group:

The dependency names you'll see referenced below map to:

• get_current_user — session cookie required.
• require_user_or_apikey — session cookie or an sk-at-… ingest key.
• require_user_apikey_or_runner_token — adds the daemon's sk-atd-… token.
• require_admin — tenant admin role.
• require_superadmin — cross-tenant is_superadmin flag.

User isolation (Hard Rule 8): every owned row is filtered by user_id == current_user.id. Cross-tenant reads return 404 (existence is not leaked) on the newer route groups and 403 on a few older ones — the purpose column notes where this matters.

Response envelope: trace / span / DAG / evaluation / ablation GETs wrap their payload in {"data": …}. Read resp.json()["data"], not resp.json(). Newer route groups (alerts, datasets, evals, agent-registry, runner, organizations, SSO/SCIM, compliance) return bare JSON or a typed object.

Auth & identity

routes/auth.py — prefix /api/v1/auth. Login / register are rate-limited (10/minute); password reset is tighter (5/minute).

POST /auth/login request:

{ "email": "user@example.com", "password": "secure-password" }

Response (200):

{ "user_id": "uuid", "email": "user@example.com", "role": "admin", "display_name": "Alice" }

Sets audittrail_session (HttpOnly, SameSite=Strict, 24h), audittrail_csrf (JS-readable, SameSite=Lax), and audittrail_refresh (HttpOnly, scoped to /api/v1/auth, 30d).

Admin (superadmin, cross-tenant)

routes/admin.py — prefix /api/v1/admin. Every route requires require_superadmin; mutations write audit-log rows.

Organizations, members, invites

routes/organizations.py — prefix /api/v1/organizations. RBAC ranks owner > admin > annotator > viewer via require_org_role. See SSO & SCIM for the SAML/SCIM surface that sits on top.

Projects

routes/projects.py — prefix /api/v1/organizations/{org_id}/projects.

API keys

routes/api_keys.py — prefix /api/v1/api-keys. The plaintext sk-at-… secret is shown once on create.

Traces & spans

routes/traces.py + routes/spans.py — prefix /api/v1. All get_current_user-scoped; GETs use the {"data": …} envelope.

GET /traces query parameters: status, agent_name, environment, model, tool (traces with at least one tool span of that name — v3.26.0), created_after, created_before, search, sort_by (created_at default), sort_order (desc), limit (1–200, default 50), cursor.

Response (200):

{
  "data": [
    {
      "id": "trace-uuid", "session_id": "session-uuid", "root_span_id": "span-uuid",
      "agent_name": "researcher", "environment": "production", "status": "complete",
      "created_at": "2026-06-30T10:00:00Z", "completed_at": "2026-06-30T10:00:05Z",
      "total_duration_ms": 5200, "total_tokens_in": 1200, "total_tokens_out": 450,
      "total_cost": 0.0285, "metadata_": {"tags": {"version": "1.0"}}, "span_count": 6
    }
  ],
  "meta": { "total": 150, "cursor": "eyJjcmVhdGVkX2F0Ijoi…", "has_more": true }
}

The cursor is a base64-encoded {"created_at": <iso>, "id": <str>}; pass it back as ?cursor= to fetch the next page.

Ingest

routes/ingest.py — prefix /api/v1/ingest. The data-plane entry point. require_user_or_apikey; spans are upserted on span_id (idempotent, at-least-once). Each route is rate-limited 60/minute. See the quickstart for full agent-integration patterns.

POST /ingest/spans request:

{
  "batch": [
    {
      "span_id": "span-uuid", "trace_id": "trace-uuid", "parent_span_id": null,
      "name": "gpt-4o-step-0", "span_type": "llm",
      "start_time": "2026-06-30T10:00:00Z", "end_time": "2026-06-30T10:00:01Z",
      "status": "ok", "model": "gpt-4o",
      "input": {"prompt": "…"}, "output": {"response": "…"},
      "tokens_in": 350, "tokens_out": 120, "cost": 0.0071,
      "tool_calls": [
        { "tool_name": "web_search", "arguments": {"query": "…"},
          "result": {"output": "…"}, "selected_from": ["web_search", "calculator"] }
      ],
      "attributes": {"temperature": 0.7}
    }
  ]
}

Response (200): { "accepted": 5, "errors": null }. Partial failures land in errors. The OTLP endpoint returns { "accepted", "rejected", "partialSuccess?" }.

Zero-SDK OTLP: point an OpenTelemetry exporter at the OTLP route with an Authorization: Bearer sk-at-… header — gen_ai.* attributes map onto native span fields. JS/Node exporters can target it directly with OTEL_EXPORTER_OTLP_PROTOCOL=http/json; the Python OTel SDK does not implement that protocol option, so bridge through an OpenTelemetry Collector (otlphttp exporter with encoding: json) — full recipes on OpenTelemetry integration.

XAI & causal attribution

Ablation (causal attribution)

routes/ablation.py — prefix /api/v1/ablation. get_current_user. Ablation is opt-in and cached; always preview cost with /estimate first.

Counterfactuals & NL explanations

routes/xai.py — prefix /api/v1/xai. require_user_or_apikey, rate-limited 20/minute. See Counterfactuals and NL Explanations.

SAE mechanistic XAI

routes/v20.py (sae_router) — prefix /api/v1/sae. require_user_or_apikey. See SAE mechanistic XAI.

Governance & rules

routes/rules.py — prefix /api/v1. Reads use get_current_user; mutations require require_admin. Rules live in YAML (Hard Rule 11); a tenant's edits are stored as overrides. Per-user rule bindings scope which rules fire on which spans (v2.7.0 E5).

REGO policies (Governance 2.0)

routes/v20.py (policy_router) — prefix /api/v1/policies. require_user_or_apikey.

Constitutional evaluations

routes/evaluations.py — prefix /api/v1. get_current_user.

Evals & datasets

Two distinct surfaces — see Evaluations.

Datasets

routes/datasets.py — prefix /api/v1/datasets. require_user_or_apikey.

Eval runs

routes/evals.py — prefix /api/v1/evals. require_user_or_apikey. Runs execute a built-in evaluator over a dataset in a detached task.

Annotation queues

routes/annotations.py — prefix /api/v1/annotations. require_user_or_apikey.

Deployments & runtime controls

routes/deployments.py — prefix /api/v1/deployments/actions. require_user_or_apikey; state-changing routes 30/minute. The 3-tier safety model and the executor capability matrix are documented in Deployment actions and Executable actions; the read-only runtime-control projection powers Run status.

Attribution evidence (ActionOut.evidence, v3.30.0). When a proposal's target_ref resolves to one of the caller's traces or spans, the propose path stores the no-LLM surrogate SHAP attribution for the decision-relevant tool span on the action row: {version, source ("surrogate" | "heuristic"), explanation, top_features[{name, value, shap_value, description}], surrogate_f1, tool, span_id, trace_id, violation{rule_id, rule_name, severity} | null, computed_at}. source is honest provenance — "surrogate" only when the startup-trained model exists; surrogate_f1 is null on the heuristic fallback. Actions without a resolvable trace/span target have evidence: null. Computed best-effort; never blocks or fails the propose.

Runtime-control fields (RuntimeControlOut). Each active control row carries id, control_type (switch_model / throttle / disable_flag), target, params_json, source_action_id (the deployment_actions row that created it), created_at, and expires_at (v3.9.0). expires_at is a nullable TTL — null means the control is permanent until deactivated; a non-null timestamp is when the executor's background reaper will auto-deactivate it (fail-safe: an expired throttle/disable/switch stops enforcing). See Run status for the TTL and deactivate lifecycle.

Deactivate (v3.10.0) — POST /deployments/actions/runtime-controls/{control_id}/deactivate flips the control's active flag to false so the gateway stops enforcing it, then broadcasts runtime_control.expired on the owner's WebSocket. User-scoped (Hard Rule 8): only the caller's own active controls are addressable, so a control that is already inactive or belongs to another tenant returns 404. Returns the updated RuntimeControlOut.

Agent registry & secrets

Agent registry (immutable versioning)

routes/agent_registry.py — prefix /api/v1/agent-registry. require_user_or_apikey; cross-tenant → 404; mutations 20/minute. See Agent registry.

Agent secrets (gateway-only BYOK)

routes/agent_secrets.py — prefix /api/v1/agent-secrets. require_user_or_apikey; cross-tenant → 404; mutations 30/minute. The plaintext value is write-only — never returned, never logged. See Gateway secrets.

Agent templates & agents

routes/agent_templates.py — prefix /api/v1/agent-templates (require_user_or_apikey). See Running agents from chat.

routes/agents.py — prefix /api/v1/agents. Reads get_current_user; create / delete require require_admin.

Runner daemon

routes/runner.py — prefix /api/v1/runner. require_user_or_apikey (except /status, which also accepts the daemon's sk-atd-… runner token). Dispatch is gated by a per-user template allowlist. See Local runner and Run status.

POST /runner/dispatch request:

{
  "template_id": "quickstart",
  "prompt": "Compute 12 * 8 and explain the result",
  "model": "gpt-4o-mini",
  "env_overrides": {},
  "version": null
}

template_id is a built-in (quickstart / web-search) or a registered agent reference (agent:<definition_id>). A value not in the caller's effective allowlist returns 422 {"error": "template_not_allowed", "allowed": [...]}; no connected daemon returns 404.

Response (201): { "dispatch_id": "…", "correlation_id": "…" }.

Dispatch detail (GET /runner/dispatches/{id} → DispatchDetailOut):

{
  "id": "…",
  "correlation_id": "…",
  "template_id": "agent:…",
  "prompt": "…",
  "status": "succeeded",
  "stdout_tail": [{ "stream": "stdout", "line": "…", "at": "…" }],
  "trace_id": "…",
  "created_at": "…",
  "started_at": "…",
  "completed_at": "…",
  "error_log": null,
  "agent_definition_id": "…",
  "agent_version_id": "…",
  "agent_version": 3
}

The three version-provenance fields — agent_definition_id, agent_version_id, agent_version (v3.11.0) — record which registered agent version actually ran. They are null for built-in templates (quickstart / web-search) and populated only for agent:<id> dispatches. Note the last-dispatch summary in GET /runner/status (DispatchSummary) carries the lighter pair agent_definition_id + agent_version only; agent_version_id appears solely on the full detail response above. See Local runner.

The daemon connects over WebSocket at /api/v1/runner/ws (below).

Gateway proxy

routes/gateway.py — an OpenAI-compatible reverse proxy that traces every LLM call. Virtual keys (at-gw-…) are managed under /api/v1/gateway (require_user_or_apikey); the proxy itself lives under /api/v1/gateway/proxy/v1 and authenticates with the virtual key as a Bearer token. See Gateway proxy.

Calling the proxy — point any OpenAI SDK at it:

export OPENAI_BASE_URL="https://auditrail.yourco.com/api/v1/gateway/proxy/v1"
export OPENAI_API_KEY="at-gw-YOUR-VIRTUAL-KEY"

Optional headers / body fields the proxy understands (stripped before forwarding upstream): X-AuditTrail-Secret selects a stored gateway secret as the upstream credential; audittrail_prompt_key opts the request into prompt-canary attribution. Active runtime controls (switch_model / throttle / disable_flag) are applied to the owner's gateway-routed traffic before the call forwards. Every completion is logged as an llm span — constitutional rules fire exactly as for SDK-originated spans.

Unsupported model → 400 (v3.7.0). When a provider key is configured and the request names a model the gateway doesn't recognise, the proxy refuses with a 400 rather than fabricating a response:

{
  "error": "unsupported_model",
  "model": "totally-made-up-model",
  "supported": ["gpt-*", "o1/o3/o4*", "openai/*", "claude-*", "anthropic/*", "minimax*", "ollama/*", "gemini-*", "qwen*", "mock/* (keyless dev only)"]
}

The check runs before both the streaming and non-streaming branches (a stream can't be un-started once it begins). The keyless dev-mock fallback — no provider key configured at all — is unaffected and still serves a deterministic mock/* completion. See Gateway proxy.

Prompts, canary & optimize

routes/prompts.py, routes/prompt_canary.py, routes/prompt_optimize.py — all under prefix /api/v1/prompts. require_user_or_apikey; cross-tenant → 404. Canary mutations 10/minute. See Prompt canary.

Chat sessions & assistant

routes/chat_sessions.py — prefix /api/v1/chat/sessions (require_user_or_apikey; mutations 20/minute). routes/assistant.py — prefix /api/v1/assistant. See Operations Assistant.

Compliance

routes/compliance_admin.py — prefix /api/v1/compliance. get_current_user; superadmins see all tenants. EU AI Act article posture + Article 73 incident log + regulator-ready export. See Compliance.

Alerts & webhooks

Alerts

routes/alerts.py — prefix /api/v1/alerts. require_user_or_apikey. See Alerts.

Webhooks

routes/webhooks.py — prefix /api/v1/webhooks. Reads get_current_user; mutations + test require require_admin.

Outbound destinations support Slack, PagerDuty Events v2, and generic HTTPS with HMAC-SHA256 signing. The create/patch/delivery paths enforce an SSRF guard that blocks private/loopback/link-local/cloud-metadata targets.

Identity provider integration (SSO / SCIM)

routes/v21.py — SAML SSO + SCIM provisioning. See SSO & SCIM.

Pause / resume

routes/pauses.py — prefix /api/v1/pauses. require_user_or_apikey; mutations 12/minute. The Edit + Resume path is gated by AUDITTRAIL_EXPERIMENTAL_EDIT_RESUME. See Pause / resume.

Fleet

routes/fleet.py — prefix /api/v1/fleet. require_user_or_apikey. See Live Fleet.

Reports

routes/reports.py — prefix /api/v1/reports. get_current_user.

Analytics

routes/analytics.py — prefix /api/v1/analytics. get_current_user; results cached 60s.

Fleet WHY (GET /analytics/fleet-why, v3.31.0). Global feature importances of the tool-selection surrogate — what drives tool selection across the whole deployment, computed at train time as mean |SHAP| over the training set (importance_method: "mean_abs_shap"; falls back to "xgb_gain" when the SHAP explainer is unavailable). The surrogate is instance-global: it trains on the most recent 500 tool spans across the deployment, at API startup and automatically in the background once at least 5 tool spans with two distinct tools exist. Response: {trained, n_samples, surrogate_f1, trained_at, min_samples_required, importance_method, importances[{name, importance, description}], tool_distribution, user_tool_span_count, reason} — when untrained, importances is empty and reason states why (no fabricated values).

Settings, health & billing

routes/settings.py + routes/health.py — prefix /api/v1.

routes/v20.py (billing_router) — prefix /api/v1/billing.

WebSocket

routes/ws.py. The dashboard endpoints authenticate with the session JWT cookie; the runner endpoint authenticates with an sk-atd-… token. The canonical paths are under /api/v1/ws/* (the production Caddy only proxies /api/*); legacy /ws/* paths resolve to the same handlers.

Client messages: {"type":"ping"}, {"type":"subscribe","trace_id":"…"}, {"type":"unsubscribe","trace_id":"…"}, and {"type":"command", …} — the last proposes a DeploymentAction from the live DAG (same tier rules as the REST path; the WS path only proposes, it never auto-executes Tier 2/3).

Server events use the {"event": <type>, …} envelope (note: event, not type). Examples: span_start / span_end, trace_complete, constitutional_violation, pause_active / pause_resumed / pause.expired / pause.abandoned, canary.ramped / canary.rolled_back, command.proposed / command.ack, runner.connected / runner.disconnected / runner.dispatch.output / runner.dispatch.final.

span_start fires when a running span is ingested and span_end when a span arrives closed (ok / complete / error) — both HTTP and OTLP ingest broadcast them, so a streaming SDK run renders spans in the trace view live, without polling. trace_complete fires once, when the last running span closes and the trace transitions into a terminal status; its data carries {status, span_count, total_cost, total_duration_ms}.

Error responses

{ "detail": "Resource not found" }