API: Audit

Overview

Audit endpoints provide access to execution history, hash chain verification, and GDPR PII erasure. All executions validated through the gateway are persisted in an append-only audit ledger.

Why It Matters

Compliance teams need queryable audit records and tamper-evident chain verification for ISO 42001 and SOC2 evidence.

Prerequisites

• Team tier and above for central audit and hash-chain verification
• Gateway with PostgreSQL (not embedded SQLite for production audit)

Step-by-Step Guide

List executions

GET /v1/audit/executions?agent_id=payment-agent&limit=50&offset=0
X-AgentTrust-Token: at_team_your_key

Get execution detail

GET /v1/audit/executions/{envelope_id}

Verify hash chain

GET /v1/audit/chain/verify

Returns chain integrity status. Team tier and above — the entitlement guard answers 402 Payment Required (not 403) with an upgrade message on lower tiers. The list and detail endpoints above carry no entitlement guard at all.

PII erasure (GDPR Art. 17)

DELETE /v1/audit/executions/{envelope_id}/pii

Masks PII fields in payload without deleting hash chain metadata.

Full route list

CLI equivalents

agentrust audit tail
agentrust export ./audit.jsonl

Examples

curl -H "X-AgentTrust-Token: $AGENTRUST_KEY" \
  "http://localhost:8000/v1/audit/executions?agent_id=faq-agent&limit=10"

Best Practices

• Retention: 90-day hot store, 7-year metadata (see Data Governance)
• Run periodic chain verification in Enterprise deployments
• Use agent_id filter for per-agent compliance reports
• Export via /v1/reports/* for regulator evidence packs

Common Mistakes

• Expecting full payloads after 90-day retention period
• Deleting audit records manually in PostgreSQL (breaks hash chain)
• Using embedded SQLite as production audit store

Troubleshooting

Related Resources

• Data Governance
• Operator dashboard — agentrust-edge/dashboard/ (served on :3000 in the Compose stack)
• Compliance