03 — API Reference

Ingest endpoints

Base URL https://audit.example.com. All ingest routes require a valid Bearer JWT with the audit.writer role.

Method	Path	Purpose	Status
POST	/v1/audit-logs:batch	Append up to 500 events	202
POST	/v1/audit-logs	Append a single event	202
GET	/v1/audit-logs?source=&actor=&from=&to=	Query (reader role)	200
GET	/healthz · /readyz	Liveness / readiness (no auth)	200

Request · POST /v1/audit-logs

Authorization: Bearer eyJ…
Idempotency-Key: 5f3c…
Content-Type: application/json

Idempotency-Key is optional.

{
  "event_id": "a1b2-uuid",
  "occurred_at": "2026-06-27T10:14:02Z",
  "source_system": "vault",
  "source_instance": "vault-prod-eu",
  "action": "ssh.cred.issued",
  "outcome": "SUCCESS",
  "severity": "INFO",
  "actor_id": "svc-deploy",
  "target_id": "db-prod-3",
  "correlation_id": "trace-9f2c",
  "metadata": { "ttl": 3600, "role": "readonly" }
}

received_at + ingest_client_id enriched by API.

Response · 202 Accepted

{
  "accepted": 1,
  "event_ids": ["a1b2-uuid"],
  "status": "queued"
}

Error envelope (4xx/5xx):

{
  "error": {
    "code": "invalid_argument",
    "field": "occurred_at",
    "message": "must be RFC3339"
  }
}

207 Multi-Status for :batch (per-item accepted / rejected).