Movies & TV API
The Movies & TV API returns film and television metadata as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary search endpoint returns title rows with cross-IDs (IMDb, TMDb, TVmaze), year and overview, and you can pull a detail, episodes, cast, crew, alternate titles and a schedule. It is built for entertainment apps, recommendation engines and media research that need unified movie and TV data without a scraper. One ReefAPI key, one shared credit pool, the standard { ok, data, meta, error } envelope.
Which id namespace each action reads
This engine merges three catalogs, and each action reads ids from a different one. A bare number is ambiguous: it is a TVmaze id in the TV actions and a TMDB id in the movie actions, so the same digits return two different titles. Every row below came out of a live call. When in doubt pass an IMDb tt id, which is auto-detected everywhere.
| Action | Id it reads | Measured result |
|---|---|---|
| detail, cast, crew, akas (TV path) | TVmaze id, or tt... auto-detected | id 169 with type tv returned Breaking Bad with ids {tvmaze 169, imdb tt0903747, thetvdb 81189, tvrage 18164, justwatch ts4} |
| detail (movie path) | TMDB id, or tt... auto-detected | id 27205 with type movie returned Inception with ids {tmdb 27205, imdb tt1375666, justwatch tm92641} |
| detail with no type at all | defaults to TV, so a TVmaze id | id 27205 alone returned the TVmaze show Boiling Points, not the movie Inception |
| episodes | TVmaze id | id 169 season 1 returned 7 rows keyed season, number, airdate and airstamp with TVmaze ratings |
| season · episode · reviews · images · videos | TMDB id or tt... only | id tt0903747 season 1 resolved to tmdb_id 1396 and returned 7 rows keyed episode and air_date with TMDB ratings |
| lookup | any one of imdb_id, tmdb_id, tvmaze_id | imdb_id tt0903747 returned {imdb tt0903747, tmdb 1396, tvmaze 169} plus title and type |
| charts, discover, similar, credits | TMDB only | chart rows carry ids.tmdb and nothing else, so no IMDb id is attached to a chart entry |
| genres | TMDB genre ids | type movie returned 28 Action, 12 Adventure, 16 Animation, 35 Comedy, 80 Crime and 14 more |
| country (streaming, watch_providers, schedule) | ISO 3166-1 alpha-2, default US | controls which JustWatch offers are merged into detail as streaming_offers |
type and id_type both have on_invalid set to ignore, so a typo in either one does not raise: the request silently falls back to the TV default and you get a real record for the wrong title. Send type explicitly on every movie call, or pass the tt id.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/movies-tv/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "breaking bad",
"type": "tv"
}
}{
"ok": true,
"meta": {
"api": "movies-tv",
"endpoint": "search",
"mode": "live",
"latency_ms": 218.4,
"record_count": 8,
"bytes": 12220,
"cache_hit": false,
"completeness_pct": 100,
"requests": 1,
"license": "CC-BY-SA 4.0 (TVmaze)",
"attribution": "TV data by TVmaze.com (CC BY-SA); This product uses the TMDB API but is not endorsed or certified by TMDB.; streaming via JustWatch"
},
"data": {
"query": "breaking bad",
"type": "tv",
"results": [
{
"ids": {
"tvmaze": 169,
"imdb": "tt0903747",
"thetvdb": 81189,
"tvrage": 18164
},
"type": "tv",
"title": "Breaking Bad",
"year": 2008,
"premiered": "[redacted-phone]",
"ended": "[redacted-phone]",
"genres": [
"Drama",
"Crime",
"Thriller"
],
"runtime": 60,
"status": "Ended",
"language": "English",
"show_type": "Scripted",
"overview": "Breaking Bad follows protagonist Walter White, a chemistry teacher who lives in New Mexico with his wife and teenage son who has cerebral palsy. White is diagnosed with Stage III cancer and given a prognosis of two years left to live. With a new sense of fearlessness based on his medical prognosis, and a desire to secure his family's financial security, White chooses to enter a dangerous world of drugs and crime and ascends to power in this world. The series explores how a fatal diagnosis such as White's releases a typical man from the daily concerns and constraints of normal society and follo",
"rating": {
"tvmaze": 9.2
},
"network": "AMC",
"country": "United States",
"schedule": {
"time": "22:00",
"days": [
"[trimmed-depth]"
]
},
"poster": "https://static.tvmaze.com/uploads/images/original_untouched/501/1253519.jpg",
"official_site": "http://www.amc.com/shows/breaking-bad",
"url": "https://www.tvmaze.com/shows/169/breaking-bad",
"source": "tvmaze",
"license": "CC-BY-SA 4.0 (TVmaze)"
},
{
"ids": {
"tvmaze": 27845,
"imdb": "tt2387761",
"thetvdb": 356427
},
"type": "tv",
"title": "Breaking Bad: Original Minisodes",
"year": 2009,
"premiered": "[redacted-phone]",
"ended": "[redacted-phone]",
"genres": [
"Comedy",
"Crime"
],
"runtime": 5,
"status": "Ended",
"language": "English",
"show_type": "Scripted",
"overview": "Watch Hank and Marie as they celebrate Valentine's Day in the bedroom in \"Good Cop, Bad Cop\". View a flashback to Hank and Marie's wedding as the groom discusses with Walt his last wild night as a bachelor in \"Wedding Day\". Go inside Jesse's band TwaughtHammer as he and Badger make a behind-the-music documentary, and sing along to the full music video for their song \"Fallacies\". Finally, watch Marie discuss politics and patriotism in her personal video diary, \"Marie's Confession\".",
"rating": {
"tvmaze": 7
},
"network": "AMC",
"country": "United States",
"schedule": {
"time": ""
},
"poster": "https://static.tvmaze.com/uploads/images/original_untouched/216/540867.jpg",
"official_site": "https://www.amc.com/shows/breaking-bad/talk/2009/02/original-minisodes#:~:text=Now%20you%20can%20watch%20five,and%20Matt%20Jones%20(Badger).",
"url": "https://www.tvmaze.com/shows/27845/breaking-bad-original-minisodes",
"source": "tvmaze",
"license": "CC-BY-SA 4.0 (TVmaze)"
},
{
"ids": {
"tvmaze": 1003,
"imdb": "tt3115468",
"thetvdb": 272219,
"tvrage": 36082
},
"type": "tv",
"title": "Talking Bad",
"year": 2013,
"premiered": "[redacted-phone]",
"ended": "[redacted-phone]",
"runtime": 30,
"status": "Ended",
"language": "English",
"show_type": "Talk Show",
"overview": "Talking Bad features Hardwick spending time with fans, actors, producers and tv enthusiasts, recapping the most recent Breaking Bad episode, and taking questions and comments from viewers. Fans may continue to engage with the after-show following the on-air conclusion, online, at amc.com for more videos, weekly polls and photo galleries of the guests featured on the series.",
"network": "AMC",
"country": "United States",
"schedule": {
"time": "23:05",
"days": [
"[trimmed-depth]"
]
},
"poster": "https://static.tvmaze.com/uploads/images/original_untouched/6/16586.jpg",
"url": "https://www.tvmaze.com/shows/1003/talking-bad",
"source": "tvmaze",
"license": "CC-BY-SA 4.0 (TVmaze)"
}
]
}
}What the Movies & TV API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | search titles (type=multi|movie|tv|streaming) | Content platforms call search to search titles (type=multi|movie|tv|streaming). | query, type, limit, year, country, ... |
| detail | unified title detail (tv→TVmaze, movie→TMDB depth + JustWatch offers) | Research tools call detail to get unified title detail (tv→TVmaze, movie→TMDB depth + JustWatch offers). | id, type, id_type, country, include_streaming, ... |
| episodes | TV episodes (optionally one season) | Community analysts call episodes to get tV episodes (optionally one season). | id, id_type, season, specials |
| cast | cast (tv→TVmaze, movie→TMDB) | Media monitors call cast to get cast (tv→TVmaze, movie→TMDB). | id, type, id_type |
| crew | crew (tv→TVmaze, movie→TMDB) | Content platforms call crew to get crew (tv→TVmaze, movie→TMDB). | id, type, id_type |
| akas | alternative titles (tv→TVmaze, movie→TMDB) | Research tools call akas to get alternative titles (tv→TVmaze, movie→TMDB). | id, type, id_type |
| schedule | TV broadcast (kind=tv) or streaming-premiere (kind=web) calendar | Community analysts call schedule to get tV broadcast (kind=tv) or streaming-premiere (kind=web) calendar. | country, date, kind |
| streaming | where-to-watch offers via JustWatch (query/node_id/imdb/tmdb) | Media monitors call streaming to get where-to-watch offers via JustWatch (query/node_id/imdb/tmdb). | query, id, id_type, node_id, country, ... |
| people | person search or detail (tv→TVmaze, movie→TMDB) | Content platforms call people to get person search or detail (tv→TVmaze, movie→TMDB). | query, id, type |
| lookup | cross-resolve imdb↔tmdb↔tvmaze ids | Research tools call lookup to get cross-resolve imdb↔tmdb↔tvmaze ids. | imdb_id, tmdb_id, tvmaze_id, id, id_type, ... |
| genres | TMDB genre reference (movie|tv) | Community analysts call genres to get tMDB genre reference (movie|tv). | type |
| countries | streaming services available in a country (JustWatch) | Media monitors call countries to get streaming services available in a country (JustWatch). | country |
| new_titles | recently added/changed on streaming (≈ catalog changes) | Content platforms call new_titles to get recently added/changed on streaming (≈ catalog changes). | date, country, limit, object_types, packages |
| charts | 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. | Research tools call charts to get ranked title charts. | chart, language, region, page, limit |
| similar | 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. | Community analysts call similar to get titles similar to / recommended for a given movie or TV show (TMDB recommendations, falling b…. | id, type, limit |
| credits | 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. | Media monitors call credits to get a person's full filmography (combined movie + TV credits) by TMDB person id or by name. | person_id, name, limit |
| discover | 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. | Content platforms call discover to get browse the catalog with filters. | type, genres, year, year_gte, year_lte, ... |
| reviews | User reviews for a movie or TV show (author, star rating, full text), paginated. | Research tools call reviews to get user reviews for a movie or TV show (author, star rating, full text), paginated.. | id, type, page |
| images | All artwork for a title — posters, backdrops and (TV) episode stills with resolutions and language tags. | Community analysts call images to get all artwork for a title. | id, type, limit |
| videos | Trailers, teasers and clips for a movie or TV show (YouTube keys + ready-to-play URLs). | Media monitors call videos to get trailers, teasers and clips for a movie or TV show (YouTube keys + ready-to-play URLs).. | id, type |
| watch_providers | 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. | Content platforms call watch_providers to get where to stream/rent/buy a title (TMDB/JustWatch data). | id, type, country |
| season | Full episode list for one season of a TV show — episode titles, overviews, air dates, ratings and stills (TMDB). | Research tools call season to get full episode list for one season of a TV show. | id, season, type |
| episode | One TV episode in depth — overview, air date, rating, guest stars and crew (TMDB). | Community analysts call episode to get one TV episode in depth. | id, season, episode |
Call search from your stack
curl -X POST https://api.reefapi.com/movies-tv/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"breaking bad","type":"tv"}'import requests
r = requests.post(
"https://api.reefapi.com/movies-tv/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "breaking bad",
"type": "tv"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/movies-tv/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "breaking bad",
"type": "tv"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.movies-tv.search with {"query":"breaking bad","type":"tv"}.Who uses this API and why
- Recommendation engines call search and detail to build catalogs cross-linked to IMDb and TMDb.
- TV apps use episodes and schedule to track seasons and airings.
- Media research uses cast and crew to assemble filmographies.
Questions developers ask before integrating
Why did id 27205 return a show I have never heard of?
Because a bare number has no namespace here. With type omitted, detail treats the id as TVmaze, and TVmaze 27205 is a show called Boiling Points. TMDB 27205 is Inception. Both calls return ok true with a complete record, so nothing tells you the lookup went to the wrong catalog. Either send type movie, or set id_type tmdb, or pass tt1375666 and let the tt prefix decide.
Why do episodes and season disagree about the same episode?
They read different catalogs. For Breaking Bad season 1 episode 1, episodes (TVmaze) reported runtime 60 and rating 8.2 under the keys number, airdate and airstamp. season (TMDB) reported runtime 59 and rating 8.477 for the same episode under the keys episode and air_date. TVmaze runtime is the broadcast slot, TMDB runtime is the cut. Pick one source per pipeline rather than mixing the two.
What does streaming_offers look like, and why is it sometimes null?
detail merges JustWatch offers when include_streaming is on, keyed provider, technical_name, provider_id, type, quality, currency and url. Breaking Bad in the US came back with 19 offers, the first two being Netflix subscription in SD and HD. On a 2026 title with no offers in the requested country the whole streaming_offers key came back null rather than an empty list, so check for null before iterating.
Why are budget and revenue zero rather than null on a new film?
TMDB stores unreported financials as 0, and the engine passes that through unchanged. A measured detail call on TMDB 1101412 returned budget 0 and revenue 0 alongside a full cast, crew and video list. Zero here means unreported, not free. Anything you compute from those fields needs an explicit guard, because a 0 revenue will quietly sink an average.
The chart and the detail call give different release dates for the same film. Which is right?
Both, for different questions. A charts call for upcoming_movies with region US returned release_date 2026-09-02 for TMDB 1101412, and detail on the same id returned 2026-08-07. The chart date is the release window for the region you asked about, while detail carries TMDB's primary release date, which is usually the earliest release anywhere. If you need a specific market, take the date from the region-scoped call.
Chart and discover rows have no IMDb id. How do I get one?
Feed the tmdb id to lookup. Those two actions are TMDB-only surfaces, so their rows carry ids.tmdb and stop there, while detail on the same title returns tmdb, imdb and justwatch together. lookup exists for exactly this: one call with tmdb_id, imdb_id or tvmaze_id returns whichever of the three resolve, plus the title and type so you can confirm you landed on the right record.
How is this different from the imdb engine?
The imdb engine reads IMDb itself, so it is the place for IMDb's own rating and vote count, awards, the parental guide, box-office weekends and full department credits, all keyed on tt and nm ids. This engine never touches IMDb. It merges TVmaze, TMDB and JustWatch, which is what gives it the things IMDb has no equivalent of: where-to-watch offers per country, a discover surface with genre, year, rating, runtime and cast filters, and lookup to translate an id between the three catalogs.
Which fields tell a TV show apart from a movie in a mixed result set?
Read type, which is tv or movie, then the keys only one side has. A TV record carries premiered, ended, network, schedule with time and days, show_type and seasons. A movie record carries release_date, runtime, budget, revenue, production_companies and tagline. The rating object also differs: rating.tvmaze on the TV path, rating.tmdb plus rating.tmdb_votes on the movie path.
What is the Movies & TV API?
Movies & TV API is a ReefAPI endpoint group for film and series details, cast and ratings. It returns live JSON through POST requests under /movies-tv/v1.
Is the Movies & TV API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Movies & TV calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Movies & TV login or account?
No login to Movies & TV is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Movies & TV data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Movies & TV API use?
Movies & TV actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Movies & TV from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call movies-tv actions with the same key, credit pool and JSON envelope used by normal REST requests.