Audit API

Query the immutable audit trail of all agent actions, policy decisions, and human interventions.

Query audit logs

GET /v1/audit

Auth: JWT Bearer Token

Query parameters

Parameter	Type	Description
entityType	string	Filter by entity type (run, tool_call, policy, approval)
entityId	string	Filter by specific entity ID
runId	string	Filter by run ID
actorType	string	Filter by actor type (agent, system, user)
action	string	Filter by action (e.g., blocked, approved, matched)
from	ISO date	Start of date range
to	ISO date	End of date range
search	string	Full-text search across audit entries
limit	number	Max results (default: 50)
offset	number	Pagination offset

Examples

# All audit logs
curl http://localhost:3000/v1/audit \
  -H "Authorization: Bearer $TOKEN"

# Logs for a specific run
curl "http://localhost:3000/v1/audit?runId=run_abc123" \
  -H "Authorization: Bearer $TOKEN"

# All policy match events
curl "http://localhost:3000/v1/audit?entityType=policy&action=matched" \
  -H "Authorization: Bearer $TOKEN"

# All human actions
curl "http://localhost:3000/v1/audit?actorType=user" \
  -H "Authorization: Bearer $TOKEN"

# Search
curl "http://localhost:3000/v1/audit?search=deploy+production" \
  -H "Authorization: Bearer $TOKEN"

# Date range
curl "http://localhost:3000/v1/audit?from=2026-03-01&to=2026-03-19&limit=100" \
  -H "Authorization: Bearer $TOKEN"

Response

[
  {
    "auditId": "aud_abc123",
    "runId": "run_xyz789",
    "entityType": "tool_call",
    "entityId": "tc_def456",
    "action": "blocked",
    "actorType": "system",
    "actorId": "system:policy:block-destructive-ops",
    "timestamp": "2026-03-19T10:32:15.000Z",
    "metadata": {
      "toolName": "shell_execute",
      "policyName": "Destructive Script Block",
      "reason": "Matched pattern: rm -rf"
    }
  },
  {
    "auditId": "aud_abc124",
    "runId": "run_xyz789",
    "entityType": "approval",
    "entityId": "appr_ghi012",
    "action": "approved",
    "actorType": "user",
    "actorId": "user:reviewer@company.com",
    "timestamp": "2026-03-19T10:34:00.000Z",
    "metadata": {
      "decisionReason": "Reviewed and approved"
    }
  }
]

Export audit logs as CSV

GET /v1/audit/export

Auth: JWT Bearer Token

Downloads audit logs as a CSV file. Supports the same filters as the query endpoint (excluding limit and offset — exports up to 10,000 records).

Query parameters

Parameter	Type	Description
entityType	string	Filter by entity type (run, tool_call, policy, approval)
entityId	string	Filter by specific entity ID
runId	string	Filter by run ID
actorType	string	Filter by actor type (agent, system, user)
action	string	Filter by action (comma-separated for multiple)
from	ISO date	Start of date range
to	ISO date	End of date range
search	string	Full-text search across audit entries

Examples

# Export all audit logs as CSV
curl -O -J "http://localhost:3000/v1/audit/export" \
  -H "Authorization: Bearer $TOKEN"

# Export logs for a specific run
curl -O -J "http://localhost:3000/v1/audit/export?runId=run_abc123" \
  -H "Authorization: Bearer $TOKEN"

# Export logs for a date range
curl -O -J "http://localhost:3000/v1/audit/export?from=2026-03-01&to=2026-03-19" \
  -H "Authorization: Bearer $TOKEN"

Response

Returns a CSV file with headers: timestamp, auditId, entityType, entityId, runId, action, actorType, actorId, metadata.

The Content-Disposition header sets the filename to audit-export-YYYY-MM-DD.csv.