GUgumnut-ai
people

Create a person

Changed on

Creates a person record to group faces, or reuses a matching named person without changing it. Does not delete existing records or move faces. The API checks names within the library, including hidden people, ignoring case and surrounding whitespace. Returns 201 for a new record or 200 for an existing matching name. Only supplied create fields must match; omitted fields leave existing values intact. A different supplied value returns 409 without changing the record; repeating that request does not resolve the conflict. Unnamed creates always make a new person. A new person record groups faces. The record may initially have no name and no faces.

To assign an existing face to an existing person, use update_face with the target person_id.

post/api/people

Request

  • Base URL
    https://api.gumnut.ai
  • Auth
    • HTTP bearer
    • or HTTP bearer

Request body

namestring nullable

Display name for the new person (e.g., 'Alice'). Optional — unnamed people can be named later via update_person. If supplied, it must not be blank; surrounding whitespace is trimmed.

birth_datestring date nullable

Optional birth date (ISO 8601 date, YYYY-MM-DD) for this person.

is_hiddenboolean nullable

If true, the person is hidden from default listings. Defaults to false.

is_favoriteboolean nullable

If true, the person is marked as a favorite. Defaults to false.

thumbnail_face_idstring nullable

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_idstring nullable

Library to create the person in. Optional if the user has a single live (non-trashed) library; required when they have multiple.

Response

Existing matching person

idstring required

Unique person identifier with 'person_' prefix

namestring nullable

Name assigned to this person, or null when unnamed. Names supplied as text on create or update are trimmed and must not be blank.

birth_datestring date nullable

Optional birth date of this person

is_hiddenboolean required

Whether this person should be hidden from the UI

is_favoriteboolean required

Whether this person is marked as a favorite

asset_countinteger nullable

Number of unique photos this person appears in, by a face or a body linked to them, or null if not computed

thumbnail_face_idstring nullable

ID of the face resource used as this person's thumbnail

asset_urlsobject 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.

created_atstring date-time required

When this person record was created

updated_atstring date-time required

When this person record was last updated

Changes

  • 7c2860d9eb88Revision changes
    • breaking

      the / request property's minLength was increased from 0 to 1

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the success response with the status

  • 815e0302a988Revision changes
    • breaking

      response property detail list-of-types was widened by adding types string to media type application/json of response 422

    • info

      the response property became required for the status