# impartire API — Reference: Audit log

Every path is under `https://impartire.com/api/v1`. The machine-readable contract is https://impartire.com/api/v1/openapi.json (OpenAPI 3.1).

#### GET /api/v1/audit-log

List the org's audit trail

Who changed what and when, newest first, as a projected feed: each entry names the resource (a public type, its id and name), the actor, the request it belongs to, a semantic event's public ids where there is one, and the public fields that changed — never the stored row images, and only the KEYS of an asset's or a record's `fields`. Something the feed does not describe is `resource.type: other` with no name and no changes. Filters combine with AND; `since` / `until` are exclusive. An `event` entry's changes are on the entry with the same `request_id`. For an OAuth token, its person needs the view-audit-log permission (no platform-admin bypass). 404 when the org does not have the audit log, and for an OAuth token whose person may not view it.

Scopes: `audit:read`

Parameters:

- `resource_type` (query, "asset" | "file" | "project" | "collection" | "playlist" | "record" | "tag" | "tag_link" | "asset_type" | "field_definition" | "workflow" | "spec_profile" | "api_key" | "run" | "receipt" | "delivery_requirement" | "delivery_target" | "schedule_slot" | "service" | "channel" | "share_link" | "comment" | "marker" | "confirmation" | "other") — Only entries about this kind of resource.
- `resource_id` (query, string) — Only entries about this resource (its id as `resource.id` shows it — for an asset, a version's id).
- `actor_kind` (query, "user" | "api_key" | "oauth" | "system" | "orchestration" | "unknown") — Only entries made by this kind of actor.
- `action` (query, "created" | "updated" | "deleted" | "event") — Only entries with this action.
- `request_id` (query, string) — Only the entries one request produced.
- `since` (query, string (date-time)) — Only entries strictly after this instant (ISO 8601 with offset), compared to the millisecond.
- `until` (query, string (date-time)) — Only entries strictly before this instant (ISO 8601 with offset), compared to the millisecond.
- `limit` (query, integer) — Page size, default 50. Values above 100 are treated as 100.
- `cursor` (query, string) — next_cursor from the previous page, with the other parameters unchanged.

Response 200 — `AuditEntryList`

- `data` (array of AuditEntry, required) — Newest first (by `occurred_at`, then id).
  - `id` (string (uuid), required)
  - `occurred_at` (string (date-time), required)
  - `action` ("created" | "updated" | "deleted" | "event", required) — `created`, `updated`, `deleted` — the change itself. `event` — what a change MEANT (an asset created through the API, a file attached, a legal hold placed), recorded beside the change in the same request: its `changes` are on the entry with the same `request_id`.
  - `resource` (object, required)
    - `type` (string, required) — The kind of thing changed: `asset`, `file`, `project`, `collection`, `playlist`, `record`, `tag`, `tag_link`, `asset_type`, `field_definition`, `workflow`, `spec_profile`, `api_key`, `run`, `receipt`, `delivery_requirement`, `delivery_target`, `schedule_slot`, `service`, `channel`, `share_link`, `comment`, `marker`, `confirmation`, `other`. `other` is something the feed does not describe (its name and changes are withheld). More types may be added.
    - `id` (string, required) — The changed row's id (for an asset, the version's id).
    - `name` (string or null, required) — Its name where the feed knows it; null otherwise.
  - `actor` (object, required)
    - `kind` ("user" | "api_key" | "oauth" | "system" | "orchestration" | "unknown", required) — `user` — a person in the app; `api_key` — an org API key; `oauth` — an app acting for a person; `system` — the platform itself (a migration or maintenance); `orchestration` — a workflow run; `unknown` — not recorded.
    - `id` (string (uuid) or null, required) — The person's principal id (`user`, `oauth`), the key's id (`api_key`, when the entry records it), or the run's id (`orchestration`, GET /api/v1/runs/{id}); null otherwise.
    - `name` (string or null, required) — The person's name, or the key's name.
    - `client_id` (string or null, required) — For `oauth`, the app's OAuth client_id when the entry records it.
  - `request_id` (string or null, required) — Shared by every entry one request produced; filter by it to see a whole change.
  - `event` (object or null, required) — For an entry that records a semantic event: its kind and its public ids and names (which keys depend on the kind). Null otherwise.
    - `kind` (string, required) — The event's kind, e.g. `api_asset_create`, `legal_hold`, `derivation`. More may be added.
  - `changes` (array of object, required) — The public fields that changed. Empty for an `event`, for `other`, and when nothing public changed.
    - `field` (string, required) — A public field of the resource. `fields` (an asset's or a record's field values) reports the changed KEYS only.
    - `from` (any, required) — The value before (null when created or unset); for `fields`, the changed keys that were present before.
    - `to` (any, required) — The value after (null when deleted or cleared); for `fields`, the changed keys present after.
