# Movies & TV API — unified movie and TV metadata plus streaming availability: search, full details, cast and crew, seasons and episodes, discover/browse with filters, reviews, images, trailers, where-to-watch by region, charts and recommendations (TMDB, TVmaze, JustWatch)

> search titles (type=multi|movie|tv|streaming)
> ReefAPI engine `movies-tv` · 23 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/movies-tv/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /movies-tv/v1/search — 1 credit
search titles (type=multi|movie|tv|streaming)

**Parameters:**
- `query` (string, required) — Free-text title/person search keywords.
- `type` (enum, optional, default "multi") — Which catalog to search. tv also accepts 'show'/'series'. [one of: multi, movie, tv, streaming]
- `limit` (integer, optional, default 10) — Max results to return.
- `year` (integer, optional) — Release-year filter (movie search / streaming match).
- `country` (string, optional, default "US") — JustWatch market — ISO-3166-1 alpha-2 (~140 supported). Controls streaming offers / services / new-titles region.
- `page` (integer, optional, default 1) — TMDB result page (movie/multi search only).
- `language` (string, optional) — Display locale for TMDB movie/multi search (e.g. de-DE, es-ES, ja-JP).

**Returns:** results[] (shape depends on type: title rows with ids {imdb,tmdb,tvmaze} + year/overview; streaming rows carry offers), query, type

**Example request body:**
```json
{
  "query": "breaking bad",
  "type": "tv"
}
```

### POST /movies-tv/v1/detail — 2 credits
unified title detail (tv→TVmaze, movie→TMDB depth + JustWatch offers)

**Parameters:**
- `id` (string, required) — Title id. By default a TVmaze id (TV) or TMDB id (movie); an imdb id (tt0903747) is auto-detected. Set id_type to be explicit.
- `type` (enum, optional) — Whether the id/query is a movie or a TV show. Defaults to TV unless the id is a tmdb id or looks like a movie. [one of: movie, tv]
- `id_type` (enum, optional) — How to interpret `id`. Auto-detected (imdb if it starts with 'tt', else tvmaze for TV / tmdb for movie) when omitted. [one of: tvmaze, tmdb, imdb]
- `country` (string, optional, default "US") — JustWatch market — ISO-3166-1 alpha-2 (~140 supported). Controls streaming offers / services / new-titles region.
- `include_streaming` (boolean, optional, default true) — Merge JustWatch where-to-watch offers into the detail record.
- `language` (string, optional) — Display locale for movie titles/overview (TMDB; e.g. de-DE, fr-FR, ja-JP).

**Returns:** full title record: title, genres, overview, ids, ratings, cast/crew; movie adds runtime/budget/revenue; +streaming_offers when include_streaming

**Example request body:**
```json
{
  "id": 169,
  "type": "tv"
}
```

### POST /movies-tv/v1/episodes — 1 credit
TV episodes (optionally one season)

**Parameters:**
- `id` (string, required) — Title id. By default a TVmaze id (TV) or TMDB id (movie); an imdb id (tt0903747) is auto-detected. Set id_type to be explicit.
- `id_type` (enum, optional) — How to interpret `id`. Auto-detected (imdb if it starts with 'tt', else tvmaze for TV / tmdb for movie) when omitted. [one of: tvmaze, tmdb, imdb]
- `season` (integer, optional) — Limit to one season number (omit for all).
- `specials` (boolean, optional, default false) — Include special (non-numbered) episodes.

**Returns:** tvmaze_id, season, episodes[]{name, season, number, airdate, runtime}

**Example request body:**
```json
{
  "id": 169,
  "type": "tv"
}
```

### POST /movies-tv/v1/cast — 1 credit
cast (tv→TVmaze, movie→TMDB)

**Parameters:**
- `id` (string, required) — Title id. By default a TVmaze id (TV) or TMDB id (movie); an imdb id (tt0903747) is auto-detected. Set id_type to be explicit.
- `type` (enum, optional) — Whether the id/query is a movie or a TV show. Defaults to TV unless the id is a tmdb id or looks like a movie. [one of: movie, tv]
- `id_type` (enum, optional) — How to interpret `id`. Auto-detected (imdb if it starts with 'tt', else tvmaze for TV / tmdb for movie) when omitted. [one of: tvmaze, tmdb, imdb]

