# Streaming Availability API (JustWatch where-to-watch) — find which platform a movie or TV show is on by country: stream/rent/buy offers with price & quality, multi-country availability, trending, what's new and leaving, and provider catalogs

> search movies/shows with current offers
> ReefAPI engine `streaming` · 12 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/streaming/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 /streaming/v1/search — 1 credit
search movies/shows with current offers

**Parameters:**
- `query` (string, required) — Title to search for.
- `country` (string, optional, default "US") — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.
- `language` (string, optional, default "en") — ISO-639-1 language for titles/genre names (lower-cased).
- `page_size` (integer, optional, default 20) — Results per page (1-40). Larger values are clamped.
- `cursor` (string, optional) — Next-page token from the previous response's meta.next_cursor (for episodes it is a numeric offset).

**Returns:** results[]{id, title, year, offers[]{provider, type, quality, price, url}, external_ids, scoring, cursor}; meta has total/has_more/next_cursor

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

### POST /streaming/v1/browse — 1 credit
browse a provider/country catalog by genre/type/year, ranked (sort_by), with pagination

**Parameters:**
- `country` (string, optional, default "US") — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.
- `language` (string, optional, default "en") — ISO-639-1 language for titles/genre names (lower-cased).
- `object_types` (array, optional) — Restrict to these title types (movie / show; 'tv' is accepted). Comma-list or array. [one of: movie, show, tv]
- `packages` (array, optional) — Restrict to these providers by JustWatch technical name (e.g. nfx=Netflix, amp=Prime Video) — see the providers action.
- `genres` (array, optional) — Restrict to these genre short-names (e.g. act, drm) — see the genres action. Comma-list or array.
- `sort_by` (enum, optional, default "popular") — Ranking for the result list. Case-insensitive; common values shown. [one of: popular, trending, imdb_score, tmdb_popularity, alphabetical, random]
- `release_year` (object, optional) — Advanced: release-year range as {min, max} (overrides year_min/year_max).
- `year_min` (integer, optional) — Earliest release year (inclusive).
- `year_max` (integer, optional) — Latest release year (inclusive).
- `page_size` (integer, optional, default 20) — Results per page (1-40). Larger values are clamped.
- `cursor` (string, optional) — Next-page token from the previous response's meta.next_cursor (for episodes it is a numeric offset).

**Returns:** results[] (same title shape as search), meta total/has_more/next_cursor

### POST /streaming/v1/trending — 1 credit
trending titles right now (with where-to-watch offers), filterable by provider/type/genre

**Parameters:**
- `country` (string, optional, default "US") — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.
- `language` (string, optional, default "en") — ISO-639-1 language for titles/genre names (lower-cased).
- `sort_by` (enum, optional, default "trending") — Ranking for the result list. Case-insensitive; common values shown. [one of: popular, trending, imdb_score, tmdb_popularity, alphabetical, random]
- `object_types` (array, optional) — Restrict to these title types (movie / show; 'tv' is accepted). Comma-list or array. [one of: movie, show, tv]
- `packages` (array, optional) — Restrict to these providers by JustWatch technical name (e.g. nfx=Netflix, amp=Prime Video) — see the providers action.
- `genres` (array, optional) — Restrict to these genre short-names (e.g. act, drm) — see the genres action. Comma-list or array.
- `page_size` (integer, optional, default 20) — Results per page (1-40). Larger values are clamped.
- `cursor` (string, optional) — Next-page token from the previous response's meta.next_cursor (for episodes it is a numeric offset).

**Returns:** results[]{id, title, year, offers[]{provider, type, quality, price, url}, scoring, cursor}; meta total/has_more/next_cursor

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

### POST /streaming/v1/title — 1 credit
title metadata and offers by JustWatch node id

**Parameters:**
- `id` (string, optional) — JustWatch node id (movie tm…, show ts…, season tse…). Get it from a search/browse result's `id`.
- `query` (string, optional) — Resolve the title by name when you have no node id (first match is used).
- `url` (string, optional) — Resolve from a JustWatch URL when you have no id/query.
- `country` (string, optional, default "US") — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.
- `language` (string, optional, default "en") — ISO-639-1 language for titles/genre names (lower-cased).

**Returns:** one title record{id, title, year, runtime, genres, external_ids, scoring, offers[]{provider, type, quality, price, url}}

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

### POST /streaming/v1/availability — 2 credits
where-to-watch offers for one title across multiple countries (the core comparison call)

