Stream entity change events

curl --request GET \
  --url https://api.example.com/api/events

{
  "data": [
    {
      "cursor": "<string>",
      "entity_type": "<string>",
      "entity_id": "<string>",
      "event_type": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "payload": {}
    }
  ],
  "has_more": true
}

events

Stream entity change events

Returns a paginated stream of change events (create/update/delete) for entities in the library. Each event is a lightweight record — entity_type, entity_id, event_type, and timestamps — pointing at a concrete entity that has changed. Follow up with get_asset, get_album, get_person, or get_face to fetch full entity data when needed.

Use this tool when the user wants to synchronise a local copy of their library, audit recent activity, or detect deletions. Don’t use it for content queries — use search_assets or list_assets instead. Events cannot be filtered by content or asset metadata.

Pagination: cursor-based via after_cursor. When has_more is true, pass the last event’s cursor value into after_cursor to fetch the next page.

Recommended sync pattern:

Capture current time as sync_end.
Fetch events with created_at_lt=sync_end.
For subsequent pages, use after_cursor={last.cursor}&created_at_lt=sync_end.
Continue until has_more=false.
For each event, fetch the entity data from the appropriate endpoint if needed.
Store sync_end as checkpoint for next sync.

Handling deletions: when event_type ends with _deleted or _removed, the entity no longer exists — remove it from the local cache. Some deletion events include a payload field with context (e.g., album_asset_removed carries album_id and asset_id since the junction row is gone).

Event types:

asset_created, asset_updated, asset_deleted
album_created, album_updated, album_deleted
person_created, person_updated, person_deleted
face_created, face_updated, face_deleted
album_asset_added, album_asset_removed
metadata_updated

GET

api

events

Stream entity change events

curl --request GET \
  --url https://api.example.com/api/events

{
  "data": [
    {
      "cursor": "<string>",
      "entity_type": "<string>",
      "entity_id": "<string>",
      "event_type": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "payload": {}
    }
  ],
  "has_more": true
}

Query Parameters

library_id

string | null

Library to stream events from. Optional if the user has a single library; required when they have multiple. Use list_libraries to enumerate.

after_cursor

string | null

Opaque cursor from the last event of the previous page. Pass the cursor field from the last event to fetch the next page. Omit for the first page.

created_at_gte

string<date-time> | null

Only return events created at or after this timestamp (ISO 8601). Set this to the previous sync's checkpoint when doing incremental sync.

created_at_lt

string<date-time> | null

Only return events created strictly before this timestamp (ISO 8601). Recommended for bounding a sync operation — capture now once and reuse it as created_at_lt across all pages so newly arriving events don't shift the window.

entity_types

string[] | null

Entity types to include (e.g., asset, album). Valid values: asset, album, person, face, album_asset, metadata. Accepts multiple entity_types= query params or a single comma-delimited value (e.g., entity_types=asset,album). Omit to receive events for all types.

limit

integer

default:20

Maximum number of events to return per page (1–200). Defaults to 20.

Required range: 1 <= x <= 200

Response

Successful Response

Response containing a page of events.

data

EventResponse · object[]

required

List of events, ordered by event ID (monotonically increasing)

Show child attributes

has_more

boolean

required

True if there are more events after this page. Pass the last event's cursor value as after_cursor to fetch the next page.

Remove assets from an album

List libraries