Audit

Every change in Actuator — flag edit, config edit, segment edit, member change, API key mint, proposal lifecycle, environment create — is recorded in the audit log with the actor, the previous and new values, and a free-text reason.

The AuditEventSummary object (returned by the list endpoint):

{
  "id": "9f7a32b5-…",
  "createdAt": "2026-04-29T14:33:00Z",
  "actorType": "user",
  "actorId": "1234abcd-…",
  "actorEmail": "pat@example.com",
  "delegatorUserId": null,
  "approverUserId": null,
  "resourceType": "flag",
  "resourceKey": "new-onboarding",
  "resourceId": "5678ef01-…",
  "envId": "9f7a32b5-…",
  "action": "flag.update_rules",
  "version": 143,
  "reason": "expand to 50% production"
}

The detail endpoint adds the previousValue, newValue, and diff JSONB blobs.

actorType is one of user, api_token, agent_token, system. delegatorUserId is set when the actor is a token; it points at the human who minted it. approverUserId is set on apply-of-proposal rows that were gated through human approval.

---

List audit events

GET /api/v1/orgs/{slug}/audit?resourceType=flag&resourceKey=new-onboarding&limit=50

Cursor-paginated. All filters AND-combine.

Param	Type	Notes
resourceType	string	flag, config, segment, proposal, environment, project, member, invitation, api_token
resourceKey	string	The primitive key.
envId	UUID	Restrict to events on a specific environment.
actorId	UUID	Restrict to events by a specific user or token.
cursor	string	Opaque continuation token from a prior nextCursor.
limit	int	1–200, default 50.

Response: 200 → { "events": AuditEventSummary[], "nextCursor": "…" | null }Errors: 400 invalid_request, 404 not_found.

Get an audit event

GET /api/v1/audit/events/{id}

Returns the full AuditEventDetail including the previousValue, newValue, and diff blobs.

Response: 200 → AuditEventDetailErrors: 404 not_found.

Cross-tenant access (asking for an audit event id from another org) collapses to 404 so URL existence doesn't leak across orgs.

---

Common queries

The lifecycle of a single flag:

GET /api/v1/orgs/{slug}/audit?resourceType=flag&resourceKey=new-onboarding

Everything one user (or token) did:

GET /api/v1/orgs/{slug}/audit?actorId={userId}

Every proposal lifecycle event:

GET /api/v1/orgs/{slug}/audit?resourceType=proposal

The data-change rows for an applied proposal — the underlying flag/config/segment audit row carries reason="proposal:<id>", so you can find them with:

GET /api/v1/orgs/{slug}/audit?resourceType=flag&resourceKey={key}

…and look for rows whose reason starts with proposal:.

See Agents and AI → Audit chain for the full schema and the proposal-lifecycle ↔ data-change cross-link pattern.