Audit API

Use the Audit API to search request history, generate compliance summaries, record non-LLM tool calls, and inspect tenant-scoped audit trails. This is one of the most important surfaces for regulated AI systems because it turns governance decisions into something security, compliance, and platform teams can actually review.

Overview

Verified routes:

Method	Path	Purpose
POST	/api/v1/audit/search	Search audit logs
POST	/api/v1/audit/tool-call	Record a non-LLM tool call
GET	/api/v1/audit/tenant/{tenant_id}	Fetch tenant audit logs
POST	/api/v1/audit/summary	Generate a compliance summary

Base URL, recommended:

http://localhost:8080

The Agent commonly proxies these requests to the Orchestrator. For hardened deployments, the tool-call write path is especially important to send through the Agent because the Orchestrator may require the internal proxy-auth header it injects.

Authentication

Common headers:

Header	Notes
Authorization	Basic auth for protected requests
Tenant (from Basic auth)	Required for POST /api/v1/audit/tool-call; also used by summary
X-Org-ID	Backward-compatible tenant scope on some read paths
Content-Type	JSON POST bodies

Search Audit Logs

POST /api/v1/audit/search accepts a JSON body with these verified fields:

Field	Notes
user_email	Optional filter
client_id	Optional filter
start_time	RFC3339 time accepted by the handler
end_time	RFC3339 time accepted by the handler
request_type	Optional filter
limit	Defaults to 100 when omitted

The response shape is verified in code as:

{
  "entries": [],
  "total": 0,
  "limit": 100,
  "offset": 0
}

The entries array is made of audit records with fields such as:

Field	Notes
id	Audit entry ID
request_id	Request or workflow correlation ID
timestamp	Event time
user_id, user_email, user_role	User context when available
client_id, tenant_id	Caller and tenant scope
request_type	Request category like llm_request, workflow_*, or tool_call_audit
query, query_hash	Request text and stable hash
policy_decision	allowed, blocked, redacted, error, or other internal states
policy_details	Structured policy metadata
provider, model	Provider details for LLM-backed requests
response_time_ms, tokens_used, cost	Performance and usage metadata
redacted_fields	Output fields that were redacted
error_message	Error detail when present
response_sample	Truncated sample response
compliance_flags, security_metrics	Derived compliance or risk metadata

Example:

{
  "entries": [
    {
      "id": "aud_001",
      "request_id": "req_abc123",
      "timestamp": "2026-03-29T11:58:00Z",
      "user_email": "[email protected]",
      "client_id": "security-app",
      "tenant_id": "tenant-123",
      "request_type": "llm_request",
      "query": "Summarize the quarterly security report",
      "query_hash": "a1b2c3",
      "policy_decision": "allowed",
      "policy_details": {
        "applied_policies": ["tenant-cost-review"],
        "risk_score": 0.12
      },
      "provider": "openai",
      "model": "gpt-4o",
      "response_time_ms": 842,
      "tokens_used": 598,
      "cost": 0.0049,
      "redacted_fields": [],
      "response_sample": "The quarterly security report highlights...",
      "compliance_flags": [],
      "security_metrics": {
        "risk_score": 0.12
      }
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

This is the endpoint staff engineers usually wire into internal admin consoles, SIEM forwarders, and incident triage tools.

Record Tool Calls

POST /api/v1/audit/tool-call is for non-LLM actions such as MCP executions, third-party API calls, or framework-level function invocations.

Verified required behavior:

• tool_name is required
• Tenant context (derived from Basic auth credentials) is required
• when the proxy token validator is active, requests must come through the Agent
• Basic auth is required outside community-only paths

curl -X POST http://localhost:8080/api/v1/audit/tool-call \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'client-id:client-secret' | base64)" \
  -d '{
    "tool_name": "weather-api",
    "tool_type": "api",
    "input": {"city": "San Francisco"},
    "output": {"temperature": 18},
    "duration_ms": 245,
    "success": true
  }'

Successful responses return:

{
  "audit_id": "aud_tc_abc123",
  "status": "recorded",
  "timestamp": "2025-01-02T14:30:00Z"
}

The tool-call handler stores your request in policy_details, so fields like tool_type, input, output, workflow_id, step_id, duration_ms, policies_applied, success, and error_message are preserved for later search and summary flows.

Tenant Audit Log Reads

GET /api/v1/audit/tenant/{tenant_id} returns the same entries, total, limit, and offset wrapper used by search, but scoped directly to one tenant ID from the path. It accepts:

Query param	Notes
limit	Preferred limit, default 50, max 1000
page_size	Deprecated alias retained for compatibility

Compliance Summary

POST /api/v1/audit/summary is the fastest way to build compliance dashboards and review windows for internal controls.

Verified request rules:

• start_time and end_time must be RFC3339
• end_time must be after start_time
• range cannot exceed 1 year
• Tenant context (derived from Basic auth credentials) or X-Org-ID is required

Verified response shape:

{
  "total_events": 1200,
  "by_severity": {
    "critical": 12,
    "warning": 96,
    "info": 1092
  },
  "by_action": {
    "llm_request": 900,
    "mcp_query": 200,
    "workflow_execution": 100
  },
  "top_policies": [],
  "compliance_score": 99.0
}

top_policies is an array of objects with policy_name, trigger_count, and block_count, which makes this route especially useful for compliance dashboards and procurement review material.

Related Docs

• Decision & Execution Replay API
• Workflow API
• Community vs Enterprise