**Returns:** cast[]{person, character, ...}

**Example request body:**
```json
{
  "id": 169,
  "type": "tv"
}
```

### POST /movies-tv/v1/crew — 1 credit
crew (tv→TVmaze, movie→TMDB)

**Parameters:**
- `id` (string, required) — Title id. By default a TVmaze id (TV) or TMDB id (movie); an imdb id (tt0903747) is auto-detected. Set id_type to be explicit.
- `type` (enum, optional) — Whether the id/query is a movie or a TV show. Defaults to TV unless the id is a tmdb id or looks like a movie. [one of: movie, tv]
- `id_type` (enum, optional) — How to interpret `id`. Auto-detected (imdb if it starts with 'tt', else tvmaze for TV / tmdb for movie) when omitted. [one of: tvmaze, tmdb, imdb]

**Returns:** crew[]{person, department, job/type}

**Example request body:**
```json
{
  "id": 169
}
```

### POST /movies-tv/v1/akas — 1 credit
alternative titles (tv→TVmaze, movie→TMDB)

**Parameters:**
- `id` (string, required) — Title id. By default a TVmaze id (TV) or TMDB id (movie); an imdb id (tt0903747) is auto-detected. Set id_type to be explicit.
- `type` (enum, optional) — Whether the id/query is a movie or a TV show. Defaults to TV unless the id is a tmdb id or looks like a movie. [one of: movie, tv]
- `id_type` (enum, optional) — How to interpret `id`. Auto-detected (imdb if it starts with 'tt', else tvmaze for TV / tmdb for movie) when omitted. [one of: tvmaze, tmdb, imdb]

**Returns:** akas[]{name, country/language}

**Example request body:**
```json
{
  "id": 169,
  "type": "tv"
}
```

### POST /movies-tv/v1/schedule — 1 credit
TV broadcast (kind=tv) or streaming-premiere (kind=web) calendar

**Parameters:**
- `country` (string, optional, default "US") — JustWatch market — ISO-3166-1 alpha-2 (~140 supported). Controls streaming offers / services / new-titles region.
- `date` (string, optional) — Date as YYYY-MM-DD.
- `kind` (enum, optional, default "tv") — Which calendar. Any non-web value is treated as the TV broadcast schedule. [one of: tv, web, streaming]

**Returns:** kind, date, airings[]{show.title, airdate/time, network}

**Example request body:**
```json
{
  "country": "US",
  "date": "2024-01-01"
}
```

### POST /movies-tv/v1/streaming — 1 credit
where-to-watch offers via JustWatch (query/node_id/imdb/tmdb)

**Parameters:**
- `query` (string, optional) — Free-text title/person search keywords.
- `id` (string, optional) — Title id. By default a TVmaze id (TV) or TMDB id (movie); an imdb id (tt0903747) is auto-detected. Set id_type to be explicit.
- `id_type` (enum, optional) — How to interpret `id`. Auto-detected (imdb if it starts with 'tt', else tvmaze for TV / tmdb for movie) when omitted. [one of: tvmaze, tmdb, imdb]
- `node_id` (string, optional) — JustWatch node id (tm…/ts…) — fetches offers directly without a search.
- `country` (string, optional, default "US") — JustWatch market — ISO-3166-1 alpha-2 (~140 supported). Controls streaming offers / services / new-titles region.
- `object_types` (array, optional) — Restrict JustWatch results to these node types (MOVIE / SHOW). [one of: MOVIE, SHOW]
- `title` (string, optional) — Exact title to match when resolving by imdb/tmdb id.
- `year` (integer, optional) — Release-year filter (movie search / streaming match).

**Returns:** results[] (query path) OR one title with offers[]{provider, type, quality, price, url} (node/id path)

