> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# People and Faces

> Use the Gumnut API to review face detections, add manual face boxes, and manage people assignments

Gumnut exposes two related resources for face workflows:

* `people` for grouped identities such as everyone in a library
* `faces` for individual face boxes on specific assets

Use the `people` endpoints when you want to browse or manage identities. Use the `faces` endpoints when you need to review a specific box, fix an assignment, or add a face that automatic detection missed.

## When to use `faces` vs `people`

Choose the resource that matches the job:

* Use `people` when you want the grouped identities in a library.
* Use `faces` when you need one face box on one asset.
* Use asset responses with `include=faces` when you want face boxes alongside the asset record you are already fetching.

## Add a manual face box for a missed detection

Gumnut detects faces automatically, but you can also add a manual face box when someone in an asset was missed.

When you create a manual face box:

* Use the asset's display-space pixel coordinates, matching the same `width` and `height` values the asset reports.
* Pass a `person_id` if you already know who the face belongs to.
* Create the person first if you need a brand-new identity, then attach the face to that person.
* Leave the face unassigned if you want to review it later.

<Note>
  Manual face boxes stay where you put them. If you leave one unassigned, Gumnut will not automatically group or move it later, so plan to assign it explicitly when you are ready.
</Note>

## How faces appear in responses

Manual and automatic faces use the same response shape in asset expansions and in the faces endpoints.

Use the `source` field to tell them apart:

* `automatic` for detector-found faces
* `manual` for user-drawn face boxes

A face row can also include `person_id` when the face is already assigned to a person.

## Common face-management workflows

### Review faces on an asset

Request `include=faces` when you want the face boxes alongside an asset. Use the faces endpoints directly when you need pagination, filtering, or per-face updates across many assets.

### Fix a wrong assignment without deleting the box

Update the face's `person_id` when you want to reassign it. Set `person_id` to `null` when you want to keep the face box but detach it from the current person.

### Remove a bad face box entirely

Delete the face only when the box itself should be removed. This does not delete the underlying asset or the person it was assigned to.

## Related guides

* [API Overview](./overview)
* [Requests & Responses](./requests-and-responses)
* [MCP Overview](../mcp/overview)