07 Identity - Momentry API Docs

Global Identities

`GET /api/v1/identities`

Auth: Required Scope: identity-level

List all registered identities with pagination.

Example

curl -s "$API/api/v1/identities?page=1&page_size=20" -H "X-API-Key: $KEY" | jq '{count, identities: [.identities[] | {name}]}'

`GET /api/v1/identity/:identity_uuid`

Auth: Required Scope: identity-level

Get detailed information for a specific identity, including metadata and TMDb references.

Example

curl -s "$API/api/v1/identity/$IDENTITY_UUID" -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
  "name": "Cary Grant",
  "identity_type": "people",
  "source": "tmdb",
  "status": "confirmed",
  "tmdb_id": 112,
  "tmdb_profile": "{output}/identities/{identity_uuid}/profile.jpg",
  "metadata": {},
  "reference_data": {},
  "created_at": "2026-05-16T12:00:00Z",
  "updated_at": null
}

Field	Type	Description
`identity_uuid`	string	Identity identifier
`name`	string	Identity name
`identity_type`	string	`"people"` or null
`source`	string	`.json`, `auto`, `tmdb`, `user_defined`, or `merged`
`status`	string	`"confirmed"`, `"pending"`, or `"inactive"`
`tmdb_id`	integer	TMDb person ID (only if source = tmdb)
`tmdb_profile`	string	Local profile image path (`{output}/identities/{uuid}/profile.jpg`)
`metadata`	object	Metadata JSON (tmdb_character, cast_order, etc.)
`created_at`	string	Creation timestamp

`DELETE /api/v1/identity/:identity_uuid`

Auth: Required Scope: identity-level

Delete an identity permanently.

`PATCH /api/v1/identity/:identity_uuid`

Auth: Required Scope: identity-level

Partially update an identity. Only provided fields are modified. The name field is a display label and may repeat across identities (removed UNIQUE constraint). Aliases for multilingual display are stored in metadata.aliases (see BCP 47 reference below).

Request (JSON, all fields optional)

Field	Type	Description
`name`	string	New display name
`metadata`	object	Merged into existing metadata. Use `"aliases"` key for locale-tagged names
`status`	string	`"confirmed"`, `"pending"`, or `"skipped"`
`identity_type`	string	`"people"`, `"brand"`, `"object"`, `"concept"`, etc.

Example

# Update name and add aliases
curl -s -X PATCH "$API/api/v1/identity/$IDENTITY_UUID" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "metadata": {
      "aliases": [
        {"locale": "en", "name": "John Smith"},
        {"locale": "zh-TW", "name": "約翰·史密斯"},
        {"locale": "ja", "name": "ジョン・スミス"}
      ]
    }
  }'

# Update status only
curl -s -X PATCH "$API/api/v1/identity/$IDENTITY_UUID" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "confirmed"}'

Response (200)

{
  "success": true,
  "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
  "updated_fields": ["name", "metadata"]
}

Error Responses

HTTP	When
`400`	No fields to update or invalid UUID format
`404`	Identity not found

`GET /api/v1/identity/:identity_uuid/files`

Auth: Required Scope: identity-level

Get all files where this identity appears. Returns per-file summary including face count, confidence, and appearance time range.

Example

curl -s "$API/api/v1/identity/$IDENTITY_UUID/files" -H "X-API-Key: $KEY"

`GET /api/v1/identity/:identity_uuid/faces`

Auth: Required Scope: identity-level

Get all face detection records associated with this identity.

Example

curl -s "$API/api/v1/identity/$IDENTITY_UUID/faces" -H "X-API-Key: $KEY"

Field	Type	Description
`file_uuid`	string	File where face was detected
`frame_number`	integer	Frame number of detection
`face_id`	string	Face ID (format: `face_{frame_number}`)
`confidence`	float	Detection confidence

`GET /api/v1/identity/:identity_uuid/chunks`

Auth: Required Scope: identity-level

Get all text chunks (sentences) spoken while this identity's face was on screen. Useful for finding what a person said.

Example

curl -s "$API/api/v1/identity/$IDENTITY_UUID/chunks" -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
  "data": [
    {
      "id": 0,
      "file_uuid": "bd80fec92b0b6963d177a2c55bf713e2",
      "chunk_id": "bd80fec92b0b6963d177a2c55bf713e2_2",
      "chunk_type": "sentence",
      "start_frame": 5103,
      "end_frame": 5127,
      "fps": 24.0,
      "start_time": 212.64,
      "end_time": 213.64,
      "text_content": "[213s-214s] Cary Grant: \"Olá!\""
    }
  ]
}

Field	Type	Description
`file_uuid`	string	File identifier
`chunk_id`	string	Sentence chunk identifier
`start_frame`	integer	Frame-accurate start position
`end_frame`	integer	Frame-accurate end position
`fps`	float	Frames per second
`start_time`	float	Start time in seconds
`end_time`	float	End time in seconds
`text_content`	string	Spoken text content

`POST /api/v1/identity/:identity_uuid/bind`

Auth: Required Scope: identity-level

Bind a face detection to an identity. Associates the face trace with the identity for future search and recognition.

Request Parameters

