API reference

Audit log

Every path is under https://impartire.com/api/v1. Generated from the API’s own contract, openapi.json (OpenAPI 3.1), which you can load into any OpenAPI tool. Errors are Problems — see Conventions.

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_typequery · "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_idquery · string
Only entries about this resource (its id as resource.id shows it — for an asset, a version's id).
actor_kindquery · "user" | "api_key" | "oauth" | "system" | "orchestration" | "unknown"
Only entries made by this kind of actor.
actionquery · "created" | "updated" | "deleted" | "event"
Only entries with this action.
request_idquery · string
Only the entries one request produced.
sincequery · string (date-time)
Only entries strictly after this instant (ISO 8601 with offset), compared to the millisecond.
untilquery · string (date-time)
Only entries strictly before this instant (ISO 8601 with offset), compared to the millisecond.
limitquery · integer
Page size, default 50. Values above 100 are treated as 100.
cursorquery · string
next_cursor from the previous page, with the other parameters unchanged.

Response 200AuditEntryList

dataarray of AuditEntryrequired
Newest first (by occurred_at, then id).
- idstring (uuid)required
- occurred_atstring (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.
- resourceobjectrequired
  - typestringrequired
    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.
  - idstringrequired
    The changed row's id (for an asset, the version's id).
  - namestring or nullrequired
    Its name where the feed knows it; null otherwise.
- actorobjectrequired
  - 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.
  - idstring (uuid) or nullrequired
    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.
  - namestring or nullrequired
    The person's name, or the key's name.
  - client_idstring or nullrequired
    For oauth, the app's OAuth client_id when the entry records it.
- request_idstring or nullrequired
  Shared by every entry one request produced; filter by it to see a whole change.
- eventobject or nullrequired
  For an entry that records a semantic event: its kind and its public ids and names (which keys depend on the kind). Null otherwise.
  - kindstringrequired
    The event's kind, e.g. api_asset_create, legal_hold, derivation. More may be added.
- changesarray of objectrequired
  The public fields that changed. Empty for an event, for other, and when nothing public changed.
  - fieldstringrequired
    A public field of the resource. fields (an asset's or a record's field values) reports the changed KEYS only.
  - fromanyrequired
    The value before (null when created or unset); for fields, the changed keys that were present before.
  - toanyrequired
    The value after (null when deleted or cleared); for fields, the changed keys present after.
next_cursorstring or nullrequired
Pass as cursor to get the next page; null means this is the last page.

Other responses

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

idpath · string (uuid)required
The entry's id, from GET /api/v1/audit-log.
If-None-Matchheader · string
An ETag from a previous response; 304 if unchanged.

Response 200AuditEntry

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.

idstring (uuid)required
occurred_atstring (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.
resourceobjectrequired
- typestringrequired
  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.
- idstringrequired
  The changed row's id (for an asset, the version's id).
- namestring or nullrequired
  Its name where the feed knows it; null otherwise.
actorobjectrequired
- 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.
- idstring (uuid) or nullrequired
  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.
- namestring or nullrequired
  The person's name, or the key's name.
- client_idstring or nullrequired
  For oauth, the app's OAuth client_id when the entry records it.
request_idstring or nullrequired
Shared by every entry one request produced; filter by it to see a whole change.
eventobject or nullrequired
For an entry that records a semantic event: its kind and its public ids and names (which keys depend on the kind). Null otherwise.
- kindstringrequired
  The event's kind, e.g. api_asset_create, legal_hold, derivation. More may be added.
changesarray of objectrequired
The public fields that changed. Empty for an event, for other, and when nothing public changed.
- fieldstringrequired
  A public field of the resource. fields (an asset's or a record's field values) reports the changed KEYS only.
- fromanyrequired
  The value before (null when created or unset); for fields, the changed keys that were present before.
- toanyrequired
  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 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope — the key lacks a required scope.
404 not-found.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.