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/{face_id}{
"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": {}
}Get metadata for a single face detection by ID
Fetches one face’s details (bounding box, assigned person, timestamps, thumbnail). Use when you already have a face_id.
curl --request GET \
--url https://api.example.com/api/faces/{face_id}{
"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) to fetch. Obtain from list_faces or from the faces array on get_asset / list_assets responses.
Query Parameters
Library the face belongs to. Optional if the user has a single library; required when they have multiple.
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