identity agent API

Identity Agent

POST /api/v1/agents/identity/match-from-photo

Auth: Required Scope: file-level

Upload a face photo to match against known identities. Detects face via InsightFace, extracts 512D embedding via CoreML FaceNet, then searches pgvector for the closest identity.

Request

multipart/form-data with field image (JPEG/PNG) and optional file_uuid.

Example

curl -s -X POST "$API/api/v1/agents/identity/match-from-photo" \
  -H "Authorization: Bearer $JWT" \
  -F "image=@/path/to/face.jpg" \
  -F "file_uuid=$FILE_UUID"

Response (200)

{
  "success": true,
  "matches": [
    {
      "identity_uuid": "a9a90105...",
      "name": "Cary Grant",
      "similarity": 0.87
    }
  ]
}

---

POST /api/v1/agents/identity/match-from-trace

Auth: Required Scope: file-level

Match a face trace (tracked face across frames) against known identities. Samples 3 angles from the trace, generates embeddings, and searches pgvector.

Request Parameters

Field	Type	Required	Description
file_uuid	string	Yes	File containing the trace
trace_id	integer	Yes	Face trace ID to match

Example

curl -s -X POST "$API/api/v1/agents/identity/match-from-trace" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"file_uuid": "'"$FILE_UUID"'", "trace_id": 10}'

---

POST /api/v1/agents/identity/confirm

Auth: Required Scope: file-level

Confirm identity binding for a trace. This marks the trace as confirmed in TKG, updates face_detections, adds to _seeds, and optionally triggers Round 2 propagation.

Request Parameters

Field	Type	Required	Description
file_uuid	string	Yes	Video file UUID
trace_id	integer	Yes	Face trace ID to confirm
identity_id	integer	Yes	Identity internal ID
identity_uuid	string	Yes	Identity UUID
name	string	Yes	Identity name
propagate	boolean	No	Auto-trigger Round 2 matching (default: true)

Example

curl -s -X POST "$API/api/v1/agents/identity/confirm" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"file_uuid": "'"$FILE_UUID"'", "trace_id": 10, "identity_id": 42, "identity_uuid": "'"$IDENTITY_UUID"'", "name": "Cary Grant", "propagate": false}'

Response (200)

{
  "success": true,
  "file_uuid": "384b0ff44aaaa1f1",
  "trace_id": 10,
  "identity_uuid": "a9a90105...",
  "name": "Cary Grant",
  "steps": {
    "tkg_updated": true,
    "qdrant_updated": 150,
    "pg_updated": 150,
    "seed_added": true
  },
  "propagation": {
    "matched": 5,
    "message": "Propagation completed"
  }
}

Side Effects

1. TKG face_track node status → 'confirmed'
2. Qdrant _faces: identity_uuid added to payload
3. PG face_detections: identity_id set
4. Trace centroid added to _seeds (source='propagation')
5. Round 2 matching triggered (if propagate=true)

---

Updated: 2026-06-26 00:30:00

---

Version History

Version	Date	Changes
1.0	2026-10-24	Initial documentation