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/people{
"data": [
{
"id": "<string>",
"is_hidden": true,
"is_favorite": true,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"name": "<string>",
"birth_date": "2023-12-25",
"asset_count": 123,
"thumbnail_face_id": "<string>",
"asset_urls": {}
}
],
"has_more": true
}List people in a library, optionally filtered by asset, album, name, or ID
Returns a paginated list of people (named identities that group one or more faces), ordered by creation time (newest first). Use this to enumerate who appears in the library, to resolve a user-typed name to a person_id, or to find who appears in a specific asset or album.
By default only named people are returned; pass name_filter=all or name_filter=unnamed to include clusters that haven’t been named yet.
To list the underlying faces for a specific person, use list_faces with person_id.
Pagination is cursor-based: when has_more is true, pass the id of the last person in data as starting_after_id to fetch the next page.
curl --request GET \
--url https://api.example.com/api/people{
"data": [
{
"id": "<string>",
"is_hidden": true,
"is_favorite": true,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"name": "<string>",
"birth_date": "2023-12-25",
"asset_count": 123,
"thumbnail_face_id": "<string>",
"asset_urls": {}
}
],
"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
Maximum number of people to return per page (1–200). Defaults to 20.
1 <= x <= 200Cursor for pagination. Pass the id of the last person in the previous response's data to fetch the next page. Omit for the first page.
Return only people who have at least one face in this asset. Useful for 'who is in this photo?'.
Return only people who appear in at least one asset of this album. Useful for 'who is in this album?'.
Look up specific people by ID (max 100; each ID has the person_ prefix). When set, name_filter defaults to all so unnamed clusters are included in the lookup.
Filter by name using case-insensitive substring matching. Use this to resolve a user-supplied name like 'Alice' into a person_id, then pass that ID into search_assets.person_ids or list_assets.person_id.
Filter by name status: named returns only people with a name; unnamed returns only nameless face clusters awaiting a name; all returns both. Defaults to named (or all when ids is provided).
named, unnamed, all Library to list from. Optional if the user has a single library; required when they have multiple.