Prerequisites
- An API key with read access to the library
- The Python SDK
gumnut-sdk0.168.0 or later, for the examples on this page
How the feed behaves
GET /api/events returns events in pages, each with an opaque cursor:
- Nothing is skipped. Reading forward from a stored cursor returns every event committed after it, each once. A cursor is the only checkpoint you need.
- Events are not in commit order. Two changes to one entity can arrive in either order, so apply an event by reading the entity’s current state, not by replaying the change.
- Events can trail their commit. An event appears once every write that started before it has finished, so a change can take a moment to show up.
created_at is when the change’s transaction started. Use it for display only:
it is neither the feed order nor a checkpoint, and a later event can carry an
earlier time.
Sync a library
- Load your stored cursor, or start with none for a first sync.
- Request a page with
after_cursorset to that cursor. - Apply each event, as described below.
- After applying the page, store its
next_cursor. - Repeat until
has_moreisfalse. You are caught up; the next sync starts again at step 1.
store stands for your local storage, keyed by entity type and ID. Save the
cursor in the same place as the data, ideally in the same transaction, so the
two can’t drift apart.
Make applying an event idempotent. If your client stops after applying a page
but before storing its cursor, the next sync replays that page.
While has_more is true, next_cursor also bounds the read to events that
were ready when it began, so a busy library can’t keep a sync running forever.
Changes made during the sync arrive in the next one. Pass the same library_id,
entity_types, and created_at_gte on every page.
Apply events
Treat every event as “this changed”: read the entity’s current state and upsert it, or remove your copy when the read no longer returns it. Because you always apply current state, events that arrive out of order still leave you correct. Read that state from the list endpoints, passing the feed’slibrary_id and
the ids, as the example does. An asset can move to another library and keep
its ID, and GET /api/assets/{id} isn’t scoped to a library: it still returns
an asset that moved to another library you can read. Don’t use it to decide
whether an asset belongs to the library you are syncing. This holds for every
event whose entity_id is an asset ID, which is every event with entity_type
asset or metadata, whatever its event_type.
Re-reads count against your rate limit. The list
endpoints accept up to 200 ids, so read a page’s entities of each type in one
call rather than one call per event.
- Deletions. Event types ending in
_deletedor_removedmean the entity is gone. A read omits it, so the same rule removes your copy. - Trash.
asset_trashedmoves an asset to the trash, where a default read omits it, andasset_restoredbrings it back. Both also hide or reveal the asset’s faces and album memberships, and change its people’s and stack’s counts, without events of their own. On either event, re-read the asset’s faces and memberships byasset_id, as the example does for memberships: a trashed asset returns none. Then refetch by ID the people and stack that your copy of its faces and of the asset names, before you drop that copy. To keep trashed assets in your copy, passstate="all"to the asset read. It returns them too, withtrashed_atset, so an asset it omits was permanently deleted or has left the library. - Moves between libraries. A move records
asset_moved_outin the library the asset left andasset_moved_inin the library it joined. Neither has apayloador names the other library.asset_moved_outisn’t a deletion: the asset may have moved back by the time you read the event, so re-read it like any other asset. When the read omits it, remove it and its faces and memberships from your copy of this library only. Its people’s face counts change, so refetch by ID the people that your copy of its faces names, before you drop that copy. Each moved face that a person had also records aface_updatedin the library it left, with anullperson_idand that person asprevious_person_id. The face read may omit that face; refetch the person either way. In the library it joined, its faces keep their IDs too, but it arrives in no album or stack and with its faces assigned to no person.asset_moved_incomes with ametadata_updatedfor the asset and aface_createdfor each face. People, albums, and stacks don’t move. - Album membership. Each add creates a new membership with its own ID, so
re-read memberships by ID like any other entity. Removing one, permanently
deleting its asset, or moving its asset to another library records an
album_asset_removedwhosepayloadnames thealbum_idandasset_id. Deleting an album doesn’t:album_deletedmeans its memberships are gone too, so remove them with the album. To learn of those, requestalbumevents along withalbum_asset. - People and faces. A person’s face and asset counts change through its
faces, so they arrive as
face_*events, notperson_updated. Aface_updatedpayload names the face’sperson_idandprevious_person_id, and aface_deletedpayload carriesprevious_person_id. Refetch each person that isn’tnull, whether or not the read returns the face, and expect a404for one deleted in the same change.
READERS
and apply the rules above.
If your sync also needs stack members, request include=asset_ids on each
list_stacks page. The response includes live member IDs in capture-time order,
and asset_count matches that list. Trashed members are excluded. Without the
expansion, asset_ids is null; a stack with no live members has an empty
list. This lets you read members for all stacks on a page without a separate
asset-list request for each stack.
The GET /api/events page in the API Reference tab lists the event types.
Request only the entity types you apply. Within them, re-read state for any
event type your client doesn’t recognize rather than failing.
Sync several entity types together
Some clients read one entity type at a time, such as albums before the photos in them. Each read stops at its own point, so a later read could include a change an earlier one stopped short of. Every response includesas_of, the point that read stopped at. Pass the first
response’s as_of to every other read in the same sync so they all stop at the
same point:
as_of: it belongs to one
sync. A shared as_of stops every read at one point, but an entity can still
arrive before an entity it refers to. Let your client tolerate a missing
reference until a later event fills it in.
Handle errors
GET /api/events returns 400 for:
- an unknown entity type
- a malformed
after_cursororas_of - an
after_cursororas_ofahead of the server, as after a restore that went back in time