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 POST \
--url https://api.example.com/api/people \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"birth_date": "2023-12-25",
"is_hidden": false,
"is_favorite": false,
"thumbnail_face_id": "<string>",
"library_id": "<string>"
}
'{
"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": {}
}Create a new person record (a named identity for grouping faces)
Creates a new person. Most people are auto-created by face clustering, so this tool is typically used only when the user explicitly wants to introduce a new identity before any faces are attached.
To assign an existing face to an existing person, use update_face with the target person_id.
curl --request POST \
--url https://api.example.com/api/people \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"birth_date": "2023-12-25",
"is_hidden": false,
"is_favorite": false,
"thumbnail_face_id": "<string>",
"library_id": "<string>"
}
'{
"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": {}
}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.
Body
Display name for the new person (e.g., 'Alice'). Optional — unnamed people can be named later via update_person.
Optional birth date (ISO 8601 date, YYYY-MM-DD) for this person.
If true, the person is hidden from default listings. Defaults to false.
If true, the person is marked as a favorite. Defaults to false.
ID of the face to use as this person's thumbnail (with face_ prefix). Typically set after the person has at least one associated face — get face IDs from list_faces.
Library to create the person in. Optional if the user has a single library; required when they have multiple.
Response
Successful Response
Represents a person identified through face clustering and recognition.
Unique person identifier with 'person_' prefix
Whether this person should be hidden from the UI
Whether this person is marked as a favorite
When this person record was created
When this person record was last updated
Optional name assigned to this person
Optional birth date of this person
Number of unique photos this person appears in, or null if not computed
ID of the face resource used as this person's thumbnail
Asset variants from this person's thumbnail face. May be null when embedded in an AssetResponse; use /api/people endpoints for full person data.
Show child attributes
Show child attributes