Skip to main content
POST
Create a person

Body

application/json
name
string | null

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

Maximum string length: 255
birth_date
string<date> | null

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

is_hidden
boolean | null
default:false

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

is_favorite
boolean | null
default:false

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

thumbnail_face_id
string | null

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_id
string | null

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.

id
string
required

Unique person identifier with 'person_' prefix

is_hidden
boolean
required

Whether this person should be hidden from the UI

is_favorite
boolean
required

Whether this person is marked as a favorite

created_at
string<date-time>
required

When this person record was created

updated_at
string<date-time>
required

When this person record was last updated

name
string | null

Optional name assigned to this person

birth_date
string<date> | null

Optional birth date of this person

asset_count
integer | null

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

thumbnail_face_id
string | null

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

asset_urls
Asset Urls · object | null

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

cluster_metrics
ClusterMetricsResponse · object | null

Cohesion metrics for this person's face cluster. Populated only when include=cluster_metrics is requested on the people endpoint, and only for persons with a populated centroid (newly-created empty Persons will have null). See ClusterMetricsResponse for the shape.