---
title: "Update a person"
method: PATCH
path: "/api/people/{person_id}"
tags: ["people"]
---

# Update a person

`PATCH /api/people/{person_id}`

Updates a person's name, birth date, visibility, or thumbnail. Only the fields included in the request body are changed. Typical use: assigning a name ('name this face cluster "Alice"') or choosing a better thumbnail.

This tool does not move faces between people — use `update_face` with a new `person_id` for that.

## Path parameters

- `person_id` string, required — Person ID (with `person_` prefix) of the person to update.

## Request body

- PersonUpdate
  - `name` string, nullable — New display name. Omit to leave unchanged.
  - `birth_date` string, date, nullable — New birth date (ISO 8601 date). Omit to leave unchanged.
  - `is_hidden` boolean, nullable — Hide or unhide this person. Omit to leave unchanged.
  - `is_favorite` boolean, nullable — Mark or unmark this person as a favorite. Omit to leave unchanged.
  - `thumbnail_face_id` string, nullable — New thumbnail face ID for this person. Omit to leave unchanged. Enumerate a person's faces with `list_faces` and `person_id`.

## Response `200`

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)