Events

An event records that something in your team changed, and carries a snapshot of the object as it stood immediately afterwards. Together they form the team's change feed: a time-ordered, resumable log you can poll, replay, or have pushed to you as webhooks — and the team's record of who changed what.

Change history

The feed is the team's record of who changed what. Every event names the actor, the time it was recorded and the call that caused it, and a passport.updated event also carries the values the changed fields had before, in data.previous_attributes.

To reconstruct how one object reached its current state, filter the feed to it: GET /v1/events?object_id=pass_3e9a1c5b7d2f4083 returns every event about that passport, newest first. actor.user_id is the id GET /v1/team/members reports, which is how an actor becomes a name.

Three limits apply. Reads are not recorded — retrieving, listing or finding a passport leaves no trace in the feed or anywhere else. Batch work is recorded per batch, not per passport: rows an import wrote, passports a release cascade stamped and values a Lab transform changed appear on the import's, the run's or the Lab run's own events, not under the passport's id (see one event per call). Their per-passport detail lives on the import's rows and the Lab run's changes. And the history is as long as retention and no longer: 30 days. If you need it for longer, keep it yourself — subscribe a webhook endpoint or run a poller and store what arrives.

The event model

These are the exact bytes a webhook delivery POSTs. An event fetched from GET /v1/events/{event} and the same event received on your webhook endpoint are byte-identical, which is what lets you build against the feed first and turn on delivery later.

Snapshots

data.object is produced by the same code that serves the object's own GET, so it is byte-identical to what that endpoint would have returned at the moment of emission. A passport.updated event carries the whole passport, not a diff — you rarely need a follow-up call to find out what the object now looks like.

Two consequences worth internalising. First, the snapshot is a point-in-time value and the object may have changed again since; if you need current truth, re-fetch. Second, the snapshot reflects the object as the emitting code saw it — lab.enabled and lab.disabled have no read endpoint behind them and carry a purpose-built payload instead, {object, team, enabled, enabled_at}.

design.updated is the other side of that coin. It does have a read endpoint behind it, so its snapshot is the ordinary kind: byte-identical to what GET /v1/design would have returned at that moment.

api_key.revoked is a third case: its snapshot is the ordinary kind, but the row it describes no longer exists — so re-fetching returns 404 and the snapshot is the only record. All three api_key.* payloads omit the key's secret, which the key resource structurally cannot render.

A translated passport value appears the way a GET without lang renders it: in the ontology's default language, with language and is_fallback beside value and no translations map. Re-fetch with ?lang=all when you need every language.

Previous attributes

An update event can say what the object looked like before as well as after. data.previous_attributes holds the prior values of the fields that changed, in the same shape as data.object — and only those fields. It is present only on *.updated events whose prior values are known, which today means passport.updated; on every other event it is absent.

{
  "type": "passport.updated",
  "data": {
    "object": {
      "object": "passport",
      "id": "pass_3e9a1c5b7d2f4083",
      "friendly_id": "BAT-002",
      "publish_status": "released",
      "values": {
        "prop_ab12": { "value": 13.1 },
        "prop_cd34": { "value": "LFP" }
      }
    },
    "previous_attributes": {
      "friendly_id": "BAT-001",
      "publish_status": "draft",
      "values": {
        "prop_ab12": { "value": 12.5 },
        "prop_cd34": null
      }
    }
  }
}

On a passport it can carry friendly_id, publish_status and values; metadata is never among them, so a call that changes only metadata emits a passport.updated with no previous_attributes. Under values, a property that had no value before the change appears as null — prop_cd34 above was set for the first time. A field that did not change is not listed, so a key's absence means "unchanged", not "was empty".

Because one API call emits one event, a PATCH that changes values, friendly_id and publish_status together produces a single event whose previous_attributes holds the value each field had before the request — not some intermediate state from partway through it. Diffing previous_attributes against data.object gives you exactly what that call changed.

