oauth
assets
- GETList assets in a library, optionally filtered by album, person, date range, or asset ID
- POSTUpload a new asset
- DELPermanently delete the specified assets and their underlying files
- GETGet asset counts
- POSTCheck asset existence
- POSTMove assets to trash
- POSTRestore assets from trash
- POSTPermanently delete every trashed asset in the library
- GETGet full metadata for a single asset by ID
- DELPermanently delete an asset and its underlying file
album-assets
albums
- GETList albums in a library, optionally filtered by asset membership or ID
- POSTCreate a new, empty album in a library
- GETGet metadata for a single album by ID
- DELDelete an album (the assets inside it are kept)
- PATCHRename an album or change its description
- POSTAdd existing assets to an album
- DELRemove assets from an album (assets themselves are kept)
libraries
faces
people
- GETList people in a library, optionally filtered by asset, album, name, or ID
- POSTCreate a new person record (a named identity for grouping faces)
- GETGet metadata for a single person by ID
- DELDelete a person record; its faces become unassigned and will be re-clustered
- PATCHUpdate a person's name, birth date, visibility, or thumbnail
- POSTMerge people
server
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
}Stream entity change events for client sync (use to keep a local cache in sync)
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_endas 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_deletedalbum_created,album_updated,album_deletedperson_created,person_updated,person_deletedface_created,face_updated,face_deletedalbum_asset_added,album_asset_removedexif_created,exif_updated,exif_deletedmetadata_updated(emitted alongsideexif_updatedduring the asset_metadata migration window;exif_*events are deprecated and will be removed in a future release)
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
}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.
Query Parameters
Library to stream events from. Optional if the user has a single library; required when they have multiple. Use list_libraries to enumerate.
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.
Only return events created at or after this timestamp (ISO 8601). Set this to the previous sync's checkpoint when doing incremental sync.
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.
Comma-separated list of entity types to include (e.g., asset,album). Valid values: asset, album, person, face, album_asset, exif, metadata. Omit to receive events for all types.
Maximum number of events to return per page (1–200). Defaults to 20.
1 <= x <= 200Response
Successful Response
Response containing a page of events.