# Tmdb — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/get_movie_cast_crew \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/get_movie_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/get_movie_images \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/get_movie_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/get_movie_videos \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/get_popular_movies \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/get_trending \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/get_tv_show_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/get_watch_providers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-tmdb-org-api-bcbf6758/search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```