Trace Agent API

Manage face traces, temporal knowledge graphs, and trace-related operations.

Overview

Trace Agent API provides endpoints for: - Trace Management: List, query, and analyze face traces - Face Retrieval: Get faces from traces, representative faces - Thumbnails: Generate and retrieve trace thumbnails - TKG Operations: Build, query, and manage Temporal Knowledge Graphs - Co-occurrence: Analyze identity co-occurrence in videos

Endpoints

POST /api/v1/file/:file_uuid/traces

Auth: Required

Scope: file-level

List all traces for a file, sorted by various criteria.

Request Parameters

Field	Type	Required	Default	Description
file_uuid	string	Yes	—	File UUID (path parameter)

Example

# List traces for a file
curl -s -X POST "$API/api/v1/file/$FILE_UUID/traces" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response (200)

{
  "traces": [
    {
      "trace_id": 1,
      "face_count": 50,
      "first_frame": 100,
      "last_frame": 1500,
      "identity_uuid": "a9a90105-..."
    }
  ]
}

---

GET /api/v1/file/:file_uuid/trace/:trace_id/faces

Auth: Required

Scope: file-level

Get all faces for a specific trace.

Request Parameters

Field	Type	Required	Description
file_uuid	string	Yes	File UUID
trace_id	number	Yes	Trace ID

Example

# Get faces for trace 1
curl -s "$API/api/v1/file/$FILE_UUID/trace/1/faces" \
  -H "X-API-Key: $KEY"

---

GET /api/v1/file/:file_uuid/trace/:trace_id/representative-face

Auth: Required

Scope: file-level

Get the representative (best quality) face for a trace.

Example

# Get representative face
curl -s "$API/api/v1/file/$FILE_UUID/trace/1/representative-face" \
  -H "X-API-Key: $KEY"

---

GET /api/v1/file/:file_uuid/trace/:trace_id/thumbnail

Auth: Required

Scope: file-level

Get thumbnail for a trace.

Example

# Get trace thumbnail
curl -s "$API/api/v1/file/$FILE_UUID/trace/1/thumbnail" \
  -H "X-API-Key: $KEY"

---

GET /api/v1/file/:file_uuid/stranger/:stranger_id/representative-face

Auth: Required

Scope: file-level

Get representative face for a stranger (unidentified person).

Example

# Get stranger representative face
curl -s "$API/api/v1/file/$FILE_UUID/stranger/1/representative-face" \
  -H "X-API-Key: $KEY"

---

GET /api/v1/file/:file_uuid/stranger/:stranger_id/thumbnail

Auth: Required

Scope: file-level

Get thumbnail for a stranger.

Example

# Get stranger thumbnail
curl -s "$API/api/v1/file/$FILE_UUID/stranger/1/thumbnail" \
  -H "X-API-Key: $KEY"

---

GET /api/v1/file/:file_uuid/identities/:identity_uuid_a/co-occur-with/:identity_uuid_b

Auth: Required

Scope: file-level

Get co-occurrence information between two identities in a file.

Request Parameters

Field	Type	Required	Description
file_uuid	string	Yes	File UUID
identity_uuid_a	string	Yes	First identity UUID
identity_uuid_b	string	Yes	Second identity UUID

Example

# Check co-occurrence
curl -s "$API/api/v1/file/$FILE_UUID/identities/$IDENTITY_UUID_A/co-occur-with/$IDENTITY_UUID_B" \
  -H "X-API-Key: $KEY"

---

POST /api/v1/file/:file_uuid/tkg/rebuild

Auth: Required

Scope: file-level

Rebuild Temporal Knowledge Graph for a file.

Example

# Rebuild TKG
curl -s -X POST "$API/api/v1/file/$FILE_UUID/tkg/rebuild" \
  -H "X-API-Key: $KEY"

---

GET /api/v1/file/:file_uuid/tkg

Auth: Required

Scope: file-level

Get TKG operations for a file.

Example

# Get TKG operations
curl -s "$API/api/v1/file/$FILE_UUID/tkg" \
  -H "X-API-Key: $KEY"

---

DELETE /api/v1/file/:file_uuid/tkg

Auth: Required

Scope: file-level

Delete TKG for a file.

Example

# Delete TKG
curl -s -X DELETE "$API/api/v1/file/$FILE_UUID/tkg" \
  -H "X-API-Key: $KEY"

---

POST /api/v1/file/:file_uuid/rule2

Auth: Required

Scope: file-level

Ingest Rule 2 for TKG.

Example

# Ingest Rule 2
curl -s -X POST "$API/api/v1/file/$FILE_UUID/rule2" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

---

GET /api/v1/file/:file_uuid/representative-frame

Auth: Required

Scope: file-level

Get representative frame for a file.

Example

# Get representative frame
curl -s "$API/api/v1/file/$FILE_UUID/representative-frame" \
  -H "X-API-Key: $KEY"

---

POST /api/v1/file/:file_uuid/tkg/nodes

Auth: Required

Scope: file-level

Query TKG nodes.

Example

# Query TKG nodes
curl -s -X POST "$API/api/v1/file/$FILE_UUID/tkg/nodes" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

---

POST /api/v1/file/:file_uuid/tkg/edges

Auth: Required

Scope: file-level

Query TKG edges.

Example

# Query TKG edges
curl -s -X POST "$API/api/v1/file/$FILE_UUID/tkg/edges" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

---

Implementation Details

File: /Users/accusys/momentry_core/src/api/trace_agent_api.rs (2918 lines)

Data Structures: - Trace - Face trace object - Face - Single face detection - TKG - Temporal Knowledge Graph - Stranger - Unidentified person

Database Tables: - face_detections - Face detection records - traces - Trace metadata - tkg_nodes - TKG nodes - tkg_edges - TKG edges

---

Related Documentation

• Identity API
• Profile API
• TKG API

---

Common Issues

Trace Not Found

Symptoms: 404 error when accessing trace

Solution: Check if trace exists in database or re-process the file

TKG Build Failed

Symptoms: TKG rebuild returns error

Solution: Check file processing status and logs

---

Version History

Version	Date	Changes
1.0	2026-10-24	Initial documentation (summary)

Note: This is a summary documentation. Full endpoint details require additional work.