Sign in

v64

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-016280256.4 KB
people

Create a person

Creates a new person record (a named identity for grouping faces). 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.

post/api/people

Request body

namestring nullable

Display name for the new person (e.g., 'Alice'). Optional — unnamed people can be named later via update_person.

birth_datestring date nullable

Optional birth date (ISO 8601 date, YYYY-MM-DD) for this person.

is_hiddenboolean nullable

If true, the person is hidden from default listings. Defaults to false.

is_favoriteboolean nullable

If true, the person is marked as a favorite. Defaults to false.

thumbnail_face_idstring nullable

ID of the face to use as this person's thumbnail (with face_ prefix). Carried by the entries of an asset's faces field (returned with include=faces). The face need not already be assigned to a person.

library_idstring nullable

Library to create the person in. Optional if the user has a single library; required when they have multiple.

Response

Successful Response

idstring required

Unique person identifier with 'person_' prefix

namestring nullable

Optional name assigned to this person

birth_datestring date nullable

Optional birth date of this person

is_hiddenboolean required

Whether this person should be hidden from the UI

is_favoriteboolean required

Whether this person is marked as a favorite

asset_countinteger nullable

Number of unique photos this person appears in, or null if not computed

thumbnail_face_idstring nullable

ID of the face resource used as this person's thumbnail

asset_urlsobject nullable

Asset variants from this person's thumbnail face. May be null when embedded in an AssetResponse; use /api/people endpoints for full person data.

created_atstring date-time required

When this person record was created

updated_atstring date-time required

When this person record was last updated