Translated values are compared in the same default-language rendering as the snapshot. A write that changes only another language's translation still lists the property, with the same value on both sides; re-fetch with ?lang=all to see which language moved.

Truncated snapshots

A snapshot over 64 KB is not dropped; it degrades. data.object becomes a thin reference carrying only id and object, and data.truncated appears set to true:

{
  "type": "passport.updated",
  "data": {
    "object": { "object": "passport", "id": "pass_3e9a1c5b7d2f4083" },
    "truncated": true
  }
}

Treat the presence of data.truncated as the instruction to re-fetch the object from its own endpoint. It is absent — not false — on a normal event, so test for presence rather than for a truthy value. A consumer that reads data.object fields blindly will silently see nulls on large objects, so this is worth handling on day one even if your objects are small today.

data.previous_attributes survives truncation when it fits within the size cap on its own, and is dropped when it does not — so a truncated event may or may not carry it. It is the one part a re-fetch cannot recover.

One event per call

Events are emitted once per API call, not once per changed field. A single PATCH /v1/passports/{passport} that changes property values, friendly_id, publish_status and metadata produces exactly one passport.updated, carrying the final state after all four changes.

Three related rules complete the picture:

• Reads never emit. Retrieving a passport is not recorded — here or anywhere else. Nothing you do with a GET will ever appear here.
• Batch work emits batch-level events only. A 50,000-row import produces import.started and one terminal event — never 50,000 passport.created events; walk GET /v1/imports/{import}/rows for per-row detail. A release cascade over 20,000 passports likewise produces release_run.started and one terminal release_run.* event, while releasing a single passport is an ordinary edit and emits passport.updated. The exception is a bulk data request: its children are real data requests and emit their own submit, apply and cancel events beside the set's.
• Idempotency replays never re-emit. A replayed POST returns the stored response without re-executing, so it cannot produce a second event. See idempotency.

Retention

Events are kept for 30 days, then pruned. That is one platform-wide window, the same for every team; there is no per-team retention setting — deliberately, because a webhook replay window has to mean the same thing for every consumer and every integration built against the API.

A pruned event returns 404 from GET /v1/events/{event}. A webhook delivery record can outlive the event it refers to, which is one reason a consumer reconciles by re-fetching the object rather than the event.

If your integration can be down for longer than 30 days, the feed is not your recovery mechanism — reconcile by listing the objects themselves.

List events

curl -G https://api.synexcloud.com/v1/events \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -d "types[]=passport.created" \
  -d "types[]=passport.updated" \
  -d "created[gte]=2026-07-01" \
  -d "limit=20"

{
  "object": "list",
  "data": [
    {
      "id": "evt_2c7f9a4e1b8d3506",
      "object": "event",
      "type": "passport.updated",
      "created": "2026-07-22T14:18:02Z",
      "data": {
        "object": {
          "object": "passport",
          "id": "pass_3e9a1c5b7d2f4083",
          "friendly_id": "PACK-24-0917",
          "publish_status": "released",
          "release_number": 1,
          "values": { "property_capacity": { "value": 78.4 } }
        },
        "previous_attributes": {
          "publish_status": "draft",
          "values": { "property_capacity": { "value": 76.9 } }
        }
      },
      "request_id": "req_0a9f3c2b1e4d7f0a",
      "actor": { "user_id": 118, "api_key_id": 42 }
    }
  ],
  "has_more": true,
  "next_cursor": "evt_2c7f9a4e1b8d3506",
  "url": "/v1/events"
}

Retrieve an event

curl https://api.synexcloud.com/v1/events/evt_2c7f9a4e1b8d3506 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "id": "evt_2c7f9a4e1b8d3506",
  "object": "event",
  "type": "passport.updated",
  "created": "2026-07-22T14:18:02Z",
  "data": {
    "object": {
      "object": "passport",
      "id": "pass_3e9a1c5b7d2f4083",
      "friendly_id": "PACK-24-0917",
      "publish_status": "released",
      "release_number": 1,
      "values": { "property_capacity": { "value": 78.4 } }
    },
    "previous_attributes": {
      "publish_status": "draft",
      "values": { "property_capacity": { "value": 76.9 } }
    }
  },
  "request_id": "req_0a9f3c2b1e4d7f0a",
  "actor": { "user_id": 118, "api_key_id": 42 }
}