- `next_cursor` (string or null, required) — Pass as `cursor` to get the next page; null means this is the last page.

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 422 (Problem) — validation — a bad filter, `limit` or `cursor` (`errors[].path` names it).
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.

#### GET /api/v1/audit-log/{id}

Get one audit entry

One entry, in the list's shape. 404 when the org does not have the audit log, and for an OAuth token whose person may not view it.

Scopes: `audit:read`

Parameters:

- `id` (path, string (uuid), required) — The entry's id, from GET /api/v1/audit-log.
- `If-None-Match` (header, string) — An ETag from a previous response; 304 if unchanged.

Response 200 — `AuditEntry`: One entry of the org's audit trail, projected: who changed what and when, naming the public fields that changed — never the stored row images.

- `id` (string (uuid), required)
- `occurred_at` (string (date-time), required)
- `action` ("created" | "updated" | "deleted" | "event", required) — `created`, `updated`, `deleted` — the change itself. `event` — what a change MEANT (an asset created through the API, a file attached, a legal hold placed), recorded beside the change in the same request: its `changes` are on the entry with the same `request_id`.
- `resource` (object, required)
  - `type` (string, required) — The kind of thing changed: `asset`, `file`, `project`, `collection`, `playlist`, `record`, `tag`, `tag_link`, `asset_type`, `field_definition`, `workflow`, `spec_profile`, `api_key`, `run`, `receipt`, `delivery_requirement`, `delivery_target`, `schedule_slot`, `service`, `channel`, `share_link`, `comment`, `marker`, `confirmation`, `other`. `other` is something the feed does not describe (its name and changes are withheld). More types may be added.
  - `id` (string, required) — The changed row's id (for an asset, the version's id).
  - `name` (string or null, required) — Its name where the feed knows it; null otherwise.
- `actor` (object, required)
  - `kind` ("user" | "api_key" | "oauth" | "system" | "orchestration" | "unknown", required) — `user` — a person in the app; `api_key` — an org API key; `oauth` — an app acting for a person; `system` — the platform itself (a migration or maintenance); `orchestration` — a workflow run; `unknown` — not recorded.
  - `id` (string (uuid) or null, required) — The person's principal id (`user`, `oauth`), the key's id (`api_key`, when the entry records it), or the run's id (`orchestration`, GET /api/v1/runs/{id}); null otherwise.
  - `name` (string or null, required) — The person's name, or the key's name.
  - `client_id` (string or null, required) — For `oauth`, the app's OAuth client_id when the entry records it.
- `request_id` (string or null, required) — Shared by every entry one request produced; filter by it to see a whole change.
- `event` (object or null, required) — For an entry that records a semantic event: its kind and its public ids and names (which keys depend on the kind). Null otherwise.
  - `kind` (string, required) — The event's kind, e.g. `api_asset_create`, `legal_hold`, `derivation`. More may be added.
- `changes` (array of object, required) — The public fields that changed. Empty for an `event`, for `other`, and when nothing public changed.
  - `field` (string, required) — A public field of the resource. `fields` (an asset's or a record's field values) reports the changed KEYS only.
  - `from` (any, required) — The value before (null when created or unset); for `fields`, the changed keys that were present before.
  - `to` (any, required) — The value after (null when deleted or cleared); for `fields`, the changed keys present after.

Other responses:

- 304 — Not modified — the ETag in If-None-Match is current.
- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.