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

History & Undo/Redo

Every PATCH records a before/after snapshot in the operation history. Up to 256 records per identity are kept (oldest auto-deleted). See 14_identity_history.md for:

POST /api/v1/identity/:identity_uuid/undo — Revert PATCH changes
POST /api/v1/identity/:identity_uuid/redo — Reapply undone changes
GET /api/v1/identity/:identity_uuid/history — Query operation log

`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"

Response (200)

{
  "success": true,
  "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
  "name": "Cary Grant",
  "total": 3,
  "page": 1,
  "page_size": 20,
  "data": [
    {
      "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
      "file_name": "charade.mp4",
      "file_path": "/path/to/charade.mp4",
      "status": "done",
      "face_count": 16335,
      "speaker_count": 0,
      "first_appearance": 206.76,
      "last_appearance": 6756.68,
      "confidence": 0.8088
    }
  ]
}

Field	Type	Description
`name`	string	Identity display name
`data[].file_uuid`	string	File identifier
`data[].file_name`	string	File name
`data[].face_count`	integer	Number of face detections in this file
`data[].first_appearance`	float	First appearance time in seconds
`data[].last_appearance`	float	Last appearance time in seconds
`data[].confidence`	float	Average confidence (0.0–1.0)

`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"

Response (200)

{
  "success": true,
  "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
  "name": "Cary Grant",
  "total": 963,
  "page": 1,
  "page_size": 50,
  "data": [
    {
      "id": 3902,
      "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
      "frame_number": 37974,
      "timestamp_secs": 1518.96,
      "face_id": "37974_1",
      "confidence": 0.8197,
      "bbox": { "x": 1097, "y": 310, "width": 177, "height": 177 }
    }
  ]
}

Field	Type	Description
`name`	string	Identity display name
`data[].file_uuid`	string	File where face was detected
`data[].frame_number`	integer	Frame number of detection
`data[].face_id`	string	Face ID (format: `{frame}_{idx}`)
`data[].confidence`	float	Detection confidence

`GET /api/v1/file/:file_uuid/faces`

Auth: Required Scope: identity-level

List all face detections in a file with binding status. Each face is in one of four binding states:

State	`binding` response	Meaning
identity	`{"identity_id": 9, "identity_uuid": "...", "identity_name": "Audrey Hepburn"}`	Face matched to a known TMDb or user-defined identity
stranger	`{"stranger_id": 845, "metadata": {}}`	Face matched to an unknown person (trace not matched to any known identity)
dangling	`{"old_identity_id": 18052}`	Face was previously bound to an auto-generated identity that has been deleted (orphaned reference)
unbound	`null`	Face has no binding at all (identity_id and stranger_id are both NULL)

Query Parameters

Param	Type	Default	Description
`page`	int	1	Page number
`page_size`	int	50	Items per page
`binding`	string	—	Filter by state: `identity`, `stranger`, `dangling`, or `unbound`
`trace_id`	int	—	Filter by trace ID
`min_confidence`	float	—	Minimum detection confidence (0.0–1.0)
`start_frame`	int	—	Starting frame number (inclusive)
`end_frame`	int	—	Ending frame number (inclusive)

Example

curl -s "$API/api/v1/file/aeed71342a899fe4b4c57b7d41bcb692/faces?page=1&page_size=2&binding=identity" -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
  "total": 52244,
  "page": 1,
  "page_size": 2,
  "data": [
    {
      "id": 661508,
      "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
      "frame_number": 21297,
      "timestamp_secs": 851.88,
      "face_id": "21297_0",
      "trace_id": 485,
      "bbox": { "x": 1072, "y": 390, "width": 56, "height": 56 },
      "confidence": 0.6114,
      "binding": {
        "identity_id": 9,
        "identity_uuid": "c3545906-c82d-4b66-aa1d-150bc02decce",
        "identity_name": "Audrey Hepburn"
      }
    }
  ]
}

Field	Type	Description
`total`	int	Number of faces matching the filter (not total in file)
`data[].trace_id`	int	Face tracking trace ID
`data[].timestamp_secs`	float	Timestamp in seconds (`frame_number / fps`)
`data[].bbox`	object	Bounding box `{x, y, width, height}`
`data[].binding`	object/null	One of four binding states (see table above)

`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",
  "name": "Cary Grant",
  "total": 20,
  "page": 1,
  "page_size": 20,
  "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
`name`	string	Identity display name
`data[].file_uuid`	string	File identifier
`data[].chunk_id`	string	Sentence chunk identifier
`data[].start_frame`	integer	Frame-accurate start position
`data[].end_frame`	integer	Frame-accurate end position
`data[].fps`	float	Frames per second
`data[].start_time`	float	Start time in seconds
`data[].end_time`	float	End time in seconds
`data[].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}`)

Side Effects

清除該 face detection row 的 stranger_id（設為 NULL）
不影響 identities 表中原有的 stranger auto-identity 記錄

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/bind/trace`