Field	Type	Required	Description
`file_uuid`	string	Yes	File where face is detected
`face_id`	string	Yes	Face ID (format: `{frame}_{idx}`)

Example

curl -s -X POST "$API/api/v1/identity/$IDENTITY_UUID/bind" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_uuid": "'"$FILE_UUID"'", "face_id": "1_5"}'

`POST /api/v1/identity/:identity_uuid/unbind`

Auth: Required Scope: identity-level

Unbind a face detection from an identity. Removes the identity association from the face record.

`GET /api/v1/identities/search`

Auth: Required Scope: identity-level

Search identities by name (ILIKE search). Returns matching identity records.

Example

curl -s "$API/api/v1/identities/search?q=Cary" -H "X-API-Key: $KEY"

Field	Type	Description
`name`	string	Identity name
`source`	string	Identity source
`tmdb_id`	integer	TMDb ID (if source = tmdb)
`file_uuid`	string	Associated file

`POST /api/v1/identity/upload`

Auth: Required Scope: identity-level

Upload an identity.json file to create or update an identity. Accepts the same format as the identity.json files stored on disk.

If an identity with the same identity_uuid already exists, it will be updated with the new values.

Request

The request body is an IdentityFile object:

Field	Type	Required	Description
`identity_uuid`	string	Yes	Identity identifier
`name`	string	Yes	Identity display name
`identity_type`	string	No	`"people"` or null
`source`	string	No	`.json`, `auto`, `tmdb`, `user_defined`, or `merged`
`status`	string	No	`"confirmed"`, `"pending"`, or `"inactive"`
`tmdb_id`	integer	No	TMDb person ID
`tmdb_profile`	string	No	TMDb profile image URL
`metadata`	object	No	Arbitrary metadata JSON
`file_bindings`	array	No	Array of `{ file_uuid, trace_ids, face_count }` (informational)

Example

curl -s -X POST "$API/api/v1/identity/upload" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
    "name": "Cary Grant",
    "identity_type": "people",
    "source": ".json",
    "status": "confirmed",
    "metadata": {},
    "file_bindings": []
  }'

Response (200)

{
  "success": true,
  "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
  "name": "Cary Grant",
  "message": "Identity uploaded successfully"
}

`POST /api/v1/identity/:identity_uuid/profile-image`

Auth: Required Scope: identity-level

Upload a profile image (JPEG or PNG) for an identity. The image is saved to {output}/identities/{uuid}/profile.{ext}.

Uses multipart/form-data with field name image.

Example

curl -s -X POST "$API/api/v1/identity/$IDENTITY_UUID/profile-image" \
  -H "X-API-Key: $KEY" \
  -F "image=@/path/to/photo.jpg"

Response (200)

{
  "success": true,
  "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
  "path": "/path/to/output/identities/.../profile.jpg",
  "message": "Profile image saved: profile.jpg"
}

Error Responses

HTTP	When
`400`	Missing image field or unsupported format
`404`	Identity not found
`415`	Unsupported image type (use JPEG or PNG)

`GET /api/v1/identity/:identity_uuid/profile-image`

Auth: Required Scope: identity-level

Retrieve the profile image for an identity. Returns the raw image data with appropriate Content-Type header.

curl -s "$API/api/v1/identity/$IDENTITY_UUID/profile-image" \
  -H "X-API-Key: $KEY" -o profile.jpg

Response Header	Value
`content-type`	`image/jpeg` or `image/png`

Alias System (BCP 47 Locale Tags)

Identity aliases support multilingual display names. Aliases are stored in metadata.aliases as an array of {locale, name} objects.

BCP 47 Locale Tags Reference

Locale	Tag	Example
English	`en`	John Smith
Traditional Chinese	`zh-TW`	約翰·史密斯
Simplified Chinese	`zh-CN`	约翰·史密斯
Japanese	`ja`	ジョン・スミス
Korean	`ko`	존 스미스
Cantonese	`yue`	約翰·史密夫
French	`fr`	John Smith (French spelling)
Spanish	`es`	Juan Smith
Arabic	`ar`	جون سميث
Russian	`ru`	Джон Смит
Thai	`th`	จอห์น สมิธ

BCP 47 is the IETF standard for language tags. Format: language (e.g. en, ja) or language-Region (e.g. zh-TW, zh-CN). Region suffix distinguishes regional variants.

Frontend Display Logic

function getDisplayName(identity, preferredLocale) {
  // 1. Exact locale match
  const match = identity.metadata?.aliases?.find(a => a.locale === preferredLocale);
  if (match) return match.name;

  // 2. Language-only match (zh-TW → zh)
  const lang = preferredLocale.split('-')[0];
  const langMatch = identity.metadata?.aliases?.find(a => a.locale.startsWith(lang));
  if (langMatch) return langMatch.name;

  // 3. Fallback to identity.name
  return identity.name;
}

Updating Aliases via PATCH

PATCH /api/v1/identity/:identity_uuid
{
  "metadata": {
    "aliases": [
      {"locale": "en", "name": "John Smith"},
      {"locale": "zh-TW", "name": "約翰·史密斯"}
    ]
  }
}

This replaces the entire aliases array. To add to existing aliases, include all existing entries in the request.

*Updated: 2026-05-22