---
title: "Create a person"
method: POST
path: "/api/people"
tags: ["people"]
---

# Create a person

`POST /api/people`

Creates a person record for grouping faces. The record may initially have no name and no faces.

To assign an existing face to an existing person, use `update_face` with the target `person_id`.

## Request body

- PersonCreate
  - `name` string, nullable — Display name for the new person (e.g., 'Alice'). Optional — unnamed people can be named later via `update_person`.
  - `birth_date` string, date, nullable — Optional birth date (ISO 8601 date, YYYY-MM-DD) for this person.
  - `is_hidden` boolean, nullable — If true, the person is hidden from default listings. Defaults to false.
  - `is_favorite` boolean, nullable — If true, the person is marked as a favorite. Defaults to false.
  - `thumbnail_face_id` string, 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_id` string, nullable — Library to create the person in. Optional if the user has a single live (non-trashed) library; required when they have multiple.

## Response `201`

Successful Response

- PersonResponse — Represents a person identified through face clustering and recognition.
  - `id` string, required — Unique person identifier with 'person_' prefix
  - `name` string, nullable — Optional name assigned to this person
  - `birth_date` string, date, nullable — Optional birth date of this person
  - `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
  - `asset_count` integer, nullable — Number of unique photos this person appears in, or null if not computed
  - `thumbnail_face_id` string, nullable — ID of the face resource used as this person's thumbnail
  - `asset_urls` object, 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.
  - `cluster_metrics` ClusterMetricsResponse — Cohesion metrics for a Person's face cluster — surfaced via ``include=cluster_metrics`` on the people endpoints. These describe how tight the cluster is in embedding space (lower = more cohesive) and drive both the production face-assignment cohesion gate and the operator-facing face cleanup dashboard.
    - `pairwise_p90` number, required — 90th-percentile pairwise cosine distance between faces in this person's cluster. Lower = more cohesive cluster; loose clusters (higher pairwise_p90) are gated out of the face-assignment path to prevent further drift.
    - `pairwise_mean` number, required — Mean pairwise cosine distance between faces in this person's cluster.
    - `face_count` integer, required — Number of faces that fed into the centroid and pairwise metrics. This is the cluster-membership count, **not** the same as `asset_count` — `face_count` counts every face row, while `asset_count` counts distinct assets (one asset can contribute multiple faces of the same person).
  - `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

## Other responses

- `401` — Missing, invalid, or expired credentials.
- `403` — The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept.
- `404` — Not found
- `422` — Validation Error
- `429` — Rate limit exceeded. Retry after the interval in the `Retry-After` header.

---

[API](https://skmtc.net/gumnut-ai/apis/gumnut-api.md) · [All operations](https://skmtc.net/gumnut-ai/apis/gumnut-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gumnut-ai/gumnut-api/versions/e71db45f5d4a/schema)