API Reference

REST API reference for the Audit Manager — rendered directly from the live OpenAPI 3.1 spec committed to the repo.

Base path: /v1/auditmanager/. The spec below is rendered from the live docs/openapi.json. CI regenerates it from the FastAPI app on every src/-touching push, so endpoint signatures, response shapes, status-code descriptions, and the error-code catalog stay in lockstep with the code. This page does not duplicate any of that in prose.

A running instance also exposes the live spec at /v1/auditmanager/openapi.json and interactive UIs at /v1/auditmanager/docs (Swagger) and /v1/auditmanager/redoc.

Ingest a single CloudEvent

post

Accepts one CloudEvent, validates its schema, and enqueues it for durable publication to Kafka.

Returns 202 Accepted the moment the event lands in the in-process queue — Kafka and Postgres latency are fully hidden from the caller. Delivery from there is at-least-once with idempotent inserts on (id, occurred_at), so replays after a crash never produce duplicate rows in the audit store.

Body

application/json

CloudEvents v1.0 envelope.

Spec: https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md

specversionconst: 1.0OptionalDefault: 1.0

idstringOptional

sourcestringRequired

typestringRequired

subjectany ofOptional

stringOptional

or

nullOptional

timestring · date-timeOptional

datacontenttypestringOptionalDefault: application/json

traceparentany ofOptional

stringOptional

or

nullOptional

Other propertiesanyOptional

Responses

202

Event accepted into the ingest queue. The id you submitted is echoed back.

application/json

422

Malformed CloudEvent — failed schema validation (missing required field, invalid outcome enum, unparseable time, etc.).

application/json

503

Service not ready or backpressure.

• AUD-004 — ingest queue full. Retry with exponential backoff + jitter.
• AUD-005 — service startup not complete.
• AUD-006 — database health check failed (surfaces via /health, but also blocks ingest readiness indirectly).

application/json

post

/v1/auditmanager/events

HTTPcURLJavaScriptPython

POST /v1/auditmanager/events HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 519

