Audit events

Every read and mutation — through the app or the API — writes an audit event: who did it, what changed, and when. Even retrieving a passport records a read event, so the log lets you reconstruct exactly how your data reached its current state. Reading the log is a privileged operation: only team admins and owners may query it.

The audit event model

Name
object
Type
string
Description
Always audit_event.
Name
created
Type
integer
Description
Unix timestamp of the event, in seconds (e.g. 1752312660) — an integer, not an ISO string.
Name
action
Type
string
Description
The action performed, e.g. create, modify, delete, read, lab_transform, lab_rollback, or import_rows_retried. Open-ended — new action types are added over time, so treat unknown values gracefully (see Versioning). Nullable.
Name
user
Type
object
Description
The acting user, as { id, name }.
Name
passport
Type
object
Description
The affected passport, as { id, friendly_id }, or null for team-level actions that aren't scoped to a single passport.
Name
context
Type
object
Description
Action-specific payload. A modify event carries property_id, old_value, and value; other actions vary and the object may be empty.

Retention per action type is configured by team admins in the app. Lab actions such as lab_transform and lab_rollback are written here too — see Lab.

GET/v1/audit_events

List audit events

Lists the team's audit log, newest first. This is a role-gated endpoint: it requires the audit:read ability and the key's owner must be a team admin or owner at request time. Keys owned by other roles receive 403, even with audit:read.

Unlike other paginated lists, this endpoint pages at a fixed size of 25 events and ignores limit; walk the log with cursor. All filters combine with AND. The user, passport, and action filters each accept a single value or an array (repeat the key with [], e.g. action[]=create&action[]=modify).

Optional attributes

Name
created[gte]
Type
string
Description
Only events at or after this time. Unix timestamp or ISO date.
Name
created[lte]
Type
string
Description
Only events at or before this time. Unix timestamp or ISO date.
Name
user
Type
string
Description
Filter by acting user id. A single value or an array.
Name
passport
Type
string
Description
Filter by affected passport id. A single value or an array.
Name
action
Type
string
Description
Filter by action. A single value or an array, e.g. action[]=create&action[]=modify.
Name
order
Type
string
Description
asc or desc (default desc).
Name
cursor
Type
string
Description
A pagination cursor from a previous response's next_cursor.

Request

GET

/v1/audit_events

curl -G https://api.synexcloud.com/v1/audit_events \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -d "created[gte]=1751328000" \
  -d "action[]=create" \
  -d "action[]=modify" \
  -d "order=desc"

Response

{
  "object": "list",
  "data": [
    {
      "object": "audit_event",
      "created": 1752312660,
      "action": "modify",
      "user": { "id": 42, "name": "Jane Ops" },
      "passport": { "id": "pass_8f2k7d9a1b2c3d4e", "friendly_id": "PACK-001" },
      "context": {
        "property_id": "property_9f2k7d",
        "old_value": "4400",
        "value": "4500"
      }
    },
    {
      "object": "audit_event",
      "created": 1752312540,
      "action": "read",
      "user": { "id": 42, "name": "Jane Ops" },
      "passport": { "id": "pass_8f2k7d9a1b2c3d4e", "friendly_id": "PACK-001" },
      "context": {}
    },
    {
      "object": "audit_event",
      "created": 1752312000,
      "action": "lab_transform",
      "user": { "id": 7, "name": "Sam Admin" },
      "passport": null,
      "context": { "run_id": 3187, "matched": 128 }
    }
  ],
  "has_more": true,
  "next_cursor": "ae_01J8Z9QK7M4RXN",
  "url": "/v1/audit_events"
}