API reference · API 1.0.0

Audit

The platform audit log: every recorded change, read-only.

get /api/v1/audit-events

List audit events

Operation audit_events_list · bearer token

Every recorded change on this platform, newest first (occurred_at, then id, descending). Pages are cursor-based and stable while new events are written: pass next_cursor as cursor to get the next page; it is null on the last one. A cursor that is not one of this list's is a 400 invalid_cursor.

Filters combine with AND, and every one is exact unless stated: actor (an e-mail address or other actor string, compared lower-cased; or a user id, which matches the events recorded under that person's CURRENT address — events recorded under an earlier address need that address), auth_kind, token_id, request_id, entity_type, entity_id, action (exact, or a PREFIX when it ends in *: user.* matches user.create and user.role_grant; * alone matches every action), occurred_from (inclusive) and occurred_to (EXCLUSIVE). A range whose end is not after its start is simply empty.

before_state and after_state are returned as the writer recorded them, except that every member whose name looks secret is null. For entity_type licence the entity_id is the licence serial, masked to its last group unless the caller holds licence-admin-global, as on GET /licence; the entity_id filter matches the stored id, never the masked one. Reading the log is not itself audited.

Parameters

Name	In	Type	Description
`actor`	query	string \| null	Exact actor: an e-mail address (compared lower-cased), `system`, `pipeline:<run id>`…, or a user id (UUID) for that person's events. min length 1 · max length 320
`auth_kind`	query	string \| null	How the actor authenticated. one of `session`, `pat`, `service_account`
`token_id`	query	string (uuid) \| null	Events made with this API token.
`request_id`	query	string \| null	Events of one request (`X-Request-ID`). min length 1 · max length 200
`entity_type`	query	string \| null	Exact entity type, e.g. `users`. min length 1 · max length 200
`entity_id`	query	string \| null	Exact entity id, as the writer spelled it. min length 1 · max length 500
`action`	query	string \| null	Exact action, or a prefix when it ends in `` (`user.`). min length 1 · max length 200
`occurred_from`	query	string (date-time) \| null	Events at or after this time (inclusive). RFC 3339; without an offset, UTC.
`occurred_to`	query	string (date-time) \| null	Events BEFORE this time (exclusive). RFC 3339; without an offset, UTC.
`limit`	query	integer	Page size (at most 500). min 1 · max 500 · default `50`
`cursor`	query	string \| null	`next_cursor` from the previous page; omit it for the first page. A cursor this list did not issue is a 400 `invalid_cursor`.

Responses

200

One page of audit events, newest first.

application/json → AuditEventPage

Headers: X-Request-ID
401

Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

application/jsonapplication/problem+json → Problem

Headers: WWW-Authenticate, X-Request-ID
403

The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

application/jsonapplication/problem+json → Problem

Headers: X-Request-ID
429

More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

application/jsonapplication/problem+json → Problem

Headers: Retry-After, X-Request-ID
503

The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

application/jsonapplication/problem+json → Problem

Headers: Retry-After, X-Request-ID
default

Problem details (RFC 9457)

application/jsonapplication/problem+json → Problem

Headers: X-Request-ID

get /api/v1/audit-events/{event_id}

One audit event

Operation audit_events_get · bearer token

One event by id, with the same secret-looking members withheld and the same licence serial masking as in the list.

Parameters

Name	In	Type	Description
`event_id`required	path	string	The event's id. pattern `^[1-9][0-9]{0,8}$`

Responses

200

The audit event.

application/json → AuditEvent

Headers: X-Request-ID
401

Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

application/jsonapplication/problem+json → Problem

Headers: WWW-Authenticate, X-Request-ID
403

The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

application/jsonapplication/problem+json → Problem

Headers: X-Request-ID
404

No such event (audit_event_not_found).

application/jsonapplication/problem+json → Problem

Headers: X-Request-ID
429

More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

application/jsonapplication/problem+json → Problem

Headers: Retry-After, X-Request-ID
503

The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

application/jsonapplication/problem+json → Problem

Headers: Retry-After, X-Request-ID
default

Problem details (RFC 9457)

application/jsonapplication/problem+json → Problem

Headers: X-Request-ID

Rendered from openapi-v1.json, platform release 1.0.187. Your installation serves the contract of its own version at /api/v1/openapi.json.