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
}

DELETE /api/v1/identity/:identity_uuid

Auth: Required Scope: identity-level

Delete an identity permanently. All face detections bound to this identity are unbound (identity_id set to NULL). The identity JSON file is deleted from disk.

History & Undo/Redo

Every DELETE records a full snapshot of the identity and its unbound faces. See 14_identity_history.md for:

• Undo via POST /api/v1/identity/:identity_uuid/undo — recreates identity and re-binds faces
• Redo via POST /api/v1/identity/:identity_uuid/redo — re-deletes the identity

Note: Delete undo/redo reuses the same endpoints as PATCH undo/redo. The endpoint automatically detects whether the identity was deleted (undo) or needs to be re-deleted (redo) based on the history record.

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)

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

History & Undo/Redo

Every bind records a before/after snapshot. See 14_identity_history.md for:

• POST /api/v1/identity/:identity_uuid/bind/undo — Revert a bind
• POST /api/v1/identity/:identity_uuid/bind/redo — Reapply an undone bind
• GET /api/v1/identity/:identity_uuid/bind/history — Query bind operations

Metadata (Embedded JSON)

The identities.metadata column is a JSONB field that stores arbitrary structured data alongside the identity's core fields (name, status, identity_type). No schema is enforced — any valid JSON object is accepted.

Merge Behavior

Validation

Conventional Keys

Custom keys are fully supported — no registration required.

Search Coverage

The identity search endpoint (GET /api/v1/identity/search) matches across three scopes:

1. i.name — exact and ILIKE against display name
2. jsonb_array_elements(i.metadata->'aliases')->>'name' — locale-tagged alias names
3. i.metadata::text ILIKE $1 — raw string search across the entire JSON blob (all keys, all values)

This means searching for "1904-01-18" or "biography" will match identities whose metadata contains those strings anywhere.

History Snapshots

Every identity_history record captures the full metadata in both before_snapshot and after_snapshot (as part of the complete identity JSONB dump). Undo restores the identity row — including metadata — to the before_snapshot state.

For merge operations, the MongoDB merge history records metadata_fields_added and metadata_fields_added_paths (dot-separated paths like "tmdb.biography"). Merge undo removes only those specific paths, preserving subsequent manual edits to other metadata keys.

Best Practices

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

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

History & Undo/Redo

Trace bind operations share the same history/undo/redo system as single-face binds. See 14_identity_history.md for endpoints.

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

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
    }
  ]
}

Error Responses

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）

History & Undo/Redo

Unbind records a before/after snapshot. See 14_identity_history.md for:

• POST /api/v1/identity/:identity_uuid/bind/undo — Revert an unbind
• POST /api/v1/identity/:identity_uuid/bind/redo — Reapply an undone unbind

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

Request Parameters

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/redo）

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
  }
}

Error Responses

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

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

POST /api/v1/identity/merge/:merge_id/redo

Auth: Required Scope: identity-level

Redo a previously undone merge operation. See 14_identity_history.md for full details.

GET /api/v1/identity/merge/history

Auth: Required Scope: identity-level

Query merge history records from MongoDB.

Query Parameters

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
    }
  ]
}

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

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..."
    }
  ]
}

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:

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

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

Identity Related Data

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

Auth: Required Scope: identity-level

List all files containing this identity.

Example

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

Response (200)

{
  "success": true,
  "identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
  "total": 3,
  "files": [
    {
      "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
      "file_name": "video1.mp4",
      "face_count": 142,
      "first_appearance": 4.17,
      "last_appearance": 208.33
    }
  ]
}

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

Auth: Required Scope: identity-level

List all chunks associated with this identity (chunks where the identity's face appears).

Query Parameters

Example

curl -s "$API/api/v1/identity/$IDENTITY_UUID/chunks?page=1&page_size=50" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
  "total": 45,
  "page": 1,
  "page_size": 20,
  "chunks": [
    {
      "chunk_id": "chunk_1",
      "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
      "start_time": 4.17,
      "end_time": 8.33,
      "text": "[4s-8s] Hello, how are you?",
      "chunk_type": "story_child"
    }
  ]
}

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

Auth: Required Scope: identity-level

List all face detections for this identity.

Query Parameters