{
  "specversion": "1.0",
  "id": "text",
  "source": "text",
  "type": "text",
  "subject": "text",
  "time": "2026-05-09T15:00:04.494Z",
  "datacontenttype": "application/json",
  "traceparent": "text",
  "data": {
    "actor": {
      "type": "user",
      "id": "text",
      "name": "text",
      "roles": [
        "text"
      ],
      "ip": "text",
      "session_id": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "action": "text",
    "outcome": "success",
    "resource": {
      "type": "text",
      "id": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "reason": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

{
  "id": "openg2p.auditmanager",
  "version": "1.0",
  "responsetime": "2026-04-23T10:00:00.000Z",
  "response": {
    "accepted": "01HXQ9R2V3K8Y2ZP7N5FJ6M4A1"
  },
  "errors": []
}

Ingest a batch of CloudEvents

post

Accepts up to ingest.max_batch_size CloudEvents in a single request. Each event is validated and enqueued independently — same 202 semantics as /events. Events in the batch are not atomic: on queue overflow part way through, the response reports the count actually accepted.

Events in a batch become separate rows in Postgres (one per CloudEvent). Batching is a transport optimization — not a storage concept.

Body

application/json

Batched ingest payload.

Responses

202

All events (or as many as fit before backpressure) accepted. The response echoes accepted ids.

application/json

400

AUD-007 — batch payload exceeds the configured ingest.max_batch_size. Split into smaller batches.

application/json

422

Malformed CloudEvent — failed schema validation (missing required field, invalid outcome enum, unparseable time, etc.).

application/json

503

Service not ready or backpressure.

• AUD-004 — ingest queue full. Retry with exponential backoff + jitter.
• AUD-005 — service startup not complete.
• AUD-006 — database health check failed (surfaces via /health, but also blocks ingest readiness indirectly).

application/json

post

/v1/auditmanager/events/batch

HTTPcURLJavaScriptPython

POST /v1/auditmanager/events/batch HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 532

{
  "events": [
    {
      "specversion": "1.0",
      "id": "text",
      "source": "text",
      "type": "text",
      "subject": "text",
      "time": "2026-05-09T15:00:04.494Z",
      "datacontenttype": "application/json",
      "traceparent": "text",
      "data": {
        "actor": {
          "type": "user",
          "id": "text",
          "name": "text",
          "roles": [
            "text"
          ],
          "ip": "text",
          "session_id": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "action": "text",
        "outcome": "success",
        "resource": {
          "type": "text",
          "id": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "reason": "text",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ]
}

{
  "id": "openg2p.auditmanager",
  "version": "1.0",
  "responsetime": "2026-04-23T10:00:00.000Z",
  "response": {
    "accepted": [
      "01HXQ9R2V...",
      "01HXQ9R2W...",
      "01HXQ9R2X..."
    ],
    "count": 3
  },
  "errors": []
}

Health / readiness probe

get

Combined liveness + readiness probe. Returns 200 with status: UP only when service startup is complete and the Postgres connection is healthy. Kubernetes probes in the shipped Helm chart point at this endpoint.

Responses

200

Service is ready to serve traffic.

application/json

idstringOptional

Constant — identifies the service that produced this envelope.

Default: openg2p.auditmanagerExample: openg2p.auditmanager

versionstringOptional

Envelope schema version (not the service version).

Default: 1.0Example: 1.0

responsetimestringRequired

RFC3339 timestamp at which this response was produced.

Example: 2026-04-23T10:00:00.000Z

503

Not ready.

• AUD-005 — service startup not yet complete.
• AUD-006 — Postgres health check failed.

application/json

get

/v1/auditmanager/health

HTTPcURLJavaScriptPython

GET /v1/auditmanager/health HTTP/1.1
Accept: */*

{
  "id": "openg2p.auditmanager",
  "version": "1.0",
  "responsetime": "2026-04-23T10:00:00.000Z",
  "response": {
    "status": "UP"
  },
  "errors": []
}

Service version and build metadata

get

Returns the running service version plus the git commit and build timestamp baked into the Docker image. Useful from probes and smoke tests to confirm which image is actually deployed.

Responses

200

Version metadata.

application/json

idstringOptional

Constant — identifies the service that produced this envelope.

Default: openg2p.auditmanagerExample: openg2p.auditmanager

versionstringOptional

Envelope schema version (not the service version).

Default: 1.0Example: 1.0

responsetimestringRequired

RFC3339 timestamp at which this response was produced.

Example: 2026-04-23T10:00:00.000Z

get

/v1/auditmanager/version

HTTPcURLJavaScriptPython

GET /v1/auditmanager/version HTTP/1.1
Accept: */*

200

Version metadata.

{
  "id": "openg2p.auditmanager",
  "version": "1.0",
  "responsetime": "2026-04-23T10:00:00.000Z",
  "response": {
    "service_version": "0.1.0",
    "build_time": "2026-04-23T08:30:00.000Z",
    "git_commit": "a1b2c3d"
  },
  "errors": []
}

Effective non-sensitive configuration

get

Returns the non-sensitive portion of the effective service configuration — ingest tunables, Kafka topic/group names, and partition-maintenance settings. Secrets and Kafka bootstrap URLs are deliberately excluded.

Responses

200

Effective configuration snapshot.

application/json

idstringOptional

Constant — identifies the service that produced this envelope.

Default: openg2p.auditmanagerExample: openg2p.auditmanager

versionstringOptional

Envelope schema version (not the service version).

Default: 1.0Example: 1.0

responsetimestringRequired

RFC3339 timestamp at which this response was produced.

Example: 2026-04-23T10:00:00.000Z

get

/v1/auditmanager/config

HTTPcURLJavaScriptPython

GET /v1/auditmanager/config HTTP/1.1
Accept: */*

200

Effective configuration snapshot.

{
  "id": "openg2p.auditmanager",
  "version": "1.0",
  "responsetime": "2026-04-23T10:00:00.000Z",
  "response": {
    "service_id": "openg2p.auditmanager",
    "api_version": "1.0",
    "ingest": {
      "max_batch_size": 500,
      "queue_max_size": 10000
    },
    "kafka": {
      "consumer_group": "openg2p-audit-consumer",
      "dlq_topic": "openg2p.audit.dlq",
      "topic": "openg2p.audit.events"
    },
    "database": {
      "partition_check_interval_seconds": 3600,
      "partition_pre_create_months": 3,
      "partition_retention_months": 84
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "errors": []
}