---
title: "Merge people"
method: POST
path: "/api/people/{person_id}/merge"
tags: ["people"]
---

# Merge people

`POST /api/people/{person_id}/merge`

Merges one or more source people into the primary person identified by the URL. All faces from source people are reassigned to the primary person. Source people are permanently deleted (this cannot be undone). The primary person's centroid embedding is recalculated.

In the degenerate case where the primary and all sources are unnamed and have zero faces, the primary is auto-deleted by the post-merge centroid recompute and the response is `204 No Content`.

## Path parameters

- `person_id` string, required — Person ID (with `person_` prefix) of the primary person that absorbs the source people. Person IDs are carried by the `id` field of person responses (e.g. `list_people`, `get_person`) and by person references on faces and assets.

## Request body

- PersonMerge
  - `source_person_ids` string[], required — IDs of the people to merge into the primary person. These people will be deleted after their faces are moved.

## 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).
    - `pairwise_p90` number, required — 90th-percentile pairwise cosine distance between faces in this person's cluster. Lower = more cohesive cluster.
    - `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

- `204` — Primary person was auto-deleted by the post-merge centroid recompute (degenerate empty-empty merge — primary and all sources unnamed with zero faces). No body returned.
- `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/revisions/2c3aca3a6e6d/schema)