Modei
PricingDocsBlog

Documentation

Theme
Log inSign up

Audit Trail API

Endpoints for reading, filtering, and exporting attestation records, the cryptographic audit trail of every authorization decision.

··

GET /attestations: List Attestations

bash
curl https://modei.ai/api/v1/attestations \
  -H "Authorization: Bearer mod_live_xxxxxxxx" \
  -G \
  --data-urlencode "agent_id=research-bot-001" \
  --data-urlencode "gate_id=gate_01HXYZ..." \
  --data-urlencode "decision=block" \
  --data-urlencode "after=2026-02-01T00:00:00Z" \
  --data-urlencode "before=2026-03-01T00:00:00Z" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0"
200 OK
{
  "items": [
    {
      "attestation_id": "att_01HABC...",
      "decision": "allow",
      "timestamp": "2026-02-24T14:30:00Z",
      "agent_id": "research-bot-001",
      "agent_name": "Research Bot",
      "gate_id": "gate_01HXYZ...",
      "gate_name": "Production API Gate",
      "request": {
        "action": "web:search",
        "target_domain": "api.example.com",
        "estimated_cost_usd": 0.01
      },
      "guardrails_evaluated": [
        { "name": "rate_limit", "result": "pass" },
        { "name": "spend_limit", "result": "pass" }
      ],
      "signature": "EdDSA:base64url..."
    }
  ],
  "total": 48291,
  "limit": 100,
  "offset": 0
}

Query Parameters:

  • agent_id, Filter by agent
  • gate_id, Filter by gate
  • issuer_id, Filter by issuer
  • decision, allow | block | request_hold
  • after, ISO 8601 start timestamp
  • before, ISO 8601 end timestamp
  • action, Filter by action (e.g., web:search)
  • limit, Max results (default: 50, max: 1000)
  • offset, Pagination offset

GET /attestations/:id: Get a Single Attestation

bash
curl https://modei.ai/api/v1/attestations/att_01HABC... \
  -H "Authorization: Bearer mod_live_xxxxxxxx"
200 OK
{
  "attestation_id": "att_01HABC...",
  "version": "1.0",
  "decision": "allow",
  "timestamp": "2026-02-24T14:30:00Z",
  "agent": {
    "agent_id": "research-bot-001",
    "agent_name": "Research Bot",
    "passport_id": "pass_01HXYZ...",
    "issuer_id": "iss_01HABC...",
    "trust_tier": "L2"
  },
  "gate": {
    "gate_id": "gate_01HDEF...",
    "gate_name": "Production API Gate"
  },
  "request": {
    "action": "web:search",
    "target_domain": "api.example.com",
    "estimated_cost_usd": 0.01
  },
  "guardrails_evaluated": [
    { "name": "rate_limit", "result": "pass", "detail": "48/60 requests used" },
    { "name": "spend_limit", "result": "pass", "detail": "$12.50/$100.00 used" }
  ],
  "signature": {
    "algorithm": "EdDSA",
    "key_id": "gate_01HDEF...",
    "value": "base64url..."
  },
  "chain_hash": "sha256:abc123..."
}

GET /attestations/export: Export Audit Trail

Export all attestations matching filters as JSON or CSV. Includes cryptographic signatures for integrity verification.

bash
# Export as JSON (date range)
curl "https://modei.ai/api/v1/attestations/export?format=json&after=2026-01-01&before=2026-03-01" \
  -H "Authorization: Bearer mod_live_xxxxxxxx" \
  -o audit-q1-2026.json

# Export as CSV (agent-specific)
curl "https://modei.ai/api/v1/attestations/export?format=csv&agent_id=research-bot-001" \
  -H "Authorization: Bearer mod_live_xxxxxxxx" \
  -o research-bot-audit.csv

# Export blocks only
curl "https://modei.ai/api/v1/attestations/export?format=json&decision=block&after=2026-02-01" \
  -H "Authorization: Bearer mod_live_xxxxxxxx" \
  -o blocks.json

Supported formats: json, csv
Large exports are streamed. Content-Type: application/x-ndjson for JSON, text/csv for CSV.

Understanding Attestation Fields

FieldDescription
attestation_idUnique identifier for this record (att_...)
decisionallow, block, or request_hold, the gate's verdict
timestampISO 8601, when the decision was made
agent.agent_idWhich agent presented the passport
agent.trust_tierThe trust tier at time of verification (L1 or L2; Verified L3 Coming Soon)
gate.gate_idWhich gate evaluated the request
request.actionThe permission scope being requested (e.g., web:search)
guardrails_evaluatedArray of each guardrail checked and its pass/fail result
signature.valueEdDSA signature by the gate's private key, proves authenticity
chain_hashHash linking this attestation to the previous, ensures immutability

Related

API — IssuersAPI — Commerce