**Example request body:**
```json
{
  "query": "inception",
  "country": "US"
}
```

### POST /movies-tv/v1/people — 1 credit
person search or detail (tv→TVmaze, movie→TMDB)

**Parameters:**
- `query` (string, optional) — Free-text title/person search keywords.
- `id` (string, optional) — Title id. By default a TVmaze id (TV) or TMDB id (movie); an imdb id (tt0903747) is auto-detected. Set id_type to be explicit.
- `type` (enum, optional) — Whether the id/query is a movie or a TV show. Defaults to TV unless the id is a tmdb id or looks like a movie. [one of: movie, tv]

**Returns:** people[] (search; needs query) OR one person record (needs id)

### POST /movies-tv/v1/lookup — 1 credit
cross-resolve imdb↔tmdb↔tvmaze ids

**Parameters:**
- `imdb_id` (string, optional) — IMDb id to resolve (tt…). Provide any ONE id.
- `tmdb_id` (integer, optional) — TMDB id to resolve.
- `tvmaze_id` (integer, optional) — TVmaze id to resolve.
- `id` (string, optional) — Title id. By default a TVmaze id (TV) or TMDB id (movie); an imdb id (tt0903747) is auto-detected. Set id_type to be explicit.
- `id_type` (enum, optional) — How to interpret `id`. Auto-detected (imdb if it starts with 'tt', else tvmaze for TV / tmdb for movie) when omitted. [one of: tvmaze, tmdb, imdb]
- `type` (enum, optional) — Whether the id/query is a movie or a TV show. Defaults to TV unless the id is a tmdb id or looks like a movie. [one of: movie, tv]

**Returns:** ids{imdb, tmdb, tvmaze} (whichever resolve), title, type

**Example request body:**
```json
{
  "imdb_id": "tt0903747"
}
```

### POST /movies-tv/v1/genres — 0 credits
TMDB genre reference (movie|tv)

**Parameters:**
- `type` (enum, optional) — Whether the id/query is a movie or a TV show. Defaults to TV unless the id is a tmdb id or looks like a movie. [one of: movie, tv]

**Returns:** media, genres[]{id, name}

### POST /movies-tv/v1/countries — 0 credits
streaming services available in a country (JustWatch)

**Parameters:**
- `country` (string, optional, default "US") — JustWatch market — ISO-3166-1 alpha-2 (~140 supported). Controls streaming offers / services / new-titles region.

**Returns:** country, services[]{provider, ...}

**Example request body:**
```json
{
  "country": "US"
}
```

### POST /movies-tv/v1/new_titles — 1 credit
recently added/changed on streaming (≈ catalog changes)

**Parameters:**
- `date` (string, required) — Date as YYYY-MM-DD (required — the catalog-change day to report).
- `country` (string, optional, default "US") — JustWatch market — ISO-3166-1 alpha-2 (~140 supported). Controls streaming offers / services / new-titles region.
- `limit` (integer, optional, default 20) — Max results to return.
- `object_types` (array, optional) — Restrict JustWatch results to these node types (MOVIE / SHOW). [one of: MOVIE, SHOW]
- `packages` (array, optional) — Restrict to these JustWatch provider technical names (e.g. nfx=Netflix).

**Returns:** titles[]{title, ids{imdb,...}, new_offer}, total

**Example request body:**
```json
{
  "country": "US",
  "date": "2026-06-01"
}
```

### POST /movies-tv/v1/charts — 1 credit
Ranked title charts: most-popular / top-rated / upcoming / now-playing / on-the-air / trending — for movies, TV or both. A `language` filter turns top-rated/popular into the per-language charts (e.g. top-rated Tamil/Telugu/Hindi); `region` localises upcoming/now-playing.

