📜Audit Log•POST /v1/audit

Audit Log

Append-only decision records for accountability, compliance, and debugging.

What it does

Creates immutable, server-timestamped audit records that explain what an agent did, when it did it, and which metadata was attached.

Endpoint

Method: POST

Path: POST /v1/audit

Auth: x-agent-id + x-api-key

Request shape

•action: string
•metadata?: object
•request_id?: string

Example requests

Copy-pasteable examples for agents and automation.

cURL

curl -X POST https://www.agent-utils.com/v1/audit \
  -H "x-agent-id: support-bot" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{
    "action": "refund.issued",
    "metadata": { "order_id": "ord_9", "amount": 4999 }
  }'

Python

import requests

resp = requests.post(
    "https://www.agent-utils.com/v1/audit",
    headers={
        "x-agent-id": "support-bot",
        "x-api-key": "agutil_agt_…",
        "content-type": "application/json",
    },
    json={
        "action": "refund.issued",
        "metadata": {"order_id": "ord_9", "amount": 4999},
    },
)
event_id = resp.json()["data"]["id"]

JavaScript

const res = await fetch("https://www.agent-utils.com/v1/audit", {
  method: "POST",
  headers: {
    "x-agent-id": "support-bot",
    "x-api-key": "agutil_agt_…",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    action: "refund.issued",
    metadata: { order_id: "ord_9", amount: 4999 },
  }),
});

How agents use it

A support agent logs the reason for every refund or escalation before it acts.

A pricing bot records the model, prompt version, and decision metadata for later review.

An ops agent stamps every high-risk action so humans can replay the full chain.

When to use it

✓You need a permanent trail of each agent decision.
✓You need evidence for support, SOC 2, or regulated workflows.
✓You want to reconstruct incidents from a single canonical log.

When not to use it

•You only need debug logs that can be freely overwritten.
•You need high-volume analytics where append-only records are not enough.

Failure modes

•Do not treat the log as mutable state; entries are append-only by design.
•If metadata is missing, the record is still stored but may be less useful later.
•Sensitive fields should be redacted before logging.

Machine-readable summary

This JSON block is stable for crawlers, agents, and downstream documentation pipelines.

{
  "slug": "audit-log",
  "title": "Audit Log",
  "canonical": "/docs/audit-log",
  "endpoint": "POST /v1/audit",
  "method": "POST",
  "auth": "x-agent-id + x-api-key",
  "machine_readable": true,
  "request_shape": [
    "action: string",
    "metadata?: object",
    "request_id?: string"
  ],
  "agent_workflows": [
    "A support agent logs the reason for every refund or escalation before it acts.",
    "A pricing bot records the model, prompt version, and decision metadata for later review.",
    "An ops agent stamps every high-risk action so humans can replay the full chain."
  ],
  "failure_modes": [
    "Do not treat the log as mutable state; entries are append-only by design.",
    "If metadata is missing, the record is still stored but may be less useful later.",
    "Sensitive fields should be redacted before logging."
  ]
}

Related docs

checkpoint dlq