Auth: Required Scope: identity-level

Bind all face detections of a trace to an identity. Updates all rows in face_detections with the matching file_uuid and trace_id.

Request Parameters

Field	Type	Required	Description
`file_uuid`	string	Yes	File where trace exists
`trace_id`	integer	Yes	Trace ID (from `face_detections.trace_id`)

Side Effects

清除該 trace 所有 face detection rows 的 stranger_id（設為 NULL）
不影響 identities 表中原有的 stranger auto-identity 記錄

Example

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

Response (200)

{
  "success": true,
  "message": "Bound trace 919 of aeed71342... to Cary Grant",
  "data": { "rows_affected": 53 }
}

Error Responses

HTTP	When
`404`	Identity not found
`500`	Database error

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

Auth: Required Scope: identity-level

Get paginated face traces (continuous tracking segments) associated with this identity across all files.

Query Parameters

Field	Type	Required	Default	Description
`page`	integer	No	`1`	Page number
`page_size`	integer	No	`20`	Items per page

Example

curl -s "$API/api/v1/identity/$IDENTITY_UUID/traces?page=1&page_size=3" \
  -H "X-API-Key: $KEY" | jq '{total, total_faces, traces}'

Response (200)

{
  "success": true,
  "identity_uuid": "a9a901056d6b46ff92da0c3c1a57dff4",
  "name": "Cary Grant",
  "total": 18,
  "page": 1,
  "page_size": 3,
  "total_faces": 542,
  "traces": [
    {
      "file_uuid": "aeed71342a899fe4b4c57b7d41bcb692",
      "trace_id": 906,
      "frame_count": 52,
      "first_frame": 37974,
      "last_frame": 38127,
      "first_sec": 1519.0,
      "last_sec": 1525.1,
      "avg_confidence": 0.8254
    }
  ]
}

Field	Type	Description
`success`	bool	Always `true`
`identity_uuid`	string	Identity UUID
`name`	string	Identity display name
`total`	integer	Total number of traces (across all pages)
`total_faces`	integer	Sum of all face detections in returned traces
`traces[].file_uuid`	string	File where trace exists
`traces[].trace_id`	integer	Trace tracking ID
`traces[].frame_count`	integer	Number of frames in this trace
`traces[].first_frame`	integer	Start frame number
`traces[].last_frame`	integer	End frame number
`traces[].first_sec`	float	Start time in seconds
`traces[].last_sec`	float	End time in seconds
`traces[].avg_confidence`	float	Average detection confidence (0.0–1.0)

Error Responses

HTTP	When
`404`	Identity not found
`500`	Database error

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

Side Effects

只清除 identity_id（設為 NULL），不會恢復 stranger_id
被 unbind 的 face 不會自動成為 stranger
要重新標記為 stranger 需重新跑 Agent API（identity/analyze）

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

Auth: Required Scope: identity-level

Transfer all face bindings from this identity to another identity, then optionally delete or mark the source as merged.

Two Merge Cases

Case	Description	Undo Support
stranger → identity	Merge an auto-generated stranger identity into a known identity (TMDb or user-defined)	✅ 24hr undo
identity A → identity B	Merge two known identities (e.g., duplicate entries)	✅ 24hr undo

Request Parameters

Field	Type	Required	Default	Description
`into_uuid`	string	Yes	—	Target identity UUID to merge into
`keep_history`	bool	No	`true`	Keep source identity record with `status='merged'` (`true`) or delete it (`false`)

Side Effects

轉移所有 face_detections.identity_id 到目標 identity
同時清除所有被轉移 rows 的 stranger_id
將 source name 加入 target aliases (with source: "merge" tag)
將 source aliases 加入 target aliases (if not already present)
將 source metadata fields 加入 target metadata (if not already present)
keep_history: true（預設）：source identity 設為 status='merged'，保留記錄
keep_history: false：刪除 source identity 及其 identity JSON 檔案
記錄 merge history 到 MongoDB（支援 undo）

Example

curl -s -X POST "$API/api/v1/identity/$SOURCE_UUID/mergeinto" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"into_uuid": "'"$TARGET_UUID"'", "keep_history": true}'

Response (200)

{
  "success": true,
  "message": "Merged 'stranger_13894' into 'Louis Viret' (52 faces transferred, history kept)",
  "data": {
    "merge_id": "550e8400-e29b-41d4-a716-446655440000",
    "faces_transferred": 52,
    "aliases_added": 1,
    "metadata_fields_added": 2
  }
}