**Parameters:**
- `chart` (enum, optional) — Which chart to return. [one of: popular_movies, popular_tv, top_rated_movies, top_rated_tv, upcoming_movies, now_playing_movies, on_the_air_tv, trending_movies, trending_tv, trending_all]
- `language` (string, optional) — ISO 639-1 original-language filter (e.g. ta=Tamil, te=Telugu, hi=Hindi, en=English). Turns popular/top-rated into per-language charts.
- `region` (string, optional) — ISO 3166-1 region to localise upcoming/now-playing.
- `page` (integer, optional, default 1) — TMDB result page (movie/multi search only).
- `limit` (integer, optional, default 20) — Max results to return.

**Returns:** chart, language, region, page, total_pages, total_results, results[]{ids{tmdb,imdb}, type, title, year, genres, rating, ...}

**Example request body:**
```json
{
  "chart": "top_rated_movies"
}
```

### POST /movies-tv/v1/similar — 1 credit
Titles similar to / recommended for a given movie or TV show (TMDB recommendations, falling back to similar). Accepts a TMDB id or an IMDb tt… id.

**Parameters:**
- `id` (string, required) — Title id. By default a TVmaze id (TV) or TMDB id (movie); an imdb id (tt0903747) is auto-detected. Set id_type to be explicit.
- `type` (enum, optional) — Whether the id/query is a movie or a TV show. Defaults to TV unless the id is a tmdb id or looks like a movie. [one of: movie, tv]
- `limit` (integer, optional, default 20) — Max results to return.

**Returns:** id, tmdb_id, type, results[]{ids, title, year, genres, rating, ...}

**Example request body:**
```json
{
  "id": 27205,
  "type": "movie"
}
```

### POST /movies-tv/v1/credits — 1 credit
A person's full filmography (combined movie + TV credits) by TMDB person id or by name — every title they were cast or crew on, newest first, with their character/job.

**Parameters:**
- `person_id` (integer, optional) — TMDB person id (omit if passing `name`).
- `name` (string, optional) — Person name to search (used when `person_id` is omitted).
- `limit` (integer, optional, default 40) — Max results to return.

**Returns:** person_id, name, cast[]{title, year, character, ...}, crew[]{title, year, job, ...}

### POST /movies-tv/v1/discover — 1 credit
Browse the catalog with filters — find movies or TV by genre, year range, minimum rating, runtime, original language, cast/crew, keyword and where-to-stream provider, sorted however you like. The 'explore like a real user' surface.

**Parameters:**
- `type` (enum, optional, default "movie") — Whether to browse/return movies or TV shows. [one of: movie, tv]
- `genres` (string, optional) — Genre filter — names ('Action','Comedy') or TMDB ids (28,878), comma-separated. See the `genres` action for the full list.
- `year` (integer, optional) — Exact release/first-air year.
- `year_gte` (integer, optional) — Earliest year (inclusive).
- `year_lte` (integer, optional) — Latest year (inclusive).
- `rating_gte` (number, optional) — Minimum TMDB rating 0-10 (auto-applies a 50-vote floor to drop 1-vote outliers).
- `runtime_gte` (integer, optional) — Minimum runtime in minutes.
- `runtime_lte` (integer, optional) — Maximum runtime in minutes.
- `language` (string, optional) — Original-language filter, ISO 639-1 (e.g. ko=Korean, ja=Japanese, hi=Hindi, en=English).
- `region` (string, optional) — ISO 3166-1 region for release-window localisation.
- `with_cast` (string, optional) — TMDB person id(s) who must appear in the cast (comma-separated).
- `sort_by` (enum, optional, default "popularity.desc") — Result ordering. [one of: popularity.desc, popularity.asc, vote_average.desc, vote_average.asc, primary_release_date.desc, primary_release_date.asc, revenue.desc]
- `page` (integer, optional, default 1) — TMDB result page (movie/multi search only).
- `locale` (string, optional) — Display language for titles/overviews (e.g. de-DE, ja-JP).

**Returns:** media, page, total_pages, total_results, results[]{ids, title, year, genres, rating}

**Example request body:**
```json
{
  "type": "movie",
  "genres": "Science Fiction",
  "year_gte": 2010,
  "rating_gte": 7.5,
  "sort_by": "vote_average.desc"
}
```

