> ## 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. # Create a person > Creates a new person record (a named identity for grouping faces). Most people are auto-created by face clustering, so this tool is typically used only when the user explicitly wants to introduce a new identity before any faces are attached. To assign an existing face to an existing person, use `update_face` with the target `person_id`. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json post /api/people openapi: 3.1.0 info: title: Gumnut API description: API for using Gumnut to manage photos and videos version: 0.1.0 servers: [] security: [] paths: /api/people: post: tags: - people summary: Create a person description: >- Creates a new person record (a named identity for grouping faces). Most people are auto-created by face clustering, so this tool is typically used only when the user explicitly wants to introduce a new identity before any faces are attached. To assign an existing face to an existing person, use `update_face` with the target `person_id`. operationId: create_person requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PersonCreate' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PersonResponse' '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: PersonCreate: properties: name: anyOf: - type: string maxLength: 255 - type: 'null' title: Name description: >- Display name for the new person (e.g., 'Alice'). Optional — unnamed people can be named later via `update_person`. birth_date: anyOf: - type: string format: date - type: 'null' title: Birth Date description: Optional birth date (ISO 8601 date, YYYY-MM-DD) for this person. is_hidden: anyOf: - type: boolean - type: 'null' title: Is Hidden description: >- If true, the person is hidden from default listings. Defaults to false. default: false is_favorite: anyOf: - type: boolean - type: 'null' title: Is Favorite description: If true, the person is marked as a favorite. Defaults to false. default: false thumbnail_face_id: anyOf: - type: string - type: 'null' title: Thumbnail Face Id description: >- 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: anyOf: - type: string - type: 'null' title: Library Id description: >- Library to create the person in. Optional if the user has a single library; required when they have multiple. type: object title: PersonCreate PersonResponse: properties: id: type: string title: Id description: Unique person identifier with 'person_' prefix name: anyOf: - type: string - type: 'null' title: Name description: Optional name assigned to this person birth_date: anyOf: - type: string format: date - type: 'null' title: Birth Date description: Optional birth date of this person is_hidden: type: boolean title: Is Hidden description: Whether this person should be hidden from the UI is_favorite: type: boolean title: Is Favorite description: Whether this person is marked as a favorite asset_count: anyOf: - type: integer - type: 'null' title: Asset Count description: >- Number of unique photos this person appears in, or null if not computed thumbnail_face_id: anyOf: - type: string - type: 'null' title: Thumbnail Face Id description: ID of the face resource used as this person's thumbnail asset_urls: anyOf: - additionalProperties: $ref: '#/components/schemas/AssetVariant' type: object - type: 'null' title: Asset Urls description: >- 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: anyOf: - $ref: '#/components/schemas/ClusterMetricsResponse' - type: 'null' description: >- Cohesion metrics for this person's face cluster. Populated only when `include=cluster_metrics` is requested on the people endpoint, and only for persons with a populated centroid (newly-created empty Persons will have null). See `ClusterMetricsResponse` for the shape. created_at: type: string format: date-time title: Created At description: When this person record was created updated_at: type: string format: date-time title: Updated At description: When this person record was last updated type: object required: - id - is_hidden - is_favorite - created_at - updated_at title: PersonResponse description: Represents a person identified through face clustering and recognition. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AssetVariant: properties: url: type: string title: Url description: URL to fetch this image variant mimetype: type: string title: Mimetype description: MIME type of the served image width: anyOf: - type: integer - type: 'null' title: Width description: Target width in pixels (null if unknown) type: object required: - url - mimetype title: AssetVariant description: A single image variant with its URL, MIME type, and target width. ClusterMetricsResponse: properties: pairwise_p90: type: number title: Pairwise P90 description: >- 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: type: number title: Pairwise Mean description: >- Mean pairwise cosine distance between faces in this person's cluster. face_count: type: integer title: Face Count description: >- 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). type: object required: - pairwise_p90 - pairwise_mean - face_count title: ClusterMetricsResponse description: |- 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. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````