AgentTrust Docs

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 for central audit (Enterprise for hash chain)
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. Enterprise tier.

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

Masks PII fields in payload without deleting hash chain metadata.

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

Issue	Fix
Empty audit list	Confirm validations hit this gateway instance
Chain verify fails	Do not manually edit audit table
403 on chain verify	Enterprise tier required

API: Audit