A resumable poller

Because ids are k-sortable and the feed is ordered on them, the last event id you processed is a durable high-water mark. Poll newest-first, stop when you reach an id you have already seen, and persist the newest id of the batch:

1. GET /v1/events?limit=100 with your filters.
2. Process rows until you hit your stored high-water mark id.
3. If you did not reach it and has_more is true, follow next_cursor.
4. Store the newest id from the run and sleep until the next tick.

The created[gte] / created[lte] window is applied as bounds on the event id rather than as a scan over timestamps, so a narrow window is exact and cheap — backfilling one day out of the retained thirty costs about what reading that day costs.

For push instead of polling, register a webhook endpoint. The two are the same data; webhooks add delivery, signing and retries, and cost you a public HTTPS endpoint.

Event catalog

Forty-six types today. New ones are added over time, so a consumer that switches on type must tolerate an unrecognised value rather than failing — and a webhook endpoint subscribed with "*" receives types added after it was registered.

Most types fire on the acting team's feed only. Those marked both feeds fire on the customer's and the supplier's feed from the same change; see two teams, one change.

Remember the two catalog-wide rules when reading that list: no type fires on a read, and no type fires per-row inside a mass import or per-passport inside a release cascade.

Two teams, one change

A supplier link and a data request belong to two teams at once — the customer that asks and the supplier that answers — so the types the catalog marks both feeds are emitted to both teams from one change. Four things follow, and they are worth knowing before you build on them.

Each feed gets its own event. A data_request.applied produces one row on the customer's feed and one on the supplier's, each with its own evt_ id and its own webhook deliveries. The two share type, request_id and the object's id; nothing else is guaranteed to be identical, and a consumer sees only its own team's row. object_id filters both feeds by the same sup_, dreq_ or dset_ id.

The snapshot is the object as that side reads it. data.object is what a GET of the link or request from that team would return at that instant — a supplier.* snapshot carries role: customer on one feed and role: supplier on the other — with three subtractions on a data request. The presigned link a single read puts on file and image values never travels on the feed, since a 24-hour credential has no place in a 30-day log; the customer's copy does not carry current_value, because the passport is not read to emit an event; and there is no viewer_role, which the read endpoint stamps and the snapshot does not. Tell the sides apart by the feed you are reading, or by comparing customer_team.id and supplier_team.id with your own team's id. Re-fetch the request for any of the three.

The actor is the real person who acted, on both feeds. When Nordvolt's engineer submits, the customer's data_request.submitted names her user_id even though she is not a member of the customer team — so it is not an id the customer's GET /v1/team/members returns. actor.api_key_id is set only on the feed of the team the key is pinned to: on the other team's copy of the same event it is null, because no key of theirs was involved. The same holds when her auto_apply submission writes to the customer's passport: the passport.updated lands on the customer's feed only, naming her, with a null api_key_id. An acceptance in the web application (supplier.linked, and the .received events it triggers) has a null api_key_id on both feeds, like every change made in the application. A bulk request's create, submit and apply run as queued jobs, so the events they record — the set's and its children's — name the user who started the job, with a null api_key_id and a null request_id.

One case has no actor at all. When a request is cancelled as a side effect — its link revoked, or its passport deleted — the customer's feed names the key and user behind the revoke or delete, but the supplier's copy of data_request.cancelled carries user_id: null and api_key_id: null, and the request's own cancelled_by is null too: nobody on the supplier's side did anything, and the customer's context does not extend to their feed. Read the actor as optional everywhere and the question never comes up again.