---
title: "Update a face"
method: PATCH
path: "/api/faces/{face_id}"
tags: ["faces"]
---

# Update a face

`PATCH /api/faces/{face_id}`

Assigns a face to a specific person, or detaches it from its current person (set `person_id` to null). This is the right tool for 'this face is Alice' or 'this face isn't Bob after all'.

Currently only the `person_id` field is mutable. To create a brand-new identity first, call `create_person`; to delete the face detection entirely, use `delete_face`.

## Path parameters

- `face_id` string, required — Face ID (with `face_` prefix) of the face detection to update.

## Query parameters

- `library_id` string, nullable — Library the face belongs to. Optional if the user has a single live (non-trashed) library; required when they have multiple.

## Request body

- FaceUpdate
  - `person_id` string, nullable — Target person ID (with `person_` prefix) to assign this face to. Pass `null` to detach the face from its current person without deleting either. Use `create_person` first if the target identity doesn't exist yet.

## Response `200`

Successful Response

- FaceResponse — Represents a detected face in an asset with facial recognition data.
  - `id` string, required — Unique face identifier with 'face_' prefix
  - `asset_id` string, required — ID of the asset containing this face
  - `person_id` string, nullable — ID of the person this face belongs to (if identified)
  - `bounding_box` object, required — Face location as {x, y, w, h} coordinates in pixels
  - `confidence` number, nullable — Detector confidence on a 0-1 scale; higher is more confident among faces detected under the same configuration (values are not comparable across detector generations). Null on legacy faces without a stored score and on manually added faces.
  - `source` 'automatic' | 'manual', required — How this face was added: 'automatic' for detector-found faces, 'manual' for user-drawn face boxes.
  - `timestamp_ms` integer, nullable — For video files, timestamp in milliseconds when face appears
  - `asset_urls` object, nullable — Asset variants for this face: 'thumbnail' with face crop
  - `created_at` string, date-time, required — When this face was detected and recorded
  - `updated_at` string, date-time, required — When this face record was last updated
  - `cluster_assignment` ClusterAssignmentResponse — Per-face cluster-assignment diagnostics: how well the face fits its currently-assigned Person, and which other Persons are nearby in embedding space. Surfaced via ``include=cluster_assignment`` on the faces endpoints — used by the operator-facing face cleanup dashboard to triage mis-clustered faces.
    - `distance_to_person` number, nullable — Cosine distance from the face's embedding to its currently-assigned Person's centroid. Lower = better fit. Null when the face is unassigned or when the assigned Person has no centroid.
    - `candidates` FaceCandidatePersonResponse[] — Persons in the same library that pass the same gate shape as production face assignment, surfaced with deliberately relaxed thresholds so the list is a superset of what the automated path would admit. Sorted ascending by distance. Excludes the face's currently-assigned Person (its distance is in `distance_to_person`). Empty when no eligible Persons pass the gate.
      - `person_id` string, required — Person ID (with 'person_' prefix) of the candidate.
      - `name` string, nullable — Display name of the candidate Person, or null for unnamed clusters. Candidates surface the same Persons production assignment considers, which includes unnamed clusters.
      - `distance` number, required — Cosine distance from the face's embedding to this Person's centroid (lower = closer).

## 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)