Field	Type	Description
`merge_id`	string	Unique merge operation ID (for undo)
`faces_transferred`	integer	Number of face detections transferred
`aliases_added`	integer	Number of aliases added to target
`metadata_fields_added`	integer	Number of metadata fields added to target

Error Responses

HTTP	When
`404`	Source or target identity not found
`500`	Database error

`POST /api/v1/identity/merge/:merge_id/undo`

Auth: Required Scope: identity-level

Undo a merge operation within 24 hours. Restores the source identity and reverts face bindings.

Undo Behavior

Action	Description
Restore source identity	If `keep_history=true`: restore status to `confirmed` If `keep_history=false`: recreate identity from MongoDB snapshot
Restore faces	Transfer faces back to source identity
Remove aliases from target	Remove aliases with `source: "merge"` tag
Remove metadata fields from target	Remove fields that were added from source
Preserve manual changes	Keep aliases/metadata manually added after merge

Example

curl -s -X POST "$API/api/v1/identity/merge/550e8400-e29b-41d4-a716-446655440000/undo" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "message": "Undo merge completed: 'stranger_13894' restored, 52 faces reverted",
  "data": {
    "source_identity_restored": {
      "uuid": "a9a90105...",
      "name": "stranger_13894",
      "status": "confirmed"
    },
    "faces_reverted": 52,
    "aliases_removed_from_target": 1,
    "metadata_fields_removed_from_target": 2
  }
}

Error Responses

HTTP	When
`400`	Undo deadline expired (>24hr) or already undone
`404`	Merge record not found
`500`	Database error

`GET /api/v1/identity/merge/history`

Auth: Required Scope: identity-level

Query merge history records from MongoDB.

Query Parameters

Field	Type	Required	Default	Description
`source_uuid`	string	No	—	Filter by source identity UUID
`target_uuid`	string	No	—	Filter by target identity UUID
`merge_id`	string	No	—	Filter by specific merge ID
`undone`	bool	No	—	Filter by undone status
`page`	int	No	1	Page number
`page_size`	int	No	20	Items per page

Example

curl -s "$API/api/v1/identity/merge/history?page=1&page_size=10" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "total": 5,
  "page": 1,
  "page_size": 10,
  "results": [
    {
      "merge_id": "550e8400-e29b-41d4-a716-446655440000",
      "source_name": "stranger_13894",
      "target_name": "Louis Viret",
      "faces_transferred": 52,
      "merged_at": "2026-05-27T10:00:00Z",
      "undo_deadline": "2026-05-28T10:00:00Z",
      "undone": false,
      "undo_expired": false
    }
  ]
}

Field	Type	Description
`merge_id`	string	Unique merge operation ID
`source_name`	string	Source identity name
`target_name`	string	Target identity name
`faces_transferred`	integer	Number of faces transferred
`merged_at`	datetime	When merge occurred
`undo_deadline`	datetime	24hr deadline for undo
`undone`	bool	Whether merge was undone
`undo_expired`	bool	Whether undo deadline passed

`GET /api/v1/identities/search`

Auth: Required Scope: global / file-level

Search identity name → find associated chunks. Searches identity name and aliases, returns identities with their associated text chunks.

Query Parameters

Field	Type	Required	Default	Description
`q`	string	Yes	—	Search text (ILIKE match on name and aliases)
`file_uuid`	string	No	—	Restrict to specific file. If omitted, searches all files (global search)
`limit`	integer	No	50	Max results

Example (Global Search)

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

Example (File-specific Search)

curl -s "$API/api/v1/identities/search?q=Audrey&file_uuid=$FILE_UUID" -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "total": 5,
  "results": [
    {
      "identity_id": 9,
      "name": "Audrey Hepburn",
      "source": "tmdb",
      "tmdb_id": 1932,
      "file_uuid": "a6fb22eebefaef17e62af874997c5944",
      "trace_id": 41,
      "chunk_id": "llm_parent_..._204_207",
      "start_time": 204.162,
      "text_content": "...confrontation..."
    }
  ]
}

Field	Type	Description
`results[].identity_id`	integer	Identity ID
`results[].name`	string	Identity name
`results[].source`	string	Identity source (`tmdb`, `user_defined`, etc.)
`results[].tmdb_id`	integer	TMDb person ID (if source = tmdb)
`results[].file_uuid`	string	File where identity appears
`results[].trace_id`	integer	Face trace ID
`results[].chunk_id`	string	Associated chunk ID
`results[].start_time`	float	Chunk start time
`results[].text_content`	string	Chunk text content

`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-25 — Added GET /api/v1/file/:file_uuid/faces with 4 binding states, filters, strangers table split