<!-- module: tmdb -->
<!-- description: TMDb enrichment endpoints — prefetch, probe, resource, check -->
<!-- depends: 01_auth, 03_register -->

## TMDb Enrichment

> **Offline operation**: TMDb prefetch now checks local identity files first (`identities/_index.json` + `*.tmdb.json`).
> If local files exist, no external API call is made. Internet is only needed for initial data seeding.

### Overview

TMDb enrichment is an optional identity enrichment step that can be run after Pipeline face detection completes. The workflow is:

1. **Prefetch** (requires internet): Download movie cast data from TMDb API → cache to `{file_uuid}.tmdb.json`
2. **Probe**: Read local cache → create identities for **all** cast members (`source='tmdb'`) + save `identity.json` + download profile image to `{OUTPUT}/identities/{uuid}/profile.jpg`
3. **Match**: The worker automatically matches video faces against TMDb identities when `MOMENTRY_TMDB_PROBE_ENABLED=true`

### `POST /api/v1/agents/tmdb/prefetch`

**Auth**: Required
**Scope**: file-level

Fetch TMDb cast data for a registered file and cache it locally. This is the only step requiring internet access.

#### Request Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file_uuid` | string | Yes | File UUID to enrich |

#### Example

```bash
curl -s -X POST "$API/api/v1/agents/tmdb/prefetch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"file_uuid": "'"$FILE_UUID"'"}'
```

#### Response (200)

```json
{"success": true, "file_uuid": "...", "cache_path": "/output/...tmdb.json"}
```

### `POST /api/v1/file/:file_uuid/tmdb-probe`

**Auth**: Required
**Scope**: file-level

Read local TMDb cache and create/update identities. Requires prefetch to have been run first.

#### Example

```bash
curl -s -X POST "$API/api/v1/file/$FILE_UUID/tmdb-probe" \
  -H "X-API-Key: $KEY" | jq '{identities_created, movie_title}'
```

#### Response (200 — identities created)

```json
{"success": true, "identities_created": 15, "movie_title": "Charade"}
```

#### Response (200 — no cache)

```json
{"success": false, "message": "No TMDb cache found. Run tmdb-prefetch first."}
```

### `GET /api/v1/resource/tmdb`

**Auth**: Required
**Scope**: system-level

View TMDb resource status including configuration, identity counts, and cache file count.

#### Example

```bash
curl -s "$API/api/v1/resource/tmdb" -H "X-API-Key: $KEY" \
  | jq '{identities_seeded, cache_files}'
```

### `POST /api/v1/resource/tmdb/check`

**Auth**: Required
**Scope**: system-level

Ping the TMDb API to verify connectivity and measure latency.

#### Example

```bash
curl -s -X POST "$API/api/v1/resource/tmdb/check" \
  -H "X-API-Key: $KEY" | jq '.status'
```

#### Response

```json
{
  "api_key_configured": true,
  "enabled": false,
  "api_reachable": true,
  "api_latency_ms": 120
}
```