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.

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