> ## Documentation Index > Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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:** 1. Capture current time as `sync_end`. 2. Fetch events with `created_at_lt=sync_end`. 3. For subsequent pages, use `after_cursor={last.cursor}&created_at_lt=sync_end`. 4. Continue until `has_more=false`. 5. For each event, fetch the entity data from the appropriate endpoint if needed. 6. 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` ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json get /api/events openapi: 3.1.0 info: title: Gumnut API description: API for using Gumnut to manage photos and videos version: 0.1.0 servers: [] security: [] paths: /api/events: get: tags: - events summary: Stream entity change events description: >- 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:** 1. Capture current time as `sync_end`. 2. Fetch events with `created_at_lt=sync_end`. 3. For subsequent pages, use `after_cursor={last.cursor}&created_at_lt=sync_end`. 4. Continue until `has_more=false`. 5. For each event, fetch the entity data from the appropriate endpoint if needed. 6. 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` operationId: list_events parameters: - name: library_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Library to stream events from. Optional if the user has a single library; required when they have multiple. title: Library Id description: >- Library to stream events from. Optional if the user has a single library; required when they have multiple. - name: after_cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: >- 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. title: After Cursor description: >- 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. - name: created_at_gte in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: >- Only return events created at or after this timestamp (ISO 8601). Set this to the previous sync's checkpoint when doing incremental sync. title: Created At Gte description: >- Only return events created at or after this timestamp (ISO 8601). Set this to the previous sync's checkpoint when doing incremental sync. - name: created_at_lt in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: >- 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. title: Created At Lt description: >- 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. - name: entity_types in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- 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. title: Entity Types description: >- 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. - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: >- Maximum number of events to return per page (1–200). Defaults to 20. default: 20 title: Limit description: Maximum number of events to return per page (1–200). Defaults to 20. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/EventsResponse' '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: EventsResponse: properties: data: items: $ref: '#/components/schemas/EventResponse' type: array title: Data description: List of events, ordered by event ID (monotonically increasing) has_more: type: boolean title: Has More description: >- True if there are more events after this page. Pass the last event's `cursor` value as `after_cursor` to fetch the next page. type: object required: - data - has_more title: EventsResponse description: Response containing a page of events. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError EventResponse: properties: cursor: type: string title: Cursor description: >- Opaque cursor for pagination. Pass as after_cursor to get the next page. entity_type: type: string title: Entity Type description: Type of entity that changed (e.g., 'asset', 'album', 'person') entity_id: type: string title: Entity Id description: ID of the entity that changed event_type: type: string title: Event Type description: Semantic event type (e.g., 'asset_created', 'album_deleted') created_at: type: string format: date-time title: Created At description: When the event was recorded payload: anyOf: - additionalProperties: true type: object - type: 'null' title: Payload description: >- Optional extra context for the event (e.g., foreign keys for junction table deletions) type: object required: - cursor - entity_type - entity_id - event_type - created_at title: EventResponse description: Lightweight event record for sync endpoint. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````