# Tmdb — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for movies and TV shows to discover details like cast, crew, reviews, images, videos, and where to watch them. Get information about actors, browse trending and popular titles, and access comprehensive metadata for entertainment planning.

**Category:** Entertainment | **Website:** [tmdb.org/](https://tmdb.org/) | **Docs:** [parse.bot/marketplace/bcbf6758-854b-4182-b1dc-48ce85dab515/tmdb-org-api](https://parse.bot/marketplace/bcbf6758-854b-4182-b1dc-48ce85dab515/tmdb-org-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get movie cast crew

Retrieve the full cast and crew for a movie. Cast members include name, role, profile image URL, and person ID-slug. Crew is grouped by department (Directing, Writing, etc.).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `movie_id_slug` | string | Yes | Movie ID and slug (e.g. '550-fight-club') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/get-movie-cast-crew \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"movie_id_slug":"<string>"}'
```

### Get movie details

Retrieve full metadata for a single movie by its TMDB ID-slug. Includes title, release year, user score, tagline, overview, genres, budget, revenue, keywords, and schema.org JSON-LD metadata.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `movie_id_slug` | string | Yes | Movie ID and slug (e.g. '550-fight-club', '27205-inception') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/get-movie-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"movie_id_slug":"<string>"}'
```

### Get movie images

Retrieve poster and backdrop images for a movie. Each image includes a URL and descriptive info string.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `movie_id_slug` | string | Yes | Movie ID and slug (e.g. '550-fight-club') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/get-movie-images \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"movie_id_slug":"<string>"}'
```

### Get movie reviews

Retrieve user reviews for a movie. Each review includes author, content text, and an optional numeric rating.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `movie_id_slug` | string | Yes | Movie ID and slug (e.g. '550-fight-club') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/get-movie-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"movie_id_slug":"<string>"}'
```

### Get movie videos

Retrieve video clips (trailers, teasers, featurettes) for a movie. Returns title, type, and YouTube/Vimeo URL for each video.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `movie_id_slug` | string | Yes | Movie ID and slug (e.g. '550-fight-club') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/get-movie-videos \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"movie_id_slug":"<string>"}'
```

### Get popular movies

Browse currently popular movies on TMDB. Returns a paginated list of movies with title, release date, poster URL, and ID-slug for drill-down. Optionally filter by genre name. Uses the discover endpoint sorted by popularity descending.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `genre` | string | No | Filter by genre name (e.g. 'horror', 'action', 'comedy', 'drama', 'thriller', 'science fiction', 'animation', 'adventure', 'fantasy', 'mystery', 'romance', 'documentary', 'crime', 'family', 'history', 'music', 'war', 'western', 'tv movie'). Case-insensitive. When omitted, returns all genres. |
| `page` | integer | No | Page number for pagination (1-based) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/get-popular-movies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"genre":"<string>","page":"<integer>"}'
```

### Get trending

Retrieve currently trending movies and TV shows from TMDB's trending feed. Each item carries a media type discriminator ('movie' or 'tv').

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `time_window` | string | No | Time window for trending: 'day' or 'week' |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/get-trending \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"time_window":"<string>"}'
```

### Get tv show details

Retrieve full metadata for a TV show by its TMDB ID-slug. Includes title, first air year, overview, networks, and schema.org JSON-LD metadata.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tv_id_slug` | string | Yes | TV show ID and slug (e.g. '1399-game-of-thrones', '1396-breaking-bad') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/get-tv-show-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tv_id_slug":"<string>"}'
```

### Get watch providers

Retrieve watch providers (streaming, rent, buy) for a movie or TV show in the US region. Returns provider names and logos grouped by availability type.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id_slug` | string | Yes | ID and slug of the movie or TV show (e.g. '550-fight-club') |
| `media_type` | string | Yes | Type of media: 'movie' or 'tv' |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/get-watch-providers \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"id_slug":"<string>","media_type":"<string>"}'
```

### Search

Full-text search across movies, TV shows, and people on TMDB. Returns mixed-type results ordered by relevance; each result carries a media_type discriminator.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (e.g. 'inception', 'breaking bad') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/tmdb/search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.