**Parameters:**
- `id` (string, optional) — JustWatch node id (movie tm…, show ts…, season tse…). Get it from a search/browse result's `id`.
- `query` (string, optional) — Resolve the title by name when you have no node id (first match is used).
- `url` (string, optional) — Resolve from a JustWatch URL when you have no id.
- `countries` (array, optional) — Markets to check (comma-list or array of ISO-2 codes). Defaults to the single `country`.
- `country` (string, optional, default "US") — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.
- `language` (string, optional, default "en") — ISO-639-1 language for titles/genre names (lower-cased).
- `monetization_types` (array, optional) — Filter offers by how you pay. Common values shown; case-insensitive. [one of: flatrate, rent, buy, ads, free, cinema]
- `presentation_types` (array, optional) — Filter offers by video quality. Common values shown; case-insensitive. [one of: sd, hd, 4k]

**Returns:** id, countries{<CC>: offers[]{provider, type, quality, price, url}}

### POST /streaming/v1/new — 1 credit
what's new / coming soon / leaving soon on a provider — by country/provider/type

**Parameters:**
- `country` (string, optional, default "US") — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.
- `language` (string, optional, default "en") — ISO-639-1 language for titles/genre names (lower-cased).
- `packages` (array, optional) — Restrict to these providers by JustWatch technical name (e.g. nfx=Netflix, amp=Prime Video) — see the providers action.
- `object_types` (array, optional) — Restrict to these title types (movie / show; 'tv' is accepted). Comma-list or array. [one of: movie, show, tv]
- `date` (string, optional) — The change day as YYYY-MM-DD (defaults to today).
- `price_drops` (boolean, optional, default false) — Return price-drop changes instead of newly-added titles.
- `page_type` (enum, optional, default "new") — Which change feed. Case-insensitive; 'leaving' returns titles about to expire (with availableTo dates). [one of: new, upcoming, leaving]
- `monetization_types` (array, optional) — Filter offers by how you pay. Common values shown; case-insensitive. [one of: flatrate, rent, buy, ads, free, cinema]
- `presentation_types` (array, optional) — Filter offers by video quality. Common values shown; case-insensitive. [one of: sd, hd, 4k]
- `page_size` (integer, optional, default 20) — Results per page (1-40). Larger values are clamped.
- `cursor` (string, optional) — Next-page token from the previous response's meta.next_cursor (for episodes it is a numeric offset).

**Returns:** results[]{title, ids, new_offer{provider, date_created, available_to}, show, cursor}, meta total/has_more/next_cursor

**Example request body:**
```json
{
  "country": "US",
  "packages": [
    "nfx"
  ],
  "page_type": "leaving",
  "page_size": 3
}
```

### POST /streaming/v1/countries — 0 credits
supported country codes

**Parameters:** none

**Returns:** countries[]{code} (static ISO-2 JustWatch market list), source

### POST /streaming/v1/genres — 0 credits
JustWatch genre reference for a country/language

**Parameters:**
- `country` (string, optional, default "US") — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.
- `language` (string, optional, default "en") — ISO-639-1 language for titles/genre names (lower-cased).

**Returns:** genres[]{short_name, translation}

### POST /streaming/v1/providers — 0 credits
streaming providers available in a country

**Parameters:**
- `country` (string, optional, default "US") — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.

**Returns:** providers[]{provider, provider_id, technical_name, monetization_types, icon}

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

### POST /streaming/v1/country — 0 credits
one country plus live supported provider/service details

**Parameters:**
- `country` (string, required) — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.

**Returns:** country{code, providers[]{provider, technical_name, monetization_types}}

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

### POST /streaming/v1/seasons — 1 credit
show seasons with offers

**Parameters:**
- `id` (string, required) — JustWatch node id (movie tm…, show ts…, season tse…). Get it from a search/browse result's `id`.
- `country` (string, optional, default "US") — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.
- `language` (string, optional, default "en") — ISO-639-1 language for titles/genre names (lower-cased).

**Returns:** seasons[]{id, season_number, title, offers[], total_episode_count}

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

### POST /streaming/v1/episodes — 1 credit
season episodes with offers; show id + season_number resolves first

**Parameters:**
- `id` (string, optional) — JustWatch node id (movie tm…, show ts…, season tse…). Get it from a search/browse result's `id`.
- `season_id` (string, optional) — Season node id (tse…) — fetches that season's episodes directly.
- `season_number` (integer, optional) — With a show `id`, resolves this season number to its episodes.
- `country` (string, optional, default "US") — Market — ISO-3166-1 alpha-2 (upper-cased; ~135 supported, see the countries action). Controls which offers/providers are returned.
- `language` (string, optional, default "en") — ISO-639-1 language for titles/genre names (lower-cased).
- `page_size` (integer, optional, default 20) — Results per page (1-40). Larger values are clamped.
- `cursor` (string, optional) — Next-page token from the previous response's meta.next_cursor (for episodes it is a numeric offset).

**Returns:** episodes[]{id, season_number, episode_number, title, offers[]}, meta total/has_more/next_cursor

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