Example

curl -s "$API/api/v1/identity/$IDENTITY_UUID/faces?page=1&page_size=100" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
  "total": 1420,
  "page": 1,
  "page_size": 50,
  "faces": [
    {
      "face_id": "face_100",
      "file_uuid": "d3f9ae8e471a1fc4d47022c66091b920",
      "frame_number": 1200,
      "timestamp": 50.0,
      "bbox": [100, 50, 300, 400],
      "confidence": 0.95,
      "trace_id": 2
    }
  ]
}

GET /api/v1/identity/:identity_uuid/status

Auth: Required Scope: identity-level

Get processing/status info for an identity.

Example

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

Response (200)

{
  "success": true,
  "identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
  "name": "Audrey Hepburn",
  "status": "confirmed",
  "face_count": 1420,
  "file_count": 3,
  "has_embedding": true,
  "has_profile_image": true
}

GET /api/v1/identity/:identity_uuid/json

Auth: Required Scope: identity-level

Get the raw identity JSON file (same format as identity.json on disk).

Example

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

Response (200)

{
  "version": 1,
  "identity_uuid": "a9a90105-6d6b-46ff-92da-0c3c1a57dff4",
  "name": "Audrey Hepburn",
  "identity_type": "people",
  "source": "tmdb",
  "status": "confirmed",
  "tmdb_id": 1234,
  "tmdb_profile": "https://image.tmdb.org/...",
  "metadata": {},
  "file_bindings": [
    {"file_uuid": "d3f9ae8e...", "trace_ids": [0, 1, 2], "face_count": 142}
  ]
}

POST /api/v1/file/:file_uuid/pending-person

Auth: Required Scope: file-level

Create a manually managed "pending person" under a specific file. A pending person is an identity with status='pending' and source='manual', used for unmatched traces that the user wants to manually label before a full identity resolution.

Optionally binds a list of trace IDs to this new identity.

Request

{
  "trace_ids": [100, 150, 200],
  "name": "Mystery Man #1"
}

Example

# Create pending person with name and no traces
curl -s -X POST "$API/api/v1/file/$FILE_UUID/pending-person" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Unknown Woman #2", "trace_ids": []}'

# Create pending person with auto-name and bind traces
curl -s -X POST "$API/api/v1/file/$FILE_UUID/pending-person" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"trace_ids": [100, 150, 200]}'

Response (200)

{
  "success": true,
  "message": "Created pending person: Mystery Man #1 (uuid: 4d96b25b-68f0-4c52-b238-d69f7dfd588b)",
  "data": {
    "identity_uuid": "4d96b25b-68f0-4c52-b238-d69f7dfd588b",
    "identity_id": 55,
    "name": "Mystery Man #1",
    "bound_traces": 0
  }
}

Side Effects

• Creates an identities row with status='pending', source='manual', file_uuid=<file_uuid>
• If trace_ids provided: UPDATE face_detections SET identity_id = ... for matching traces
• If trace_ids provided: TKG face_track nodes get identity_id / identity_name in properties
• Identity JSON file synced to disk

GET /api/v1/file/:file_uuid/pending-persons

Auth: Required Scope: file-level

List all pending persons for a file.

Example

curl -s "$API/api/v1/file/$FILE_UUID/pending-persons" \
  -H "X-API-Key: $KEY"

Response (200)

{
  "success": true,
  "message": "Found 2 pending persons for c36f35685177c981aa139b66bbbccc5b",
  "data": [
    {
      "identity_uuid": "232ecd08-a2bf-4bd0-bd25-0bd8fb7a7dae",
      "identity_id": 56,
      "name": "Person 2",
      "created_at": "2026-06-23 17:13:23",
      "trace_count": 3,
      "bound_traces": null
    }
  ]
}

Notes

• Pending persons are normal identities rows with status='pending' — they can be promoted to confirmed via PATCH /api/v1/identity/:identity_uuid ({"status": "confirmed"})
• They can be merged into known identities via POST /api/v1/identity/:identity_uuid/mergeinto
• Use GET /api/v1/identity/:identity_uuid/traces to get detailed trace info for each pending person

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

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-06-20 — Added identity files, chunks, faces, status, and JSON endpoints