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/faces{
"data": [
{
"id": "<string>",
"asset_id": "<string>",
"bounding_box": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"person_id": "<string>",
"timestamp_ms": 123,
"asset_urls": {}
}
],
"has_more": true
}List individual face detections, optionally filtered by asset, person, or ID
Returns a paginated list of individual face detections (with bounding boxes), ordered by creation time (newest first). Each row is a single face in a single asset — a person with many photos will have many face rows.
Use list_people instead when the user wants the grouped identities (‘list everyone in my library’) rather than individual face detections. This tool is useful for curating clustering results, finding unassigned faces, or picking a thumbnail face for a person via update_person.thumbnail_face_id.
Pagination is cursor-based: when has_more is true, pass the id of the last face in data as starting_after_id to fetch the next page.
curl --request GET \
--url https://api.example.com/api/faces{
"data": [
{
"id": "<string>",
"asset_id": "<string>",
"bounding_box": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"person_id": "<string>",
"timestamp_ms": 123,
"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
Return only faces detected in this asset. Useful for 'show me all the faces in this photo'.
Return only faces currently assigned to this person. Useful for reviewing or curating a person's face cluster.
Look up specific faces by ID (max 100). IDs use the face_ prefix.
Maximum number of faces per page (1–200). Defaults to 20.
1 <= x <= 200Cursor for pagination. Pass the id of the last face in the previous response's data to fetch the next page. Omit for the first page.
Library to list from. Optional if the user has a single library; required when they have multiple.