### POST /movies-tv/v1/reviews — 1 credit
User reviews for a movie or TV show (author, star rating, full text), paginated.

**Parameters:**
- `id` (string, required) — TMDB id (e.g. 27205) OR an IMDb id (tt1375666) — auto-resolved.
- `type` (enum, optional, default "movie") — Whether to browse/return movies or TV shows. [one of: movie, tv]
- `page` (integer, optional, default 1) — TMDB result page (movie/multi search only).

**Returns:** tmdb_id, type, page, total_pages, total_results, reviews[]{author, rating, content, created_at, url}

**Example request body:**
```json
{
  "id": 27205,
  "type": "movie"
}
```

### POST /movies-tv/v1/images — 1 credit
All artwork for a title — posters, backdrops and (TV) episode stills with resolutions and language tags.

**Parameters:**
- `id` (string, required) — TMDB id (e.g. 27205) OR an IMDb id (tt1375666) — auto-resolved.
- `type` (enum, optional, default "movie") — Whether to browse/return movies or TV shows. [one of: movie, tv]
- `limit` (integer, optional, default 20) — Max results to return.

**Returns:** tmdb_id, type, results[] (flat), posters[], backdrops[], logos[], stills[] {url, width, height, language}

**Example request body:**
```json
{
  "id": 27205,
  "type": "movie"
}
```

### POST /movies-tv/v1/videos — 1 credit
Trailers, teasers and clips for a movie or TV show (YouTube keys + ready-to-play URLs).

**Parameters:**
- `id` (string, required) — TMDB id (e.g. 27205) OR an IMDb id (tt1375666) — auto-resolved.
- `type` (enum, optional, default "movie") — Whether to browse/return movies or TV shows. [one of: movie, tv]

**Returns:** tmdb_id, type, results[]{name, type, site, key, url, official, published_at}

**Example request body:**
```json
{
  "id": 27205,
  "type": "movie"
}
```

### POST /movies-tv/v1/watch_providers — 1 credit
Where to stream/rent/buy a title (TMDB/JustWatch data) — pass a country for that region's offers, or omit it to get every region.

**Parameters:**
- `id` (string, required) — TMDB id (e.g. 27205) OR an IMDb id (tt1375666) — auto-resolved.
- `type` (enum, optional, default "movie") — Whether to browse/return movies or TV shows. [one of: movie, tv]
- `country` (string, optional, default "US") — JustWatch market — ISO-3166-1 alpha-2 (~140 supported). Controls streaming offers / services / new-titles region.

**Returns:** tmdb_id, type, region, offers[]{provider, type, provider_id} (one region) OR by_region{cc:{offers}} (all regions)

**Example request body:**
```json
{
  "id": 27205,
  "type": "movie",
  "country": "US"
}
```

### POST /movies-tv/v1/season — 1 credit
Full episode list for one season of a TV show — episode titles, overviews, air dates, ratings and stills (TMDB).

**Parameters:**
- `id` (string, required) — TMDB id (e.g. 27205) OR an IMDb id (tt1375666) — auto-resolved.
- `season` (integer, required) — Season number.
- `type` (enum, optional, default "tv") — Always tv. [one of: tv]

**Returns:** tmdb_id, season_number, name, episode_count, episodes[]{episode, name, overview, air_date, runtime, rating, still}

**Example request body:**
```json
{
  "id": 1396,
  "season": 1
}
```

### POST /movies-tv/v1/episode — 1 credit
One TV episode in depth — overview, air date, rating, guest stars and crew (TMDB).

**Parameters:**
- `id` (string, required) — TMDB id (e.g. 27205) OR an IMDb id (tt1375666) — auto-resolved.
- `season` (integer, required) — Season number.
- `episode` (integer, required) — Episode number within the season.

**Returns:** tmdb_id, season, episode, name, overview, air_date, rating, guest_stars[]{person, character}, crew[]{person, job}

**Example request body:**
```json
{
  "id": 1396,
  "season": 1,
  "episode": 1
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=movies-tv
- Human docs page: https://reefapi.com/docs/movies-tv
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt