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 PATCH \
--url https://api.example.com/api/faces/{face_id} \
--header 'Content-Type: application/json' \
--data '
{
"person_id": "<string>"
}
'{
"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": {}
}Assign a face to a person, or detach it from its current person
Assigns a face to a specific person, or detaches it (set person_id to null). This is the right tool for ‘this face is Alice’ or ‘this face isn’t Bob after all’.
Currently only the person_id field is mutable. To create a brand-new identity first, call create_person; to delete the face detection entirely, use delete_face.
curl --request PATCH \
--url https://api.example.com/api/faces/{face_id} \
--header 'Content-Type: application/json' \
--data '
{
"person_id": "<string>"
}
'{
"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": {}
}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.
Path Parameters
Face ID (with face_ prefix) of the face detection to update.
Query Parameters
Library the face belongs to. Optional if the user has a single library; required when they have multiple.
Body
Target person ID (with person_ prefix) to assign this face to. Pass null to detach the face from its current person without deleting either. Get IDs from list_people; use create_person first if the target identity doesn't exist yet.
Response
Successful Response
Represents a detected face in an asset with facial recognition data.
Unique face identifier with 'face_' prefix
ID of the asset containing this face
Face location as {x, y, w, h} coordinates in pixels
Show child attributes
Show child attributes
When this face was detected and recorded
When this face record was last updated
ID of the person this face belongs to (if identified)
For video files, timestamp in milliseconds when face appears
Asset variants for this face: 'thumbnail' with face crop
Show child attributes
Show child attributes