openapi: 3.0.3
info:
    title: Watchmode API
    version: '1.1.8'
    description: |
        The Watchmode API provides comprehensive data about movies, TV shows, and streaming availability across 200+ streaming services worldwide.

        ## Official TypeScript SDK

        Install our official SDK for the best developer experience:

        ```bash
        npm install @watchmode/api-client
        ```

        **Quick Start:**
        ```typescript
        import { WatchmodeClient } from '@watchmode/api-client';

        const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

        // Search for titles
        const { data: results } = await client.search.byName('Breaking Bad');

        // Get title details
        const { data: title } = await client.title.getDetails('3173903');

        // Get streaming sources
        const { data: sources } = await client.title.getSources('3173903');
        ```

        📦 [View on npm](https://www.npmjs.com/package/@watchmode/api-client) | 📖 [SDK Examples](#operation/getSources)

        ---

        ## Features
        - **Streaming Availability**: Find where movies and TV shows are available to stream, rent, or buy
        - **Title Details**: Get comprehensive information about movies and TV series including cast, crew, ratings, and more
        - **Search**: Search for titles by name, IMDB ID, or TMDB ID
        - **Changes Tracking**: Monitor new titles, streaming source changes, and metadata updates
        - **Multi-Region Support**: Data available for 50+ countries

        ## API Key
        All API requests require an API key. We recommend sending it in a request header so the key is not exposed in URLs, browser history, analytics, referrer headers, or web server logs.

        Recommended:
        ```bash
        curl -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/status/'
        ```

        Also supported:
        ```bash
        curl -H 'Authorization: Bearer YOUR_API_KEY' 'https://api.watchmode.com/v1/status/'
        ```

        For backwards compatibility, the `apiKey` query parameter is still accepted, but new integrations should prefer headers:
        ```bash
        curl 'https://api.watchmode.com/v1/status/?apiKey=YOUR_API_KEY'
        ```

        Get your free API key at [https://api.watchmode.com/requestApiKey/](https://api.watchmode.com/requestApiKey/)

        ## Third-Party Image URLs
        Some image-related fields may contain URLs hosted by third parties or publicly accessible sources. These URLs are provided as references only. Watchmode does not grant any license to the underlying images and does not guarantee ownership, copyright status, availability, or permitted use. You are responsible for verifying rights and complying with applicable source terms, attribution obligations, and caching rules. See the Terms & Conditions at [https://api.watchmode.com/tc](https://api.watchmode.com/tc).

        ## Rate Limiting
        API requests are limited based on your plan. Check response headers for current limits:
        - `X-RateLimit-Limit`: Maximum requests per minute
        - `X-RateLimit-Remaining`: Remaining requests in current window
        - `X-Account-Quota`: Monthly quota limit
        - `X-Account-Quota-Used`: Quota used this month
        The following additional headers apply to the Live beta endpoints:
        - `X-Account-Quota-Remaining`: Remaining credits at settlement
        - `X-Watchmode-Request-Cost`: Credits charged for this response (0 for rejected requests)
        - `X-Watchmode-Request-Id`: Identifier for reconciling a Live request

        The older catalog endpoints, including `/sources` and `/networks`, keep their existing credit charges and
        do not return the Live request-cost or request-ID headers. Both families use the same monthly credit balance.
        If several apps share an account, its balance includes all of their requests. Track your own Live spending
        by summing request-cost headers, including retries. Do not treat another app's usage as your own.
        Default limits are 240 requests/minute for Live and 1,000 for catalog routes; account overrides may apply.
        Read the response headers for the limit in effect.

        Authenticated requests count toward the request limit even if validation fails or the response costs
        zero credits. Live responses commit their full cost atomically. For Live, monthly exhaustion
        returns `MONTHLY_QUOTA_EXCEEDED` without a one-minute Retry-After; zero-credit operations remain
        available. A plan or billing-period change during a request returns `ACCOUNT_PERIOD_CHANGED` so
        the request can be retried against the current account state.

        ## ID Mapping
        Watchmode IDs are universally unique across titles and people. Download ID mapping files:
        - [Title ID Map](https://api.watchmode.com/datasets/title_id_map.csv)
        - [Person ID Map](https://api.watchmode.com/datasets/person_id_map.csv)
    contact:
        name: Watchmode API Support
        url: https://api.watchmode.com
    license:
        name: Proprietary
        url: https://api.watchmode.com/tc

servers:
    - url: https://api.watchmode.com/v1
      description: Production server

security:
    - apiKey: []

tags:
    - name: Configuration
      description: Reference data for streaming sources, regions, networks, and genres
    - name: Search
      description: Search for titles and people
    - name: Title
      description: Get detailed information about movies and TV shows
    - name: Live TV, Sports & Events (Beta)
      description: |
          Build TV guides, discover sports and awards events, and show people where to watch.
          These endpoints are in beta. Contact us at https://api.watchmode.com/support to request access for your account.
          Your API key works once access is enabled. Your current plan determines which features and dates you can use.

          Free: a shared sample of up to 25 events, including their viewing options.
          Startup: events from the past 7 days through the next 7 days in all supported countries.
          Business and Enterprise: all available event dates, event downloads, and the US TV guide.
          Check `/live-coverage` to see what your account can access. It costs no credits.
          Beta access continues when you change plans. Shared RapidAPI accounts are not supported.

          A channel is a specific station or channel version, such as an East Coast channel or a local ABC station.
          A network is the brand that may have multiple channels. An airing is one scheduled showing of a program.
          A source is a where-to-watch option, such as a streaming service, TV channel app, or event page.
          A package is a service's subscription bundle or add-on.
          Live `network_id` values belong to the Live dataset; do not join them to the catalog `/networks` directory.
          Use the included network name, and use `channel_id` to join a broadcast to a guide channel when available.
          Some event-only channels have no guide listings and therefore do not appear in `/live-channels`.

          Live errors include `success: false`, `statusCode`, a machine-readable `code`, and a readable `statusMessage`.
          Common codes include `LIVE_QUERY_INVALID`, `LIVE_REGION_UNSUPPORTED`, `LIVE_UNAUTHORIZED`,
          `LIVE_NOT_FOUND`, and `LIVE_PLAN_REQUIRED`. Errors may also include more specific access or quota codes.
          Handle the HTTP status and code; do not parse the wording of the message. Older catalog errors keep their existing format.

          September 9, 2026 (UTC) beta update (spec 1.1.8): event search now includes league and team names; league totals,
          clearer validation errors, and corrected viewing-option labels are available. The earlier prelaunch change
          renamed channel/streaming fields to the names in this reference. Build against this published contract.
          More fields and data may be added during beta; tolerate unknown response fields.

          Listings and viewing options may be incomplete or outdated. An empty result does not prove that nothing
          is airing or that an event cannot be watched. Viewing links may open a service homepage rather than a
          player. Check the link type; location and subscription restrictions may apply.
    - name: Person
      description: Get information about actors, directors, and other people
    - name: Releases
      description: Track new and upcoming streaming releases
    - name: Changes
      description: Monitor changes to titles, sources, and metadata
    - name: Account
      description: Account and quota information

paths:
    /status:
        get:
            operationId: getStatus
            summary: Get API quota status
            description: Returns your current API quota and usage for the month.
            tags:
                - Account
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/status/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      const { data: status } = await client.account.getStatus();
                      console.log(`Quota: ${status.quota}, Used: ${status.quotaUsed}`);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const url = 'https://api.watchmode.com/v1/status/';

                      const response = await fetch(url, {
                        headers: { 'X-API-Key': apiKey }
                      });
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      url = 'https://api.watchmode.com/v1/status/'
                      request = urllib.request.Request(url, headers={'X-API-Key': api_key})

                      with urllib.request.urlopen(request) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/status/')
                      request = Net::HTTP::Get.new(uri)
                      request['X-API-Key'] = 'YOUR_API_KEY'

                      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
                      json = response.body
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $url = "https://api.watchmode.com/v1/status/";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: {$apiKey}"]);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            responses:
                '200':
                    description: Quota status retrieved successfully
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/StatusResponse'
                            example:
                                quota: 1000
                                quotaUsed: 150
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /sources:
        get:
            operationId: getSources
            summary: List streaming sources
            description: |
                Returns a list of all streaming sources (streaming services, networks, etc.) supported by Watchmode.
                This includes subscription services (like Netflix), rental/purchase services (like iTunes), and free services.
                Each source includes details about supported regions, logos, and app store links.
            tags:
                - Configuration
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/sources/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      const { data: sources } = await client.sources.list();
                      console.log(sources);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const url = `https://api.watchmode.com/v1/sources/?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      url = f'https://api.watchmode.com/v1/sources/?apiKey={api_key}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/sources/?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $url = "https://api.watchmode.com/v1/sources/?apiKey={$apiKey}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - name: regions
                  in: query
                  description: Filter sources by region. Pass one or multiple 2-letter country codes comma-separated (e.g., `US,GB,CA`).
                  schema:
                      type: string
                      example: 'US,GB'
                - name: types
                  in: query
                  description: |
                      Filter sources by type. Pass one or multiple types comma-separated.
                      - `sub` - Subscription services (Netflix, Hulu, etc.)
                      - `purchase` - Rental/purchase services (iTunes, Vudu, etc.)
                      - `free` - Free ad-supported services (Tubi, Pluto TV, etc.)
                      - `tve` - TV Channel App (cable login required)
                  schema:
                      type: string
                      example: 'sub,free'
            responses:
                '200':
                    description: List of streaming sources
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Source'
                            example:
                                - id: 203
                                  name: 'Netflix'
                                  type: 'sub'
                                  logo_100px: 'https://cdn.watchmode.com/logos/203_logo_100px.jpg'
                                  ios_appstore_url: 'https://apps.apple.com/app/id363590051'
                                  android_playstore_url: 'https://play.google.com/store/apps/details?id=com.netflix.mediaclient'
                                  android_tv_url: null
                                  fire_tv_url: null
                                  roku_url: null
                                  tvos_url: null
                                  regions:
                                      - 'US'
                                      - 'GB'
                                      - 'AU'
                                - id: 26
                                  name: 'Amazon Prime'
                                  type: 'sub'
                                  logo_100px: 'https://cdn.watchmode.com/logos/26_logo_100px.jpg'
                                  ios_appstore_url: 'https://apps.apple.com/app/id545519333'
                                  android_playstore_url: 'https://play.google.com/store/apps/details?id=com.amazon.avod.thirdpartyclient'
                                  android_tv_url: null
                                  fire_tv_url: null
                                  roku_url: null
                                  tvos_url: null
                                  regions:
                                      - 'US'
                                      - 'GB'
                                      - 'AU'
                                      - 'CA'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /regions:
        get:
            operationId: getRegions
            summary: List supported regions
            description: Returns a list of all countries/regions that Watchmode supports, including data quality tier and plan availability.
            tags:
                - Configuration
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/regions/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      const { data: regions } = await client.reference.getRegions();
                      console.log(regions);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const url = `https://api.watchmode.com/v1/regions/?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      url = f'https://api.watchmode.com/v1/regions/?apiKey={api_key}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/regions/?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $url = "https://api.watchmode.com/v1/regions/?apiKey={$apiKey}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            responses:
                '200':
                    description: List of supported regions
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Region'
                            example:
                                - country: 'US'
                                  name: 'USA'
                                  flag: 'https://cdn.watchmode.com/misc_images/icons/usFlag2.png'
                                  data_tier: 1
                                  plan_enabled: true
                                - country: 'CA'
                                  name: 'Canada'
                                  flag: 'https://cdn.watchmode.com/misc_images/icons/flagCA.png'
                                  data_tier: 1
                                  plan_enabled: true
                                - country: 'GB'
                                  name: 'Great Britain'
                                  flag: 'https://cdn.watchmode.com/misc_images/icons/flagGB.png'
                                  data_tier: 1
                                  plan_enabled: true
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /networks:
        get:
            operationId: getNetworks
            summary: List TV networks
            description: Returns a list of all TV networks that may be associated with titles.
            tags:
                - Configuration
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/networks/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      const { data: networks } = await client.reference.getNetworks();
                      console.log(networks);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const url = `https://api.watchmode.com/v1/networks/?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      url = f'https://api.watchmode.com/v1/networks/?apiKey={api_key}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/networks/?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $url = "https://api.watchmode.com/v1/networks/?apiKey={$apiKey}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            responses:
                '200':
                    description: List of TV networks
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Network'
                            example:
                                - id: 1
                                  name: 'HBO'
                                  origin_country: 'US'
                                  tmdb_id: 49
                                - id: 2
                                  name: 'National Geographic'
                                  origin_country: 'US'
                                  tmdb_id: 43
                                - id: 7
                                  name: 'ABC'
                                  origin_country: 'US'
                                  tmdb_id: 2
                                - id: 8
                                  name: 'AMC'
                                  origin_country: 'US'
                                  tmdb_id: 174
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /genres:
        get:
            operationId: getGenres
            summary: List genres
            description: Returns a mapping of genre names and IDs. Some genres include corresponding TMDB IDs.
            tags:
                - Configuration
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/genres/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      const { data: genres } = await client.reference.getGenres();
                      console.log(genres);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const url = `https://api.watchmode.com/v1/genres/?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      url = f'https://api.watchmode.com/v1/genres/?apiKey={api_key}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/genres/?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $url = "https://api.watchmode.com/v1/genres/?apiKey={$apiKey}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            responses:
                '200':
                    description: List of genres
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Genre'
                            example:
                                - id: 4
                                  name: 'Comedy'
                                  tmdb_id: 35
                                - id: 6
                                  name: 'Documentary'
                                  tmdb_id: 99
                                - id: 33
                                  name: 'Anime'
                                  tmdb_id: 0
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /search:
        get:
            operationId: search
            summary: Search for titles and people
            description: |
                Search for titles or people using an external ID (IMDB, TMDB) or by name.
                Returns matching titles and people with their Watchmode IDs.
                Useful for getting Watchmode IDs to use with other endpoints.
            tags:
                - Search
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/search/?search_field=name&search_value=Ed%20Wood'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Search by name
                      const { data: results } = await client.search.byName('Ed Wood');
                      console.log(results);

                      // Or search by IMDB ID
                      const { data: imdbResults } = await client.search.byImdbId('tt0109707');
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const searchField = 'name';
                      const searchValue = 'Ed Wood';
                      const url = `https://api.watchmode.com/v1/search/?apiKey=${apiKey}&search_field=${searchField}&search_value=${encodeURIComponent(searchValue)}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json
                      from urllib.parse import urlencode

                      api_key = 'YOUR_API_KEY'
                      search_field = 'name'
                      search_value = 'Ed Wood'

                      params = {
                          'apiKey': api_key,
                          'search_field': search_field,
                          'search_value': search_value
                      }

                      url = f'https://api.watchmode.com/v1/search/?{urlencode(params)}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/search/?apiKey=YOUR_API_KEY&search_field=name&search_value=Ed%20Wood')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $searchField = 'name';
                      $searchValue = 'Ed Wood';
                      $url = "https://api.watchmode.com/v1/search/?apiKey={$apiKey}&search_field={$searchField}&search_value=" . urlencode($searchValue);

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - name: search_field
                  in: query
                  required: true
                  description: |
                      The field to search in:
                      - `name` - Search by title or person name
                      - `imdb_id` - Search by IMDB ID (e.g., tt0944947)
                      - `tmdb_movie_id` - Search by TMDB movie ID
                      - `tmdb_tv_id` - Search by TMDB TV show ID
                      - `tmdb_person_id` - Search by TMDB person ID
                  schema:
                      type: string
                      enum:
                          - name
                          - imdb_id
                          - tmdb_movie_id
                          - tmdb_tv_id
                          - tmdb_person_id
                - name: search_value
                  in: query
                  required: true
                  description: The value to search for (e.g., "Breaking Bad", "tt0944947")
                  schema:
                      type: string
                      example: 'Breaking Bad'
                - name: types
                  in: query
                  description: Filter results by type. Pass comma-separated values (e.g., `tv,movie,person`)
                  schema:
                      type: string
                      example: 'tv,movie'
            responses:
                '200':
                    description: Search results
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SearchResponse'
                            example:
                                title_results:
                                    - id: 3173903
                                      name: 'Breaking Bad'
                                      type: 'tv_series'
                                      year: 2008
                                      imdb_id: 'tt0903747'
                                      tmdb_id: 1396
                                      tmdb_type: 'tv'
                                people_results:
                                    - id: 710125611
                                      name: 'Bryan Cranston'
                                      main_profession: 'actor'
                                      imdb_id: 'nm0186505'
                                      tmdb_id: 17419
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /autocomplete-search:
        get:
            operationId: autocompleteSearch
            summary: Autocomplete search
            description: |
                Search for titles and/or people by name or partial name.
                Optimized for building autocomplete/typeahead search interfaces.
                Results include relevance scores and thumbnail images.
            tags:
                - Search
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/autocomplete-search/?search_value=Breaking%20bad&search_type=1'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Autocomplete search (optimized for typeahead)
                      const { data } = await client.search.autocomplete('Breaking bad', {
                        searchType: 2  // 2 = titles only
                      });
                      console.log(data);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const searchValue = 'Breaking bad';
                      const searchType = 1; // 1 = titles and people
                      const url = `https://api.watchmode.com/v1/autocomplete-search/?apiKey=${apiKey}&search_value=${encodeURIComponent(searchValue)}&search_type=${searchType}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json
                      from urllib.parse import urlencode

                      api_key = 'YOUR_API_KEY'
                      search_value = 'Breaking bad'
                      search_type = 1  # 1 = titles and people

                      params = {
                          'apiKey': api_key,
                          'search_value': search_value,
                          'search_type': search_type
                      }

                      url = f'https://api.watchmode.com/v1/autocomplete-search/?{urlencode(params)}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/autocomplete-search/?apiKey=YOUR_API_KEY&search_value=Breaking%20bad&search_type=1')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $searchValue = 'Breaking bad';
                      $searchType = 1; // 1 = titles and people
                      $url = "https://api.watchmode.com/v1/autocomplete-search/?apiKey={$apiKey}&search_value=" . urlencode($searchValue) . "&search_type={$searchType}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - name: search_value
                  in: query
                  required: true
                  description: The search phrase (can be partial, e.g., "The Sha" will find "The Shawshank Redemption")
                  schema:
                      type: string
                      example: 'Breaking bad'
                - name: search_type
                  in: query
                  description: |
                      Filter result types:
                      - `1` - Titles and people (default)
                      - `2` - Titles only
                      - `3` - Movies only
                      - `4` - TV shows only
                      - `5` - People only
                  schema:
                      type: integer
                      enum: [1, 2, 3, 4, 5]
                      default: 1
            responses:
                '200':
                    description: Autocomplete results
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AutocompleteResponse'
                            example:
                                results:
                                    - name: 'Breaking Bad'
                                      relevance: 445.23
                                      type: 'tv_series'
                                      id: 3173903
                                      year: 2008
                                      result_type: 'title'
                                      imdb_id: 'tt0903747'
                                      tmdb_id: 1396
                                      tmdb_type: 'tv'
                                      image_url: 'http://www.some-poster-site.com/image.jpg'
                                    - name: 'El Camino: A Breaking Bad Movie'
                                      relevance: 169.83
                                      type: 'movie'
                                      id: 1586594
                                      year: 2019
                                      result_type: 'title'
                                      imdb_id: 'tt9243946'
                                      tmdb_id: 559969
                                      tmdb_type: 'movie'
                                      image_url: 'http://www.some-poster-site.com/image.jpg'
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /list-titles:
        get:
            operationId: listTitles
            summary: List and filter titles
            description: |
                Get a paginated list of titles matching specified criteria.
                This powerful endpoint allows granular filtering such as "Horror movies streaming on Netflix in the USA".

                **Quota Notes:**
                - Each additional region costs 1 API credit
                - When using `source_ids` or `source_types`, only one region is allowed
            tags:
                - Title
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/list-titles/?source_ids=203,57'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // List titles with filtering
                      const { data } = await client.title.list({
                        types: 'movie',
                        genres: '12',           // Horror genre ID
                        sourceIds: '203',       // Netflix
                        regions: 'US',
                        sortBy: 'popularity_desc',
                        page: 1,
                        limit: 50
                      });
                      console.log(data);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const sourceIds = '203,57';
                      const url = `https://api.watchmode.com/v1/list-titles/?apiKey=${apiKey}&source_ids=${sourceIds}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      source_ids = '203,57'
                      url = f'https://api.watchmode.com/v1/list-titles/?apiKey={api_key}&source_ids={source_ids}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/list-titles/?apiKey=YOUR_API_KEY&source_ids=203,57')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $sourceIds = '203,57';
                      $url = "https://api.watchmode.com/v1/list-titles/?apiKey={$apiKey}&source_ids={$sourceIds}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - name: types
                  in: query
                  description: |
                      Filter by title type. Comma-separated for multiple values.
                      Valid types: `movie`, `tv_series`, `tv_movie`, `tv_special`, `tv_miniseries`, `short_film`
                  schema:
                      type: string
                      example: 'movie,tv_series'
                - name: regions
                  in: query
                  description: Filter by region (2-letter country code). Comma-separated for multiple.
                  schema:
                      type: string
                      example: 'US'
                - name: source_types
                  in: query
                  description: |
                      Filter by source type. Comma-separated values.
                      - `sub` - Subscription
                      - `rent` - Rental
                      - `buy` - Purchase
                      - `free` - Free
                      - `tve` - TV Channel App (Cable Plan Required)
                  schema:
                      type: string
                      example: 'sub,free'
                - name: source_ids
                  in: query
                  description: Filter by specific source IDs (from `/sources` endpoint). Comma-separated.
                  schema:
                      type: string
                      example: '203,26'
                - name: genres
                  in: query
                  description: Filter by genre IDs (from `/genres` endpoint). Comma-separated.
                  schema:
                      type: string
                      example: '4,7'
                - name: network_ids
                  in: query
                  description: Filter by network IDs (from `/networks` endpoint). Comma-separated.
                  schema:
                      type: string
                      example: '1,8'
                - name: languages
                  in: query
                  description: Filter by primary language (2-letter ISO 639 code). Comma-separated.
                  schema:
                      type: string
                      example: 'en,es'
                - name: release_date_start
                  in: query
                  description: Filter by release date start (format YYYYMMDD)
                  schema:
                      type: integer
                      example: 20200101
                - name: release_date_end
                  in: query
                  description: Filter by release date end (format YYYYMMDD)
                  schema:
                      type: integer
                      example: 20231231
                - name: user_rating_low
                  in: query
                  description: Minimum user rating (0-10)
                  schema:
                      type: number
                      minimum: 0
                      maximum: 10
                - name: user_rating_high
                  in: query
                  description: Maximum user rating (0-10)
                  schema:
                      type: number
                      minimum: 0
                      maximum: 10
                - name: critic_score_low
                  in: query
                  description: Minimum critic score (0-100)
                  schema:
                      type: integer
                      minimum: 0
                      maximum: 100
                - name: critic_score_high
                  in: query
                  description: Maximum critic score (0-100)
                  schema:
                      type: integer
                      minimum: 0
                      maximum: 100
                - name: person_id
                  in: query
                  description: Filter by person ID (actor, director, etc.)
                  schema:
                      type: integer
                      example: 7110004
                - name: sort_by
                  in: query
                  description: Sort order for results. Popularity options use Watchmode's normalized popularity percentile.
                  schema:
                      type: string
                      enum:
                          - relevance_desc
                          - relevance_asc
                          - popularity_desc
                          - popularity_asc
                          - release_date_desc
                          - release_date_asc
                          - title_desc
                          - title_asc
                      default: relevance_desc
                - $ref: '#/components/parameters/page'
                - name: limit
                  in: query
                  description: Results per page (1-250)
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 250
                      default: 250
            responses:
                '200':
                    description: Paginated list of titles
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListTitlesResponse'
                            example:
                                titles:
                                    - id: 1337513
                                      title: 'Secret in Their Eyes'
                                      year: 2015
                                      imdb_id: 'tt1741273'
                                      tmdb_id: 290751
                                      tmdb_type: 'movie'
                                      type: 'movie'
                                      popularity_percentile: 99.421
                                    - id: 1247225
                                      title: 'Spy Cat'
                                      year: 2018
                                      imdb_id: 'tt5746054'
                                      tmdb_id: 509733
                                      tmdb_type: 'movie'
                                      type: 'movie'
                                      popularity_percentile: 97.618
                                page: 1
                                total_results: 4592
                                total_pages: 19
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /title/{title_id}/details:
        get:
            operationId: getTitleDetails
            summary: Get title details
            description: |
                Get detailed information about a specific movie or TV show.

                **ID Formats Accepted:**
                - Watchmode ID (e.g., `345534`) - costs 1 credit
                - IMDB ID (e.g., `tt0903747`) - costs 2 credits
                - TMDB format (e.g., `movie-278` or `tv-1396`) - costs 2 credits

                Use `append_to_response` to include additional data in a single request.
            tags:
                - Title
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/title/345534/details/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get title details
                      const { data: title } = await client.title.getDetails('345534');
                      console.log(title);

                      // With additional data appended
                      const { data: fullTitle } = await client.title.getDetails('345534', {
                        appendToResponse: 'sources,cast-crew',
                        regions: 'US'
                      });
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const titleId = '345534';
                      const url = `https://api.watchmode.com/v1/title/${titleId}/details/?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      title_id = '345534'
                      url = f'https://api.watchmode.com/v1/title/{title_id}/details/?apiKey={api_key}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/title/345534/details/?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $titleId = '345534';
                      $url = "https://api.watchmode.com/v1/title/{$titleId}/details/?apiKey={$apiKey}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/titleId'
                - name: append_to_response
                  in: query
                  description: |
                      Include additional data. Comma-separated values. Each adds 1 credit.
                      - `sources` - Streaming availability
                      - `seasons` - Season list (TV only)
                      - `episodes` - Episode list with sources (TV only)
                      - `cast-crew` - Cast and crew
                  schema:
                      type: string
                      example: 'sources,cast-crew'
                - name: language
                  in: query
                  description: ISO 639-1 language code for localized title/overview (default `en`)
                  schema:
                      type: string
                      default: en
                      example: es
                - name: regions
                  in: query
                  description: Filter sources by region when using `append_to_response=sources` or `append_to_response=episodes`. Comma-separated. Requested regions must be enabled for your plan. If omitted, returns sources from regions enabled for your plan.
                  schema:
                      type: string
                      example: 'US,CA'
            responses:
                '200':
                    description: Title details
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TitleDetails'
                            example:
                                id: 3173903
                                title: 'Breaking Bad'
                                original_title: 'Breaking Bad'
                                plot_overview: 'When Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer...'
                                will_you_like_this: 'If you like intense character dramas with high stakes, you’ll probably enjoy this.'
                                review_summary: 'Critics praise the writing and performances; viewers highlight the show’s tense pacing and standout finale.'
                                type: 'tv_series'
                                runtime_minutes: 45
                                year: 2008
                                end_year: 2013
                                release_date: '2008-01-20'
                                imdb_id: 'tt0903747'
                                tmdb_id: 1396
                                tmdb_type: 'tv'
                                genres: [7]
                                genre_names: ['Drama']
                                user_rating: 9.2
                                critic_score: 85
                                us_rating: 'TV-MA'
                                content_ratings:
                                    AU: 'MA 15+'
                                    US: 'TV-MA'
                                poster: 'http://www.some-poster-site.com/image.jpg'
                                posterMedium: 'http://www.some-poster-site.com/image.jpg'
                                posterLarge: 'http://www.some-poster-site.com/image.jpg'
                                backdrop: 'http://www.some-poster-site.com/image.jpg'
                                original_language: 'en'
                                similar_titles: [330884, 343611]
                                networks: [8]
                                network_names: ['AMC']
                                relevance_percentile: 98.92
                                popularity_percentile: 99.99
                                trailer: 'https://www.youtube.com/watch?v=5PSNL1qE6VY'
                                trailer_thumbnail: 'http://www.some-poster-site.com/image.jpg'
                '404':
                    $ref: '#/components/responses/NotFound'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /title/{title_id}/sources:
        get:
            operationId: getTitleSources
            summary: Get title streaming sources
            description: |
                Get all streaming sources where a title is currently available.
                Returns subscription services, rental options, purchase options, and free streaming.
                For TV shows, includes information about available seasons and episodes per source.
            tags:
                - Title
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/title/345534/sources/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get streaming sources for a title
                      const { data: sources } = await client.title.getSources('345534', {
                        regions: 'US'
                      });
                      console.log(sources);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const titleId = '345534';
                      const url = `https://api.watchmode.com/v1/title/${titleId}/sources/?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      title_id = '345534'
                      url = f'https://api.watchmode.com/v1/title/{title_id}/sources/?apiKey={api_key}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/title/345534/sources/?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $titleId = '345534';
                      $url = "https://api.watchmode.com/v1/title/{$titleId}/sources/?apiKey={$apiKey}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/titleId'
                - name: regions
                  in: query
                  description: Filter by region (2-letter country code). Comma-separated for multiple. Requested regions must be enabled for your plan. If omitted, returns sources from regions enabled for your plan.
                  schema:
                      type: string
                      example: 'US,CA'
            responses:
                '200':
                    description: List of streaming sources
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/TitleSource'
                            example:
                                - source_id: 203
                                  name: 'Netflix'
                                  type: 'sub'
                                  region: 'US'
                                  ios_url: 'https://www.netflix.com/title/123456'
                                  android_url: 'https://www.netflix.com/title/123456'
                                  web_url: 'https://www.netflix.com/title/123456'
                                  format: 'HD'
                                  price: null
                                  seasons: 5
                                  episodes: 62
                '404':
                    $ref: '#/components/responses/NotFound'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /title/{title_id}/seasons:
        get:
            operationId: getTitleSeasons
            summary: Get title seasons
            description: Get all seasons for a TV series or mini-series.
            tags:
                - Title
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/title/345534/seasons/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get seasons for a TV series
                      const { data: seasons } = await client.title.getSeasons('345534');
                      console.log(seasons);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const titleId = '345534';
                      const url = `https://api.watchmode.com/v1/title/${titleId}/seasons/?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      title_id = '345534'
                      url = f'https://api.watchmode.com/v1/title/{title_id}/seasons/?apiKey={api_key}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/title/345534/seasons/?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $titleId = '345534';
                      $url = "https://api.watchmode.com/v1/title/{$titleId}/seasons/?apiKey={$apiKey}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/titleId'
            responses:
                '200':
                    description: List of seasons
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Season'
                            example:
                                - id: 12345
                                  poster_url: 'http://www.some-poster-site.com/image.jpg'
                                  name: 'Season 1'
                                  overview: 'The first season introduces Walter White...'
                                  number: 1
                                  air_date: '2008-01-20'
                                  episode_count: 7
                '404':
                    $ref: '#/components/responses/NotFound'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /title/{title_id}/episodes:
        get:
            operationId: getTitleEpisodes
            summary: Get title episodes
            description: |
                Get episodes for a TV series or mini-series, including streaming sources for each episode.
                For paid plans, includes deep links to watch each episode on streaming services.
                Use `season` and `episode` for granular retrieval, or `limit` and `offset` to page through large series.
                Episode localization is opt-in with `episode_language`; unavailable fields fall back to English.
            tags:
                - Title
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/title/345534/episodes/?regions=US'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get one season with localized metadata and US streaming sources
                      const { data: episodes } = await client.title.getEpisodes('345534', {
                        season: 2,
                        episodeLanguage: 'nl',
                        regions: 'US'
                      });
                      console.log(episodes);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const titleId = '345534';
                      const regions = 'US';
                      const url = `https://api.watchmode.com/v1/title/${titleId}/episodes/?apiKey=${apiKey}&regions=${regions}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      title_id = '345534'
                      regions = 'US'
                      url = f'https://api.watchmode.com/v1/title/{title_id}/episodes/?apiKey={api_key}&regions={regions}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/title/345534/episodes/?apiKey=YOUR_API_KEY&regions=US')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $titleId = '345534';
                      $regions = 'US';
                      $url = "https://api.watchmode.com/v1/title/{$titleId}/episodes/?apiKey={$apiKey}&regions={$regions}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/titleId'
                - name: regions
                  in: query
                  description: Filter episode sources by region (2-letter country code). Comma-separated for multiple. Requested regions must be enabled for your plan. If omitted, returns sources from regions enabled for your plan.
                  schema:
                      type: string
                      example: 'US,CA'
                - name: season
                  in: query
                  description: Return episodes from this displayed season number only.
                  schema:
                      type: integer
                      minimum: 1
                - name: episode
                  in: query
                  description: Return this episode number within `season`. Requires `season`.
                  schema:
                      type: integer
                      minimum: 1
                - name: episode_id
                  in: query
                  description: Return the episode with this Watchmode episode ID. For a single-object response, use `/title/{title_id}/episodes/{episode_id}`.
                  schema:
                      type: integer
                      minimum: 1
                - name: episode_language
                  in: query
                  description: Preferred BCP-47 language for episode names and overviews. Localized fields fall back to English when unavailable. Existing requests remain English by default.
                  schema:
                      type: string
                      maxLength: 35
                      pattern: '^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$'
                      example: nl
                - name: include_sources
                  in: query
                  description: Set to false when streaming sources are not needed. This reduces response size and retrieval time.
                  schema:
                      type: boolean
                      default: true
                - name: limit
                  in: query
                  description: Maximum number of episode rows to return.
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 500
                - name: offset
                  in: query
                  description: Number of episode rows to skip. Requires `limit`.
                  schema:
                      type: integer
                      minimum: 0
            responses:
                '200':
                    description: List of episodes with sources
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Episode'
                            example:
                                - id: 1234567
                                  name: 'Pilot'
                                  episode_number: 1
                                  season_number: 1
                                  season_id: 12345
                                  tmdb_id: 54321
                                  imdb_id: 'tt0959621'
                                  thumbnail_url: 'http://www.some-poster-site.com/image.jpg'
                                  release_date: '2008-01-20'
                                  runtime_minutes: 58
                                  overview: 'Walter White, a high school chemistry teacher...'
                                  sources:
                                      - source_id: 203
                                        name: 'Netflix'
                                        type: 'sub'
                                        region: 'US'
                                        web_url: 'https://www.netflix.com/watch/123456'
                '404':
                    $ref: '#/components/responses/NotFound'
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /title/{title_id}/episodes/{episode_id}:
        get:
            operationId: getTitleEpisode
            summary: Get a single episode
            description: |
                Get one episode by its Watchmode episode ID. Streaming sources are included by default.
                Use `episode_language` for localized episode metadata and `include_sources=false` for a smaller response.
            tags:
                - Title
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/title/345534/episodes/1234567?episode_language=nl&regions=US'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });
                      const { data: episode } = await client.title.getEpisode('345534', 1234567, {
                        episodeLanguage: 'nl',
                        regions: 'US'
                      });
                      console.log(episode);
            parameters:
                - $ref: '#/components/parameters/titleId'
                - name: episode_id
                  in: path
                  required: true
                  description: Watchmode episode ID.
                  schema:
                      type: integer
                      minimum: 1
                - name: regions
                  in: query
                  description: Filter episode sources by region (2-letter country code). Comma-separated for multiple.
                  schema:
                      type: string
                      example: 'US,CA'
                - name: episode_language
                  in: query
                  description: Preferred BCP-47 language for the episode name and overview. Localized fields fall back to English when unavailable.
                  schema:
                      type: string
                      maxLength: 35
                      pattern: '^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$'
                      example: nl
                - name: include_sources
                  in: query
                  description: Set to false when streaming sources are not needed.
                  schema:
                      type: boolean
                      default: true
            responses:
                '200':
                    description: Episode details with sources
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Episode'
                '404':
                    $ref: '#/components/responses/NotFound'
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /title/{title_id}/cast-crew:
        get:
            operationId: getTitleCastCrew
            summary: Get title cast and crew
            description: Get all cast (actors) and crew (directors, writers, etc.) associated with a title.
            tags:
                - Title
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/title/345534/cast-crew/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get cast and crew for a title
                      const { data: credits } = await client.title.getCastCrew('345534');
                      console.log(credits);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const titleId = '345534';
                      const url = `https://api.watchmode.com/v1/title/${titleId}/cast-crew/?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      title_id = '345534'
                      url = f'https://api.watchmode.com/v1/title/{title_id}/cast-crew/?apiKey={api_key}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/title/345534/cast-crew/?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $titleId = '345534';
                      $url = "https://api.watchmode.com/v1/title/{$titleId}/cast-crew/?apiKey={$apiKey}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/titleId'
                - name: language
                  in: query
                  description: ISO 639-1 language code for localized names (default `en`)
                  schema:
                      type: string
                      default: en
            responses:
                '200':
                    description: Cast and crew list
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/CastCrew'
                            example:
                                - person_id: 7110004
                                  type: 'Cast'
                                  full_name: 'Bryan Cranston'
                                  role: 'Walter White'
                                  episode_count: 62
                                  order: 1
                                - person_id: 7110005
                                  type: 'Crew'
                                  full_name: 'Vince Gilligan'
                                  role: 'Creator'
                                  episode_count: 62
                                  order: null
                '404':
                    $ref: '#/components/responses/NotFound'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /title/{title_id}/incorrect-data:
        get:
            operationId: reportIncorrectData
            summary: Report incorrect title data
            description: |
                Report incorrect or missing data for a title. This endpoint helps improve data quality
                by allowing users to flag issues with title information.

                **Note:** This endpoint does not count against your quota as users are helping improve data quality.
            tags:
                - Title
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/title/345534/incorrect-data/?sourceMissing=1&somethingWrongDetails=Missing%20Netflix'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Report incorrect data for a title
                      const { data } = await client.title.reportIncorrectData('345534', {
                        sourceMissing: 1,
                        somethingWrongDetails: 'Missing Netflix availability'
                      });
                      console.log(data);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const titleId = '345534';
                      const params = new URLSearchParams({
                        apiKey,
                        sourceMissing: '1',
                        somethingWrongDetails: 'Missing Netflix availability'
                      });
                      const url = `https://api.watchmode.com/v1/title/${titleId}/incorrect-data/?${params}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json
                      from urllib.parse import urlencode

                      api_key = 'YOUR_API_KEY'
                      title_id = '345534'
                      params = urlencode({
                          'apiKey': api_key,
                          'sourceMissing': 1,
                          'somethingWrongDetails': 'Missing Netflix availability'
                      })
                      url = f'https://api.watchmode.com/v1/title/{title_id}/incorrect-data/?{params}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/title/345534/incorrect-data/?apiKey=YOUR_API_KEY&sourceMissing=1')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $titleId = '345534';
                      $params = http_build_query([
                          'apiKey' => $apiKey,
                          'sourceMissing' => 1,
                          'somethingWrongDetails' => 'Missing Netflix availability'
                      ]);
                      $url = "https://api.watchmode.com/v1/title/{$titleId}/incorrect-data/?{$params}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/titleId'
                - name: somethingWrongDescription
                  in: query
                  description: Flag indicating description/overview is incorrect (1 = yes)
                  schema:
                      type: integer
                      enum: [0, 1]
                - name: serviceIncorrect
                  in: query
                  description: Flag indicating streaming service info is incorrect (1 = yes)
                  schema:
                      type: integer
                      enum: [0, 1]
                - name: sourceMissing
                  in: query
                  description: Flag indicating a streaming source is missing (1 = yes)
                  schema:
                      type: integer
                      enum: [0, 1]
                - name: somethingElseWrong
                  in: query
                  description: Flag indicating other issue (1 = yes)
                  schema:
                      type: integer
                      enum: [0, 1]
                - name: somethingWrongDetails
                  in: query
                  description: Free-text description of the issue
                  schema:
                      type: string
            responses:
                '200':
                    description: Report received successfully
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    success:
                                        type: boolean
                                        example: true
                                    statusMessage:
                                        type: string
                                        example: 'Request to correct title information received. Please wait 2 minutes while we attempt to auto-correct the issue.'
                '404':
                    $ref: '#/components/responses/NotFound'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /person/{person_id}:
        get:
            operationId: getPerson
            summary: Get person details
            description: |
                Get detailed information about a person including biographical data and known titles.
                Person IDs in Watchmode always start with `7` followed by the actual ID.
            tags:
                - Person
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/person/7110004'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get person details
                      const { data: person } = await client.person.getDetails(7110004);
                      console.log(person?.full_name);  // "Brad Pitt"
                      console.log(person?.known_for);  // Array of title IDs
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const personId = '7110004';
                      const url = `https://api.watchmode.com/v1/person/${personId}?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      person_id = '7110004'
                      url = f'https://api.watchmode.com/v1/person/{person_id}?apiKey={api_key}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/person/7110004?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $personId = '7110004';
                      $url = "https://api.watchmode.com/v1/person/{$personId}?apiKey={$apiKey}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - name: person_id
                  in: path
                  required: true
                  description: Watchmode person ID (starts with 7, e.g., `7110004`)
                  schema:
                      type: integer
                      example: 7110004
            responses:
                '200':
                    description: Person details
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Person'
                            example:
                                id: 7110004
                                full_name: 'Brad Pitt'
                                first_name: 'Brad'
                                last_name: 'Pitt'
                                tmdb_id: 287
                                imdb_id: 'nm0000093'
                                main_profession: 'actor'
                                secondary_profession: 'producer'
                                tertiary_profession: 'soundtrack'
                                date_of_birth: '1963-12-18'
                                date_of_death: null
                                place_of_birth: 'Shawnee, Oklahoma, USA'
                                gender: 'm'
                                known_for: [1132806, 1336708, 1183315, 1387087]
                                relevance_percentile: 100
                '404':
                    $ref: '#/components/responses/NotFound'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /releases:
        get:
            operationId: getReleases
            summary: Get Title Release Dates - Simple
            description: |
                Get recently released or upcoming releases on major streaming services.
                Includes original content flags to identify platform exclusives.
                Primarily US release dates, though most major services release globally on the same day.
            tags:
                - Releases
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/releases/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get recent/upcoming releases
                      const { data } = await client.releases.getRecent({
                        startDate: 20240101,
                        endDate: 20240131,
                        limit: 100
                      });
                      console.log(data);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const url = `https://api.watchmode.com/v1/releases/?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      api_key = 'YOUR_API_KEY'
                      url = f'https://api.watchmode.com/v1/releases/?apiKey={api_key}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/releases/?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $url = "https://api.watchmode.com/v1/releases/?apiKey={$apiKey}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - name: start_date
                  in: query
                  description: |
                      Get releases after this date (PST timezone).
                      Format: `YYYYMMDD` or `YYYYMMDDHHMMSS`
                      Default: 30 days ago
                  schema:
                      type: integer
                      example: 20240101
                - name: end_date
                  in: query
                  description: |
                      Get releases before this date (PST timezone).
                      Format: `YYYYMMDD` or `YYYYMMDDHHMMSS`
                      Default: 30 days from now
                  schema:
                      type: integer
                      example: 20240131
                - name: limit
                  in: query
                  description: Number of results (1-250)
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 250
                      default: 250
            responses:
                '200':
                    description: List of releases
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ReleasesResponse'
                            example:
                                releases:
                                    - id: 3165490
                                      title: 'Slow Horses'
                                      type: 'tv_series'
                                      tmdb_id: 95480
                                      tmdb_type: 'tv'
                                      imdb_id: 'tt5875444'
                                      season_number: 1
                                      poster_url: 'http://www.some-poster-site.com/image.jpg'
                                      source_release_date: '2022-04-01'
                                      source_id: 371
                                      source_name: 'AppleTV+'
                                      is_original: 1
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'

    /title-release-dates:
        get:
            operationId: getTitleReleaseDatesAdvanced
            summary: Get Title Release Dates - Advanced
            description: |
                Get streaming and theatrical release dates for titles within a specified date range.
                Includes both historical and upcoming releases, as well as streaming premieres and theatrical releases.

                Release dates are returned as normalized calendar dates in `YYYY-MM-DD` format. When an upstream source provides a midnight UTC
                availability timestamp that is stored in a US time zone, Watchmode normalizes it back to the intended UTC calendar date before
                filtering and returning results.

                By default, this endpoint returns all region-specific release rows available to Watchmode. Use the `regions` parameter to filter
                results to specific countries. Some legacy streaming release-date sources are US-only; those rows are returned with `region: "US"`.

                Region-specific streaming rows include a verification status. Watchmode only publishes rows matched to an exact digital release for
                the named provider. Upcoming rows are `scheduled`; after the release date Watchmode checks provider availability in that region and
                marks matching rows `confirmed_available`. Rows without a completed check remain `unverified`, while rows contradicted by a completed
                regional provider check are withheld from the response.

                Outside the US, theatrical rows are materialized for `data_tier: 1` regions from movie release events explicitly classified as
                limited theatrical or theatrical by the upstream source. Digital, physical-media, television, festival, and premiere-only events
                are not returned as theatrical releases. US theatrical rows continue to use Watchmode's legacy theatrical calendar source.

                `release_at` is a nullable ISO 8601 UTC instant and `release_timezone` is its source IANA time zone.
                `time_precision` is `time` only when fresh source evidence identifies a unique local web-channel season premiere
                matching the title, season, provider, country and release date. Global web-channel placeholder timestamps,
                broadcast airtimes, conflicting times, incomplete timing evidence and evidence older than 48 hours are not used.
                Otherwise both time fields are null and `time_precision` is `date`. A date-only value must not be interpreted
                as midnight UTC for notifications. Scheduled times do not guarantee that a playback link is already available.

                For upcoming streaming markets, request the future date window and group streaming rows by title `id`, collecting
                their unique `region` values. Exclude `theatrical_release` rows when building streaming country lists.
                This includes known scheduled releases before playback links exist; no per-title follow-up requests are needed.
                Countries are limited to the requested date/region scope and observed source coverage, not every future licensing territory.
                An absent country means no known release in the returned scope. Check the truncation headers before treating the list as complete.
                The time fields do not add credits to this request.

                **Note:** This endpoint requires a paid plan.
            tags:
                - Releases
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/title-release-dates/?start_date=20240101&end_date=20240331&regions=US,GB'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get advanced release dates (paid plans only)
                      const { data } = await client.releases.getReleaseDates({
                        startDate: 20240101,
                        endDate: 20240331,
                        regions: 'US,GB'
                      });
                      console.log(data);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const startDate = 20240101;
                      const endDate = 20240331;
                      const regions = 'US,GB';
                      const url = `https://api.watchmode.com/v1/title-release-dates/?apiKey=${apiKey}&start_date=${startDate}&end_date=${endDate}&regions=${regions}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json
                      from urllib.parse import urlencode

                      api_key = 'YOUR_API_KEY'
                      params = urlencode({
                          'apiKey': api_key,
                          'start_date': 20240101,
                          'end_date': 20240331,
                          'regions': 'US,GB'
                      })
                      url = f'https://api.watchmode.com/v1/title-release-dates/?{params}'

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/title-release-dates/?apiKey=YOUR_API_KEY&start_date=20240101&end_date=20240331&regions=US,GB')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $apiKey = 'YOUR_API_KEY';
                      $params = http_build_query([
                          'apiKey' => $apiKey,
                          'start_date' => 20240101,
                          'end_date' => 20240331,
                          'regions' => 'US,GB'
                      ]);
                      $url = "https://api.watchmode.com/v1/title-release-dates/?{$params}";

                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, $url);
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
            parameters:
                - name: start_date
                  in: query
                  description: |
                      Filter releases on or after this normalized calendar date.
                      Format: `YYYYMMDD` or `YYYYMMDDHHMMSS`
                  schema:
                      type: integer
                      example: 20240101
                - name: end_date
                  in: query
                  description: |
                      Filter releases on or before this normalized calendar date.
                      Format: `YYYYMMDD` or `YYYYMMDDHHMMSS`
                  schema:
                      type: integer
                      example: 20240131
                - name: regions
                  in: query
                  description: Filter by region(s). Pass a single 2-character region code or multiple comma-separated codes (e.g., "US" or "US,GB,CA"). Use the /regions endpoint to get a list of valid region codes. If not provided, returns releases from all regions.
                  schema:
                      type: string
                      example: US,GB
            responses:
                '200':
                    description: List of upcoming release dates
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/TitleReleaseDate'
                            example:
                                - id: 1234567
                                  title: 'Dune: Part Two'
                                  title_type: 'movie'
                                  original_language: 'en'
                                  region: 'US'
                                  type: 'theatrical_release'
                                  release_date: '2024-03-01'
                                  provider_id: null
                                  season: null
                                - id: 3173903
                                  title: 'Stranger Things'
                                  title_type: 'tv_series'
                                  original_language: 'en'
                                  region: 'US'
                                  type: 'streaming_tv_season_release'
                                  release_date: '2024-07-01'
                                  provider_id: 203
                                  season: 5
                '401':
                    description: Unauthorized or free plan
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
                            example:
                                success: false
                                statusCode: 401
                                statusMessage: 'The release dates endpoint is only available with paid plans.'

    # TEMPORARILY COMMENTED OUT - Uncomment when ready to publish
    # /title-leaving-dates:
    #     get:
    #         operationId: getTitleLeavingDates
    #         summary: Get Title Leaving Dates
    #         description: |
    #             Get dates when titles are leaving or have left streaming services within a specified date range.
    #             This is the opposite of the title-release-dates endpoint - it shows when content is being removed from streaming platforms.
    #
    #             By default, this endpoint returns leaving dates for all supported countries. Use the `regions` parameter to filter results to specific countries.
    #
    #             **Note:** This endpoint requires a paid plan.
    #         tags:
    #             - Releases
    #         x-codeSamples:
    #             - lang: Shell
    #               source: |
    #                   curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/title-leaving-dates/?start_date=20240101&end_date=20240331&regions=US,GB'
    #             - lang: TypeScript
    #               label: TypeScript SDK
    #               source: |
    #                   // npm install @watchmode/api-client
    #                   import { WatchmodeClient } from '@watchmode/api-client';
    #
    #                   const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });
    #
    #                   // Get titles leaving streaming services (paid plans only)
    #                   const { data } = await client.releases.getLeavingDates({
    #                     startDate: 20240101,
    #                     endDate: 20240331,
    #                     regions: 'US,GB'
    #                   });
    #                   console.log(data);
    #             - lang: JavaScript
    #               source: |
    #                   const apiKey = 'YOUR_API_KEY';
    #                   const startDate = 20240101;
    #                   const endDate = 20240331;
    #                   const regions = 'US,GB';
    #                   const url = `https://api.watchmode.com/v1/title-leaving-dates/?apiKey=${apiKey}&start_date=${startDate}&end_date=${endDate}&regions=${regions}`;
    #
    #                   const response = await fetch(url);
    #                   const json = await response.json();
    #                   console.log(json);
    #             - lang: Python
    #               source: |
    #                   import urllib.request
    #                   import json
    #                   from urllib.parse import urlencode
    #
    #                   api_key = 'YOUR_API_KEY'
    #                   params = urlencode({
    #                       'apiKey': api_key,
    #                       'start_date': 20240101,
    #                       'end_date': 20240331,
    #                       'regions': 'US,GB'
    #                   })
    #                   url = f'https://api.watchmode.com/v1/title-leaving-dates/?{params}'
    #
    #                   with urllib.request.urlopen(url) as response:
    #                       data = json.loads(response.read().decode())
    #                       print(data)
    #             - lang: Ruby
    #               source: |
    #                   require 'net/http'
    #                   require 'uri'
    #                   require 'json'
    #
    #                   uri = URI('https://api.watchmode.com/v1/title-leaving-dates/?apiKey=YOUR_API_KEY&start_date=20240101&end_date=20240331&regions=US,GB')
    #                   json = Net::HTTP.get(uri)
    #                   result = JSON(json)
    #                   print(result)
    #             - lang: PHP
    #               source: |
    #                   <?php
    #                   $apiKey = 'YOUR_API_KEY';
    #                   $params = http_build_query([
    #                       'apiKey' => $apiKey,
    #                       'start_date' => 20240101,
    #                       'end_date' => 20240331,
    #                       'regions' => 'US,GB'
    #                   ]);
    #                   $url = "https://api.watchmode.com/v1/title-leaving-dates/?{$params}";
    #
    #                   $ch = curl_init();
    #                   curl_setopt($ch, CURLOPT_URL, $url);
    #                   curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    #                   curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
    #                   $response = curl_exec($ch);
    #                   curl_close($ch);
    #
    #                   $json = json_decode($response);
    #         parameters:
    #             - name: start_date
    #               in: query
    #               description: Filter leaving dates after this date (format YYYYMMDD)
    #               schema:
    #                   type: integer
    #                   example: 20240101
    #             - name: end_date
    #               in: query
    #               description: Filter leaving dates before this date (format YYYYMMDD)
    #               schema:
    #                   type: integer
    #                   example: 20240131
    #             - name: regions
    #               in: query
    #               description: Filter by region(s). Pass a single 2-character region code or multiple comma-separated codes (e.g., "US" or "US,GB,CA"). Use the /regions endpoint to get a list of valid region codes. If not provided, returns leaving dates from all regions.
    #               schema:
    #                   type: string
    #                   example: US,GB
    #         responses:
    #             '200':
    #                 description: List of titles leaving streaming services
    #                 content:
    #                     application/json:
    #                         schema:
    #                             type: array
    #                             items:
    #                                 $ref: '#/components/schemas/TitleLeavingDate'
    #                         example:
    #                             - id: 1234567
    #                               title: 'The Office'
    #                               title_type: 'tv_series'
    #                               region: 'US'
    #                               type: 'streaming_tv_season_leaving'
    #                               leaving_date: '2024-03-01'
    #                               provider_id: 203
    #                               season: 9
    #                             - id: 345678
    #                               title: 'Inception'
    #                               title_type: 'movie'
    #                               region: 'US'
    #                               type: 'streaming_movie_leaving'
    #                               leaving_date: '2024-03-15'
    #                               provider_id: 387
    #                               season: null
    #             '401':
    #                 description: Unauthorized or free plan
    #                 content:
    #                     application/json:
    #                         schema:
    #                             $ref: '#/components/schemas/Error'
    #                         example:
    #                             success: false
    #                             statusCode: 401
    #                             statusMessage: 'The leaving dates endpoint is only available with paid plans.'

    /changes/new_titles:
        get:
            operationId: getNewTitles
            summary: Get newly added titles
            description: |
                Get title IDs of new movies and shows added to Watchmode within a date range.
                Useful for keeping your database in sync with Watchmode.

                **Note:** This endpoint requires a paid plan.
            tags:
                - Changes
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/changes/new_titles?types=movie,tv_series'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get newly added titles (paid plans only)
                      const { data } = await client.changes.getNewTitles({
                        startDate: 20240101,
                        endDate: 20240107,
                        types: 'movie,tv_series',
                        page: 1,
                        limit: 250
                      });
                      console.log(data);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const types = 'movie,tv_series';
                      const url = `https://api.watchmode.com/v1/changes/new_titles?apiKey=${apiKey}&types=${types}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      url = "https://api.watchmode.com/v1/changes/new_titles?apiKey=YOUR_API_KEY&types=movie,tv_series"

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/changes/new_titles?apiKey=YOUR_API_KEY&types=movie,tv_series')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, 'https://api.watchmode.com/v1/changes/new_titles?apiKey=YOUR_API_KEY&types=movie,tv_series');
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/startDate'
                - $ref: '#/components/parameters/endDate'
                - $ref: '#/components/parameters/titleTypes'
                - $ref: '#/components/parameters/page'
                - $ref: '#/components/parameters/changesLimit'
            responses:
                '200':
                    description: List of new title IDs
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ChangesResponse'
                            example:
                                titles:
                                    - 1138
                                    - 1668
                                    - 1867
                                    - 11029
                                    - 11045
                                page: 1
                                total_results: 6513
                                total_pages: 27
                '401':
                    $ref: '#/components/responses/PaidPlanRequired'

    /changes/new_people:
        get:
            operationId: getNewPeople
            summary: Get newly added people
            description: |
                Get IDs of new people (actors, directors, etc.) added to Watchmode within a date range.

                **Note:** This endpoint requires a paid plan.
            tags:
                - Changes
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/changes/new_people/'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get newly added people (paid plans only)
                      const { data } = await client.changes.getNewPeople({
                        startDate: 20240101,
                        endDate: 20240107
                      });
                      console.log(data);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const url = `https://api.watchmode.com/v1/changes/new_people/?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      url = "https://api.watchmode.com/v1/changes/new_people/?apiKey=YOUR_API_KEY"

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/changes/new_people/?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, 'https://api.watchmode.com/v1/changes/new_people/?apiKey=YOUR_API_KEY');
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/startDate'
                - $ref: '#/components/parameters/endDate'
                - $ref: '#/components/parameters/page'
                - $ref: '#/components/parameters/changesLimit'
            responses:
                '200':
                    description: List of new person IDs
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PeopleChangesResponse'
                            example:
                                people:
                                    - 710203130
                                    - 73333445
                                    - 710203131
                                page: 1
                                total_results: 15113
                                total_pages: 61
                '401':
                    $ref: '#/components/responses/PaidPlanRequired'

    /changes/titles_sources_changed:
        get:
            operationId: getTitlesSourcesChanged
            summary: Get titles with changed sources
            description: |
                Get title IDs where streaming availability has changed within a date range.
                Use this to know which titles need their sources refreshed.
                When multiple regions are requested, a title is returned if its sources changed in any requested region.

                For Australian availability, use `regions=AU`; omitting regions defaults to US.
                Example daily window: `/v1/changes/titles_sources_changed/?regions=AU&start_date=20260907000000&end_date=20260907235959&limit=250&page=1`.
                Dates use the documented Pacific-time convention. Fetch every page through `total_pages`.
                Keep a small overlap between polling windows and deduplicate title IDs.

                **Note:** This endpoint requires a paid plan.
            tags:
                - Changes
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/changes/titles_sources_changed?regions=US,FR,ES'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get titles where streaming sources changed (paid plans only)
                      const { data } = await client.changes.getTitlesSourcesChanged({
                        startDate: 20240101,
                        endDate: 20240107,
                        regions: 'US,FR,ES'
                      });
                      console.log(data);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const url = `https://api.watchmode.com/v1/changes/titles_sources_changed?apiKey=${apiKey}&regions=US,FR,ES`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      url = "https://api.watchmode.com/v1/changes/titles_sources_changed?apiKey=YOUR_API_KEY&regions=US,FR,ES"

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/changes/titles_sources_changed?apiKey=YOUR_API_KEY&regions=US,FR,ES')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, 'https://api.watchmode.com/v1/changes/titles_sources_changed?apiKey=YOUR_API_KEY&regions=US,FR,ES');
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/startDate'
                - $ref: '#/components/parameters/endDate'
                - $ref: '#/components/parameters/titleTypes'
                - name: regions
                  in: query
                  description: Filter by up to 10 unique 2-letter region codes, comma-separated. Requested regions must be enabled for your plan. Defaults to `US` when omitted. Wildcards such as `*` are not supported.
                  schema:
                      type: string
                      default: US
                      example: 'US,FR,ES'
                - $ref: '#/components/parameters/page'
                - $ref: '#/components/parameters/changesLimit'
            responses:
                '200':
                    description: List of title IDs with changed sources
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ChangesResponse'
                            example:
                                titles:
                                    - 12490
                                    - 115801
                                    - 144030
                                page: 1
                                total_results: 488
                                total_pages: 2
                '401':
                    $ref: '#/components/responses/PaidPlanRequired'

    /changes/titles_details_changed:
        get:
            operationId: getTitlesDetailsChanged
            summary: Get titles with changed details
            description: |
                Get title IDs where metadata has changed (overview, cast, genres, ratings, etc.) within a date range.

                Call `/v1/changes/titles_details_changed/`, not the bare `/v1/changes/` path.
                Example daily window: `/v1/changes/titles_details_changed/?start_date=20260907000000&end_date=20260907235959&limit=250&page=1`.
                Fetch every page through `total_pages` and intersect the title IDs with your catalog.
                Details changes are not filtered by region. Use `titles_sources_changed` with `regions=AU` for Australian availability.
                Date-only end values stop at midnight; use an explicit end timestamp to include the full day.

                **Note:** This endpoint requires a paid plan.
            tags:
                - Changes
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/changes/titles_details_changed'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get titles where details changed (paid plans only)
                      const { data } = await client.changes.getTitlesDetailsChanged({
                        startDate: 20240101,
                        endDate: 20240107
                      });
                      console.log(data);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const url = `https://api.watchmode.com/v1/changes/titles_details_changed?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      url = "https://api.watchmode.com/v1/changes/titles_details_changed?apiKey=YOUR_API_KEY"

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/changes/titles_details_changed?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, 'https://api.watchmode.com/v1/changes/titles_details_changed?apiKey=YOUR_API_KEY');
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/startDate'
                - $ref: '#/components/parameters/endDate'
                - $ref: '#/components/parameters/titleTypes'
                - $ref: '#/components/parameters/page'
                - $ref: '#/components/parameters/changesLimit'
            responses:
                '200':
                    description: List of title IDs with changed details
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ChangesResponse'
                            example:
                                titles:
                                    - 3171655
                                    - 3127447
                                    - 3146794
                                page: 1
                                total_results: 14
                                total_pages: 1
                '401':
                    $ref: '#/components/responses/PaidPlanRequired'

    /changes/titles_episodes_changed:
        get:
            operationId: getTitlesEpisodesChanged
            summary: Get titles with changed episodes
            description: |
                Get title IDs where episode data has changed (new episodes, updated details) within a date range.

                **Note:** This endpoint requires a paid plan.
            tags:
                - Changes
            x-codeSamples:
                - lang: Shell
                  source: |
                      curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/changes/titles_episodes_changed'
                - lang: TypeScript
                  label: TypeScript SDK
                  source: |
                      // npm install @watchmode/api-client
                      import { WatchmodeClient } from '@watchmode/api-client';

                      const client = new WatchmodeClient({ apiKey: 'YOUR_API_KEY' });

                      // Get titles where episodes changed (paid plans only)
                      const { data } = await client.changes.getTitlesEpisodesChanged({
                        startDate: 20240101,
                        endDate: 20240107
                      });
                      console.log(data);
                - lang: JavaScript
                  source: |
                      const apiKey = 'YOUR_API_KEY';
                      const url = `https://api.watchmode.com/v1/changes/titles_episodes_changed?apiKey=${apiKey}`;

                      const response = await fetch(url);
                      const json = await response.json();
                      console.log(json);
                - lang: Python
                  source: |
                      import urllib.request
                      import json

                      url = "https://api.watchmode.com/v1/changes/titles_episodes_changed?apiKey=YOUR_API_KEY"

                      with urllib.request.urlopen(url) as response:
                          data = json.loads(response.read().decode())
                          print(data)
                - lang: Ruby
                  source: |
                      require 'net/http'
                      require 'uri'
                      require 'json'

                      uri = URI('https://api.watchmode.com/v1/changes/titles_episodes_changed?apiKey=YOUR_API_KEY')
                      json = Net::HTTP.get(uri)
                      result = JSON(json)
                      print(result)
                - lang: PHP
                  source: |
                      <?php
                      $ch = curl_init();
                      curl_setopt($ch, CURLOPT_URL, 'https://api.watchmode.com/v1/changes/titles_episodes_changed?apiKey=YOUR_API_KEY');
                      curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                      curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
                      $response = curl_exec($ch);
                      curl_close($ch);

                      $json = json_decode($response);
                      print_r($json);
            parameters:
                - $ref: '#/components/parameters/startDate'
                - $ref: '#/components/parameters/endDate'
                - $ref: '#/components/parameters/page'
                - $ref: '#/components/parameters/changesLimit'
            responses:
                '200':
                    description: List of title IDs with changed episodes
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ChangesResponse'
                            example:
                                titles:
                                    - 3123402
                                    - 3165766
                                    - 3107530
                                page: 1
                                total_results: 130
                                total_pages: 1
                '401':
                    $ref: '#/components/responses/PaidPlanRequired'

    /live-channels:
        get:
            operationId: getLiveGuideChannels
            summary: List TV channels
            tags:
                - Live TV, Sports & Events (Beta)
            description: |-
                List the US TV channels with stored guide listings. Requires beta access and a Business or Enterprise plan.
                Costs 1 credit. Each channel has its own ID, name, timezone, and available listing dates.
                Use these IDs with `channel_ids` on `/live-airings` to build a TV guide.
                Confirmed duplicates share one channel ID across guide listings, event broadcasts, and recorded
                streaming-service package options. Local stations and East/West versions keep separate IDs when present.
                Available dates describe stored observations, including past listings. This is not a promise of current
                coverage on every channel. Compare these dates with your requested window and check `/live-airings` coverage.
                During beta, refresh this directory when channel IDs change and start a new guide download.
                Omit `channel_ids` to return all channels, or select up to 30 channels in one request.

                This list does not tell you which channels are included with Fubo, Hulu, Sling TV, or other services.
                `service_channel_lists_available` is currently false. Some channel names or other details may be missing;
                `metadata_status` tells you whether we found the channel's details.
            parameters:
                -   name: region
                    in: query
                    schema:
                        type: string
                        enum:
                            - US
                    description: Two-letter country code for viewing availability, such as US. Defaults to US. Must be available
                        to your account.
                -   name: channel_ids
                    in: query
                    description: Optional comma-separated channel IDs from /live-channels. Select up to 30 channels, or omit
                        for all channels.
                    schema:
                        type: string
            responses:
                '200':
                    description: TV channels with available listing dates.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LivePublicGuideChannels'
                '400':
                    description: Invalid or unsupported filters.
                '403':
                    description: Your account needs beta access, a higher plan, or access to the requested data. The response
                        explains the restriction.
            x-codeSamples:
                -   lang: Shell
                    source: 'curl -H ''X-API-Key: YOUR_API_KEY'' ''https://api.watchmode.com/v1/live-channels/'''

    /live-airings:
        get:
            operationId: getLiveGuideAirings
            summary: Get TV listings
            tags:
                - Live TV, Sports & Events (Beta)
            description: |-
                Get scheduled TV programs for US channels, including programs that started before your chosen time
                and are still airing. Requires beta access and a Business or Enterprise plan. Costs 1 credit per page.
                Choose a time range of up to 48 hours. Use `channel_ids` to select up to 30 channels, or omit it for all channels.
                Each page contains up to 500 listings and 1 MiB of data.

                To get the next page, send the returned `next_cursor` as `continuation`, with your API key and no other
                parameters. Stop when `next_cursor` is null. The results stay unchanged while you download all pages.
                Finish within 10 minutes. A download can contain up to 10,000 listings and 20 MiB; if it is too large,
                select fewer channels or a shorter time range. Sports and TV downloads share a limit of 16 saved downloads
                and 64 MiB per account. Repeated and empty successful pages still cost 1 credit each.

                The `coverage` array identifies missing time periods, overlapping listings, outdated records, and unknown
                end times for each channel. Listings with no end time are returned only when they start inside your requested range; they are not
                confirmed to be airing now. For a linear channel, the newest observation wins when listings share a start time. The available
                date ranges may contain gaps. `update_status: unverified` means we cannot confirm a complete guide update.
                `safe_to_replace: false` means you should keep previously saved listings when a result is empty or incomplete.
                The daily guide currently treats observations older than 36 hours as stale. Recent observations can still
                have gaps or overlaps; freshness does not prove completeness. Local station coverage and program details
                such as images, episode descriptions, and channel numbers are not currently available in this guide.

                Filters for streaming services, subscription packages, titles, ZIP codes, or now/next are not supported yet.
                You can build a now/next view from listings with known start and end times, while accounting for gaps.
            parameters:
                -   name: region
                    in: query
                    schema:
                        type: string
                        enum:
                            - US
                    description: Two-letter country code for viewing availability, such as US. Defaults to US. Must be available
                        to your account.
                -   name: channel_ids
                    in: query
                    schema:
                        type: string
                    description: Optional comma-separated channel IDs from /live-channels. Select up to 30 channels, or omit
                        for all channels.
                -   name: date_from
                    in: query
                    description: Start of the requested time range. Use an ISO 8601 date/time including Z for UTC or a timezone
                        offset. Required for the first page; choose a range of up to 48 hours.
                    schema:
                        type: string
                        format: date-time
                -   name: date_to
                    in: query
                    description: End of the requested time range, not included in the results. Use an ISO 8601 date/time
                        including Z for UTC or a timezone offset. Required for the first page; choose a range of up to 48
                        hours.
                    schema:
                        type: string
                        format: date-time
                -   name: continuation
                    in: query
                    schema:
                        type: string
                        maxLength: 512
                    description: For the next page, copy next_cursor from the previous response here. Send only this parameter
                        and your API key.
            responses:
                '200':
                    description: A page of TV listings, plus information about missing or outdated listings.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LivePublicGuidePage'
                '400':
                    description: Invalid filters, request interval longer than 48 hours or more than 10000 airings; narrow
                        the query.
                '403':
                    description: Your account needs beta access, a higher plan, or access to the requested data. The response
                        explains the restriction.
                '409':
                    description: Your access changed or this page token belongs to another endpoint. Start a new download.
                '410':
                    description: This download expired or is unavailable to your account. Start a new download.
                '413':
                    description: The result is too large. Select fewer channels or leagues, or a shorter time range.
                '429':
                    description: Monthly credits, request-rate limits, or saved-download limits were reached.
            x-codeSamples:
                -   lang: Shell
                    source: 'curl -H ''X-API-Key: YOUR_API_KEY'' ''https://api.watchmode.com/v1/live-airings/?date_from=2026-09-10T00:00:00Z&date_to=2026-09-12T00:00:00Z'''

    /live-coverage:
        get:
            operationId: getLiveCoverage
            summary: Check your Live API access
            description: |-
                See which countries, leagues, event dates, and TV channels your account can access.
                Requires beta access. Costs 0 credits, even when you have used your monthly allowance; normal request-rate
                limits still apply. Business and Enterprise also receive available channel date ranges.

                These ranges describe available data and your plan's limits. They do not promise a listing for every
                program or event, or that the information is current. `access_level` describes your Live features:
                Enterprise has the same `business` feature level. Changes-only downloads are not available yet.
            tags:
                - Live TV, Sports & Events (Beta)
            responses:
                '200':
                    description: The Live data and features available to your account.
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - beta
                                    - account_revision
                                    - release_revision
                                    - access_level
                                    - available_event_ranges
                                    - sample_event_ids
                                    - data_freshness
                                    - guide_available
                                    - incremental_sync_available
                                properties:
                                    beta:
                                        type: boolean
                                        enum:
                                            - true
                                    account_revision:
                                        type: integer
                                        description: Version of your beta access settings. Changes can require restarting
                                            a download.
                                    release_revision:
                                        type: integer
                                        description: Version of the shared Live access settings. Changes can require restarting
                                            a download.
                                    access_level:
                                        type: string
                                        enum:
                                            - free
                                            - startup
                                            - business
                                        description: Live feature level. Enterprise uses business features; this field is
                                            not the name of your billing plan.
                                    available_event_ranges:
                                        type: array
                                        items:
                                            type: object
                                            required:
                                                - region
                                                - league_id
                                                - date_from
                                                - date_to
                                                - streaming_options_available
                                                - location_filter_available
                                            properties:
                                                region:
                                                    type: string
                                                    enum:
                                                        - US
                                                        - GB
                                                        - CA
                                                        - AU
                                                league_id:
                                                    type: integer
                                                date_from:
                                                    type: string
                                                    format: date-time
                                                    description: Beginning of the available or requested range. A range may
                                                        contain missing listings.
                                                date_to:
                                                    type: string
                                                    format: date-time
                                                    description: End of the available or requested range, excluded from the
                                                        interval. A range may contain missing listings.
                                                streaming_options_available:
                                                    type: boolean
                                                    description: Whether your account can request where-to-watch options
                                                        for this country and league. Individual events may still have no
                                                        known options.
                                                location_filter_available:
                                                    type: boolean
                                                    description: Whether your account can filter viewing options by US TV
                                                        market for this country and league.
                                        description: Countries, leagues, and event start-time ranges available to your account.
                                            Dates may contain gaps.
                                    sample_event_ids:
                                        type: array
                                        nullable: true
                                        maxItems: 25
                                        items:
                                            type: integer
                                        description: Free sample event IDs. Null for paid plans; an empty array grants no
                                            sample events.
                                    data_freshness:
                                        type: string
                                        enum:
                                            - not_measured
                                        description: Overall freshness has not been measured. Check individual last_seen_at
                                            timestamps and coverage information.
                                    guide_available:
                                        type: boolean
                                        description: Whether your account can use the TV guide and channels currently have
                                            listings.
                                    available_channel_ranges:
                                        type: array
                                        items:
                                            type: object
                                            required:
                                                - channel_id
                                                - region
                                                - date_from
                                                - date_to
                                            properties:
                                                channel_id:
                                                    type: integer
                                                    description: ID of this specific TV channel or local station. Use it
                                                        with channel_ids on the guide endpoints.
                                                region:
                                                    type: string
                                                    enum:
                                                        - US
                                                date_from:
                                                    type: string
                                                    format: date-time
                                                    description: Beginning of the available or requested range. A range may
                                                        contain missing listings.
                                                date_to:
                                                    type: string
                                                    format: date-time
                                                    description: End of the available or requested range, excluded from the
                                                        interval. A range may contain missing listings.
                                        description: Channels and listing date ranges available to your account. Dates may
                                            contain gaps.
                                    guide_update_status:
                                        type: string
                                        enum:
                                            - unverified
                                        description: Whether a complete guide update has been verified. Currently unverified.
                                    incremental_sync_available:
                                        type: boolean
                                        enum:
                                            - false
                                        description: Whether you can download only changes since a previous request. Currently
                                            false; request the dates you need again.
                '403':
                    description: Your account needs beta access, a higher plan, or access to the requested data. The response
                        explains the restriction.
                '503':
                    description: Live data is temporarily unavailable.
            x-codeSamples:
                -   lang: Shell
                    source: 'curl -H ''X-API-Key: YOUR_API_KEY'' ''https://api.watchmode.com/v1/live-coverage/'''

    /live-leagues:
        get:
            operationId: getLiveLeagues
            summary: List sports leagues and award series
            description: |-
                List the sports leagues and award series available to your account. Award series, such as the Oscars,
                have `event_type: awards`. Use these IDs to filter events. Requires beta access. Costs 1 credit.
                Returns all matching available leagues in one response with `total_results`; this endpoint is not paginated.
                A league may be a tour, tournament, or ceremony series. Use `sport` and the ID to distinguish similar names.
                `country` describes the league's country when known, not where an event can be watched; it may be null.
                Use `region` on event requests to choose the viewer's country. `level` and `gender` can be unknown.
            tags:
                - Live TV, Sports & Events (Beta)
            parameters:
                -   name: types
                    in: query
                    description: 'Comma-separated event types: sport, awards.'
                    schema:
                        type: string
                        example: sport
                -   name: sport
                    in: query
                    description: Filter by the sport value returned by /live-leagues.
                    schema:
                        type: string
                -   name: country
                    in: query
                    description: Filter by the league's known 2-letter country code. Leagues with unknown country are excluded.
                    schema:
                        type: string
                        example: US
            x-codeSamples:
                -   lang: Shell
                    source: |
                        curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/live-leagues/?types=sport'
            responses:
                '200':
                    description: List of leagues.
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [leagues, total_results]
                                properties:
                                    total_results:
                                        type: integer
                                    leagues:
                                        type: array
                                        items:
                                            type: object
                                            required: [id, name, abbreviation, sport, event_type, country, level, gender]
                                            properties:
                                                id:
                                                    type: integer
                                                name:
                                                    type: string
                                                abbreviation:
                                                    type: string
                                                    nullable: true
                                                sport:
                                                    type: string
                                                    nullable: true
                                                event_type:
                                                    type: string
                                                    enum: [sport, awards]
                                                country:
                                                    type: string
                                                    nullable: true
                                                level:
                                                    type: string
                                                    nullable: true
                                                gender:
                                                    type: string
                                                    nullable: true

    /live-teams:
        get:
            operationId: getLiveTeams
            summary: List sports teams
            description: |-
                Find sports teams by league or name. Returns teams from leagues available to your account.
                Each team includes its ID, name, and logo URL; `logo_url` is null when no logo is available.
                Requires beta access. Costs 1 credit per page.
                During beta, a team may have separate records across competitions or data providers. Use the returned
                IDs in event filters; do not merge teams solely by name. Names, abbreviations and logos may be incomplete.
            tags:
                - Live TV, Sports & Events (Beta)
            parameters:
                -   name: league_id
                    in: query
                    description: A league ID from /live-leagues. Do not combine with league_ids when both filters are offered.
                    schema:
                        type: integer
                -   name: search
                    in: query
                    description: Match text anywhere in the name, ignoring capitalization. At least 2 characters.
                    schema:
                        type: string
                -   name: page
                    in: query
                    schema:
                        type: integer
                        default: 1
                -   name: limit
                    in: query
                    description: Results per page. Must be 1–250; values above 250 return 400. Values above your plan cap are reduced to 25 free / 100 Startup / 250 Business or Enterprise.
                    schema:
                        type: integer
                        default: 100
            x-codeSamples:
                -   lang: Shell
                    source: |
                        curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/live-teams/?search=lakers'
            responses:
                '200':
                    description: Paged list of teams.
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [teams, total_results, page, total_pages]
                                properties:
                                    total_results:
                                        type: integer
                                    page:
                                        type: integer
                                    total_pages:
                                        type: integer
                                    teams:
                                        type: array
                                        items:
                                            type: object
                                            required: [id, league_id, name, short_name, abbreviation, city, nickname, logo_url]
                                            properties:
                                                id:
                                                    type: integer
                                                league_id:
                                                    type: integer
                                                    nullable: true
                                                name:
                                                    type: string
                                                short_name:
                                                    type: string
                                                    nullable: true
                                                abbreviation:
                                                    type: string
                                                    nullable: true
                                                city:
                                                    type: string
                                                    nullable: true
                                                nickname:
                                                    type: string
                                                    nullable: true
                                                logo_url:
                                                    type: string
                                                    nullable: true

    /live-events:
        get:
            operationId: getLiveEvents
            summary: Find sports and awards events
            description: |-
                Find upcoming or recent sports games and award ceremonies. Results include the event name, teams,
                start time, status, and TV networks. Set `include_sources=true` to also get where-to-watch options.
                Events remain in results when their viewing options are unknown.

                Requires beta access. Free accounts receive the shared sample of up to 25 events. Startup can access
                the past 7 days and next 7 days in all supported countries. Business and Enterprise can access all
                available dates. Check `/live-coverage` for your available ranges. Country and league filters are chosen
                per request; there are no saved account selections. If Startup requests dates too far ahead, the end
                time is shortened and `date_range_limited` is true. A start time beyond that limit returns an error.

                Costs 1 credit per page for event details, or 2 credits when using `provider_ids` or `has_sources=true`.
                With `include_sources=true`, the cost is 1 credit plus 1 per returned event, with no additional filter
                charge. An empty page with viewing options costs 1 credit. Free accounts can include viewing options
                for their sample events; provider and availability filters require Startup or higher.

                ID filters accept up to 100 comma-separated IDs. An event can match any ID within one filter, but must
                match every different filter you supply. Provider filters also limit the returned viewing options to
                those providers. Search matches text anywhere in event, league, and team names (including team short names), ignoring capitalization.
                Unknown parameters and invalid values return an error.

                Use the same explicit dates on every page. Results can change between page requests as events are added
                or rescheduled. For a download whose pages stay unchanged, use `/live-schedule`.
            tags:
                - Live TV, Sports & Events (Beta)
            parameters:
                -   name: event_ids
                    in: query
                    description: Up to 100 comma-separated event IDs. Only events matching your dates and account access
                        are returned.
                    schema:
                        type: string
                -   name: provider_ids
                    in: query
                    description: Startup or higher. Up to 100 comma-separated provider IDs. Returns events with a known viewing
                        option on any listed provider in your chosen country.
                    schema:
                        type: string
                -   name: search
                    in: query
                    description: Match text anywhere in event, league, or team names, ignoring capitalization. At least 2 characters. Maximum
                        120 characters.
                    schema:
                        type: string
                        minLength: 2
                        maxLength: 120
                -   name: has_sources
                    in: query
                    description: Startup or higher. Set true to return only events with known viewing options in your chosen
                        country. False does not filter events.
                    schema:
                        type: boolean
                -   name: include_sources
                    in: query
                    description: Include where-to-watch options in sources. Costs 1 credit plus 1 per returned event. sources_state
                        explains missing or outdated options.
                    schema:
                        type: boolean
                -   name: types
                    in: query
                    description: 'Comma-separated event types: sport, awards.'
                    schema:
                        type: string
                -   name: league_ids
                    in: query
                    description: Optional comma-separated league IDs from /live-leagues (up to 100).
                    schema:
                        type: string
                        example: 13279,13281
                -   name: team_ids
                    in: query
                    description: Comma-separated team ids — matches home or away.
                    schema:
                        type: string
                -   name: sport
                    in: query
                    description: Filter by the sport value returned by /live-leagues.
                    schema:
                        type: string
                -   name: region
                    in: query
                    description: Two-letter country code for viewing availability, such as US. Defaults to US. Must be available
                        to your account.
                    schema:
                        type: string
                        default: US
                -   name: date_from
                    in: query
                    description: Start of the requested time range. Use an ISO 8601 date/time including Z for UTC or a timezone
                        offset. A date alone is also accepted. Defaults to now (7 days ago when /live-events status includes
                        live).
                    schema:
                        type: string
                        example: '2026-09-01'
                -   name: date_to
                    in: query
                    description: End of the requested time range, not included in the results. Use an ISO 8601 date/time
                        including Z for UTC or a timezone offset. A date alone is also accepted. Defaults to 7 days after
                        the start. Startup event lists are shortened to the next 7 days.
                    schema:
                        type: string
                -   name: status
                    in: query
                    description: Comma-separated statuses — `scheduled`, `live`, `final`, `postponed`, `cancelled`, `unknown`. Unknown does not mean live.
                    schema:
                        type: string
                -   name: page
                    in: query
                    schema:
                        type: integer
                        default: 1
                -   name: limit
                    in: query
                    description: Results per page. Must be 1–250; values above 250 return 400. Values above your plan cap are reduced to 25 free / 100 Startup / 250 Business or Enterprise.
                    schema:
                        type: integer
                        default: 25
            x-codeSamples:
                -   lang: Shell
                    source: |
                        curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/live-events/?types=sport&region=US&date_from=2026-09-10&date_to=2026-09-14'
            responses:
                '200':
                    description: Events with optional where-to-watch options.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LivePublicEventsResponse'

    /live-event/{id}:
        get:
            operationId: getLiveEvent
            summary: Get event details
            description: |-
                Get one event's name, league, teams, start time, status, venue, and TV broadcasts for the requested country.
                Requires beta access. Costs 1 credit. The same plan and date limits apply as on `/live-events`.
                An unknown event or one outside your account's access returns 404.

                Viewing options are not included here (`sources_state: not_requested`). Use `/live-event/{id}/sources`
                to find where to watch. Event IDs are separate from movie and TV title IDs.
            tags:
                - Live TV, Sports & Events (Beta)
            parameters:
                -   name: region
                    in: query
                    description: Two-letter country code for viewing availability, such as US. Defaults to US. Must be available
                        to your account.
                    schema:
                        type: string
                        default: US
                -   name: id
                    in: path
                    required: true
                    description: Live event id (a distinct id namespace from title ids).
                    schema:
                        type: integer
            x-codeSamples:
                -   lang: Shell
                    source: |
                        curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/live-event/69647/'
            responses:
                '200':
                    description: Event details and TV broadcasts; viewing options are not included.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LivePublicEvent'
                '404':
                    description: Unknown event id.

    /live-event/{id}/sources:
        get:
            operationId: getLiveEventSources
            summary: Find where to watch an event
            description: |-
                Find services and links for watching an event in one or more countries. Requires beta access.
                Free accounts can request their sample events. Costs 2 credits per requested country.
                The `sources` objects have the same format as viewing options in event lists and event downloads.
                If a requested country is unavailable to your account, the entire request is rejected without charging.

                A viewing option is not a guarantee that a particular person can play the event. Check subscription and
                location requirements. Without a `dma` filter, local and national options may both appear. Where enabled,
                Business and Enterprise can filter US options by a three-digit TV market code (`dma`). This narrows
                location matches but does not verify the viewer's subscription. ZIP-code lookup is not supported yet.

                Check each link's type: it may open a service homepage, channel page, event page, game finder, player,
                or signup page. A null link means we have no suitable URL. Empty options mean availability is unknown.
                `affiliate: true` identifies a known affiliate link. A separate non-affiliate URL is not currently provided.
                Repeated equivalent viewing options may be combined, while recorded channel/package pairs and market
                restrictions remain distinct. A broadcast identifies coverage; it does not prove that we have a matching
                streaming-service option. Do not infer subscription access from a broadcast alone.
                Link checks describe whether the page responded, not whether playback works.

                `channel_package_options` contains known channel/package combinations for this viewing option. Use
                these combinations together; separate `channel_ids` and `package_ids` lists do not imply every possible
                pairing. A match to a network does not identify a particular local station or East/West channel version.
                A source's link is not necessarily specific to each listed package. Missing package details mean unknown;
                these results are not a complete list of a service's channels or packages.
            tags:
                - Live TV, Sports & Events (Beta)
            parameters:
                -   name: id
                    in: path
                    required: true
                    schema:
                        type: integer
                -   name: regions
                    in: query
                    description: 'Comma-separated country codes: US, GB, CA, AU. Defaults to US. Each distinct country costs
                        2 credits.'
                    schema:
                        type: string
                        example: US
                -   name: dma
                    in: query
                    description: Optional three-digit US TV market code (Nielsen DMA), such as 803 for Los Angeles. Requires
                        Business or Enterprise and location filtering enabled for the requested events. US requests only.
                    schema:
                        type: string
                        example: '803'
            x-codeSamples:
                -   lang: Shell
                    source: |
                        curl -i -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/live-event/69647/sources/?regions=US'
            responses:
                '200':
                    description: Where-to-watch options and their availability by country.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LivePublicSourcesResponse'
                '403':
                    description: Your account needs beta access, a higher plan, or access to the requested data. The response
                        explains the restriction.
                '404':
                    description: Unknown event id.

    /live-schedule:
        get:
            operationId: getLiveSchedule
            summary: Download events and where to watch them
            description: |-
                Download events and their where-to-watch options for one country and up to 7 days at a time.
                Requires beta access and a Business or Enterprise plan. Omit league filters for all available leagues,
                or select leagues with `league_id` or `league_ids`. Events with unknown viewing options are still included.

                Each page costs 10 credits and contains up to 250 events and 1 MiB. Results stay unchanged while you
                download all pages, even if an event is updated. Send the returned `next_cursor` as `continuation`,
                with your API key and no other parameters. Continue until `next_cursor` is null. Repeated and empty
                successful pages also cost 10 credits. Download all pages before updating your saved event collection.
                The counts describe this download; they do not guarantee that every real event has been discovered.

                Finish within 10 minutes. If the download expires or your access changes, start again and keep your
                previous data until the new download finishes. A download can contain up to 10,000 events and 20 MiB.
                Larger downloads return an error; try fewer leagues or a shorter date range. If one event exceeds the
                page-size limit, the request also returns an error. Each account can keep up to 16 downloads and 64 MiB
                across sports and TV listings. This limit is shared by all of the account's API keys.
            tags:
                - Live TV, Sports & Events (Beta)
            parameters:
                -   name: continuation
                    in: query
                    description: For the next page, copy next_cursor from the previous response here. Send only this parameter
                        and your API key.
                    schema:
                        type: string
                        maxLength: 512
                -   name: league_id
                    in: query
                    description: A league ID from /live-leagues. Do not combine with league_ids when both filters are offered.
                    schema:
                        type: integer
                        minimum: 1
                -   name: league_ids
                    in: query
                    description: Optional comma-separated league IDs from /live-leagues (up to 100).
                    schema:
                        type: string
                -   name: region
                    in: query
                    description: Two-letter country code for viewing availability, such as US. Defaults to US. Must be available
                        to your account.
                    schema:
                        type: string
                        default: US
                -   name: date_from
                    in: query
                    description: Start time for the download. ISO 8601 date or date/time with timezone. Defaults to now.
                    schema:
                        type: string
                -   name: date_to
                    in: query
                    description: End time for the download, excluded from the results. Defaults to 7 days after date_from.
                        Longer ranges are rejected.
                    schema:
                        type: string
                -   name: dma
                    in: query
                    description: Optional three-digit US TV market code (Nielsen DMA), such as 803 for Los Angeles. Requires
                        Business or Enterprise and location filtering enabled for the requested events. US requests only.
                    schema:
                        type: string
            x-codeSamples:
                -   lang: Shell
                    source: |
                        curl -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/live-schedule/?region=US&date_from=2026-09-07&date_to=2026-09-14'
                        # Follow the returned next_cursor with authentication and no new filters.
                        curl -H 'X-API-Key: YOUR_API_KEY' 'https://api.watchmode.com/v1/live-schedule/?continuation=NEXT_CURSOR'
            responses:
                '200':
                    description: A page of events and viewing options. Continue until next_cursor is null.
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - region
                                    - league_ids
                                    - market
                                    - date_from
                                    - effective_date_to
                                    - window_limited
                                    - snapshot_id
                                    - expires_at
                                    - page
                                    - total_pages
                                    - total_results
                                    - event_count
                                    - has_more
                                    - next_cursor
                                    - events
                                properties:
                                    region:
                                        type: string
                                    league_ids:
                                        type: array
                                        nullable: true
                                        items:
                                            type: integer
                                    market:
                                        type: object
                                        nullable: true
                                        properties:
                                            dma:
                                                type: string
                                                description: Three-digit US TV market code (Nielsen DMA), when known. Identifies
                                                    a viewing area, not a country.
                                            resolved_from:
                                                type: string
                                                enum:
                                                    - dma
                                                    - postal_code
                                    date_from:
                                        type: string
                                        format: date-time
                                        description: Beginning of the available or requested range. A range may contain missing
                                            listings.
                                    effective_date_to:
                                        type: string
                                        format: date-time
                                        description: End time used for the query, after any plan limit. Your account access
                                            may restrict the returned data further.
                                    window_limited:
                                        type: boolean
                                        enum:
                                            - false
                                        description: 'Always false for event downloads: date ranges longer than 7 days are
                                            rejected, not shortened.'
                                    snapshot_id:
                                        type: string
                                        format: uuid
                                        description: ID of this saved download. It stays the same across all pages; use it
                                            to check that pages belong together.
                                    expires_at:
                                        type: string
                                        format: date-time
                                        description: Expiry time. On a download, finish fetching its pages before this time.
                                            On a viewing option, this is the recorded availability expiry.
                                    page:
                                        type: integer
                                        minimum: 1
                                    total_pages:
                                        type: integer
                                        minimum: 1
                                    total_results:
                                        type: integer
                                        minimum: 0
                                        description: Total matching records, across all pages.
                                    event_count:
                                        type: integer
                                        minimum: 0
                                        maximum: 250
                                        description: Number of events on this page.
                                    has_more:
                                        type: boolean
                                        description: True when another page remains in this download.
                                    next_cursor:
                                        type: string
                                        nullable: true
                                        description: Token for the next page. Send it as continuation with your API key and
                                            no other parameters. Null means the download is complete.
                                    events:
                                        type: array
                                        maxItems: 250
                                        items:
                                            $ref: '#/components/schemas/LivePublicEvent'
                '400':
                    description: Invalid dates, query window, cursor or conflicting filters.
                '403':
                    description: Your account needs beta access, a higher plan, or access to the requested data. The response
                        explains the restriction.
                '409':
                    description: Your access changed or this page token belongs to another endpoint. Start a new download.
                '410':
                    description: This download expired or is unavailable to your account. Start a new download.
                '413':
                    description: The result is too large. Select fewer channels or leagues, or a shorter time range.
                '429':
                    description: Monthly credits, request-rate limits, or saved-download limits were reached.

components:
    securitySchemes:
        apiKey:
            type: apiKey
            in: header
            name: X-API-Key
            description: Recommended authentication method. Send your Watchmode API key in the X-API-Key header.
        bearerAuth:
            type: http
            scheme: bearer
            description: 'Alternative header authentication using Authorization: Bearer YOUR_API_KEY.'
        apiKeyQuery:
            type: apiKey
            in: query
            name: apiKey
            description: Legacy query-parameter authentication. Supported for backwards compatibility; prefer X-API-Key for new integrations.

    parameters:
        titleId:
            name: title_id
            in: path
            required: true
            description: |
                Title identifier. Accepts:
                - Watchmode ID (e.g., `345534`) - 1 credit
                - IMDB ID (e.g., `tt0903747`) - 2 credits
                - TMDB format (e.g., `movie-278` or `tv-1396`) - 2 credits
            schema:
                type: string
                example: '3173903'

        page:
            name: page
            in: query
            description: Page number for pagination
            schema:
                type: integer
                minimum: 1
                default: 1

        changesLimit:
            name: limit
            in: query
            description: Results per page (1-250)
            schema:
                type: integer
                minimum: 1
                maximum: 250
                default: 250

        startDate:
            name: start_date
            in: query
            description: |
                Get changes after this date (PST timezone).
                Format: `YYYYMMDD` or `YYYYMMDDHHMMSS`
                Default: 1 day ago
            schema:
                type: integer
                example: 20240101

        endDate:
            name: end_date
            in: query
            description: |
                Get changes before this date (PST timezone).
                Format: `YYYYMMDD` or `YYYYMMDDHHMMSS`
                Default: current date
            schema:
                type: integer
                example: 20240131

        titleTypes:
            name: types
            in: query
            description: |
                Filter by title type. Comma-separated.
                Valid types: `movie`, `tv_series`, `tv_movie`, `tv_special`, `tv_miniseries`, `short_film`
            schema:
                type: string
                example: 'movie,tv_series'

    responses:
        Unauthorized:
            description: Invalid or missing API key
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
                    example:
                        success: false
                        statusCode: 401
                        statusMessage: 'Unauthorized'

        BadRequest:
            description: Invalid request parameters
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
                    example:
                        success: false
                        statusCode: 400
                        statusMessage: 'Missing required parameter: search_field'

        NotFound:
            description: Resource not found
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
                    example:
                        success: false
                        statusCode: 404
                        statusMessage: 'Title not found.'

        PaidPlanRequired:
            description: Endpoint requires paid plan
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
                    example:
                        success: false
                        statusCode: 401
                        statusMessage: 'The changes endpoint is only available with paid plans.'

    schemas:
        LivePublicGuideChannels:
            type: object
            additionalProperties: false
            required:
                - region
                - channels
                - total_results
                - beta
                - service_channel_lists_available
            properties:
                region:
                    type: string
                    enum:
                        - US
                beta:
                    type: boolean
                    enum:
                        - true
                service_channel_lists_available:
                    type: boolean
                    enum:
                        - false
                    description: Whether this endpoint can identify which channels each streaming service includes. Currently
                        false; this is a guide channel directory.
                total_results:
                    type: integer
                    description: Total matching records, across all pages.
                channels:
                    type: array
                    items:
                        type: object
                        additionalProperties: false
                        required:
                            - channel_id
                            - name
                            - network_id
                            - timezone
                            - dma
                            - channel_type
                            - region
                            - metadata_status
                            - date_from
                            - date_to
                        properties:
                            channel_id:
                                type: integer
                                description: ID of this specific TV channel or local station. Use it with channel_ids on the
                                    guide endpoints.
                            name:
                                type: string
                                nullable: true
                            network_id:
                                type: integer
                                nullable: true
                                description: ID of the TV network brand. Multiple channels or local stations can belong to one
                                    network.
                            timezone:
                                type: string
                                nullable: true
                                description: IANA timezone for this channel, such as America/New_York, when known. Response timestamps
                                    use UTC.
                            dma:
                                type: string
                                nullable: true
                                description: Three-digit US TV market code (Nielsen DMA), when known. Identifies a viewing area,
                                    not a country.
                            channel_type:
                                type: string
                                nullable: true
                                description: Recorded channel category. May be missing; use name, timezone, and location to distinguish
                                    channel versions.
                            region:
                                type: string
                                enum:
                                    - US
                            metadata_status:
                                type: string
                                enum:
                                    - available
                                    - unavailable
                                description: available means a channel record was found; individual details may still be null.
                                    unavailable means its channel details are missing.
                            date_from:
                                type: string
                                format: date-time
                                description: Beginning of the available or requested range. A range may contain missing listings.
                            date_to:
                                type: string
                                format: date-time
                                description: End of the available or requested range, excluded from the interval. A range may
                                    contain missing listings.
        LivePublicGuideAiring:
            type: object
            additionalProperties: false
            required:
                - id
                - channel_id
                - program_id
                - name
                - program_type
                - start_time
                - end_time
                - is_live
                - is_new
                - is_repeat
                - last_seen_at
            properties:
                id:
                    type: integer
                channel_id:
                    type: integer
                    description: ID of this specific TV channel or local station. Use it with channel_ids on the guide endpoints.
                program_id:
                    type: integer
                    description: ID of the guide program. This is separate from Watchmode movie and TV title IDs.
                name:
                    type: string
                program_type:
                    type: string
                    description: Recorded program category, such as show or movie.
                start_time:
                    type: string
                    format: date-time
                end_time:
                    type: string
                    format: date-time
                    nullable: true
                    description: Scheduled end time. Null means unknown; do not assume the program is currently airing.
                is_live:
                    type: boolean
                    description: Whether the program is a live broadcast. This does not mean it is airing at the time of your
                        request.
                is_new:
                    type: boolean
                    nullable: true
                    description: Whether this showing is marked new; null means unknown.
                is_repeat:
                    type: boolean
                    nullable: true
                    description: Whether this showing is marked as a repeat; null means unknown.
                last_seen_at:
                    type: string
                    format: date-time
                    description: When Watchmode last saw this record in its data source. This does not guarantee it is still
                        correct.
        LivePublicGuidePage:
            type: object
            additionalProperties: false
            required:
                - beta
                - region
                - channel_ids
                - date_from
                - date_to
                - coverage
                - update_status
                - safe_to_replace
                - snapshot_id
                - expires_at
                - page
                - total_pages
                - total_results
                - airing_count
                - has_more
                - next_cursor
                - airings
            properties:
                beta:
                    type: boolean
                    enum:
                        - true
                region:
                    type: string
                    enum:
                        - US
                channel_ids:
                    type: array
                    items:
                        type: integer
                    description: Channel IDs. Returned lists can contain more than 30 IDs; the 30-ID limit applies only to explicit
                        request filters.
                date_from:
                    type: string
                    format: date-time
                    description: Beginning of the available or requested range. A range may contain missing listings.
                date_to:
                    type: string
                    format: date-time
                    description: End of the available or requested range, excluded from the interval. A range may contain missing
                        listings.
                update_status:
                    type: string
                    enum:
                        - unverified
                    description: Whether a complete guide update has been verified. Currently unverified.
                safe_to_replace:
                    type: boolean
                    enum:
                        - false
                    description: 'Whether these results can safely replace your entire saved guide for this request. Currently
                        false: retain previous listings when results are empty or incomplete.'
                snapshot_id:
                    type: string
                    format: uuid
                    description: ID of this saved download. It stays the same across all pages; use it to check that pages belong
                        together.
                expires_at:
                    type: string
                    format: date-time
                    description: Expiry time. On a download, finish fetching its pages before this time. On a viewing option,
                        this is the recorded availability expiry.
                page:
                    type: integer
                    minimum: 1
                total_pages:
                    type: integer
                    minimum: 1
                total_results:
                    type: integer
                    minimum: 0
                    description: Total matching records, across all pages.
                airing_count:
                    type: integer
                    minimum: 0
                    maximum: 500
                    description: Number of TV listings on this page.
                has_more:
                    type: boolean
                    description: True when another page remains in this download.
                next_cursor:
                    type: string
                    nullable: true
                    description: Token for the next page. Send it as continuation with your API key and no other parameters.
                        Null means the download is complete.
                airings:
                    type: array
                    maxItems: 500
                    items:
                        $ref: '#/components/schemas/LivePublicGuideAiring'
                    description: Scheduled showings of TV programs, also called listings. A program can have multiple airings.
                coverage:
                    type: array
                    items:
                        type: object
                        additionalProperties: false
                        required:
                            - channel_id
                            - status
                            - last_seen_at
                            - gaps
                            - overlapping_intervals
                            - unknown_end_times
                            - stale_airings
                        properties:
                            channel_id:
                                type: integer
                                description: ID of this specific TV channel or local station. Use it with channel_ids on the
                                    guide endpoints.
                            status:
                                type: string
                                enum:
                                    - continuous
                                    - partial
                                    - unavailable
                                description: continuous means observed listings cover the requested time without known gaps,
                                    overlaps, unknown end times, or stale records. partial means at least one issue exists. unavailable
                                    means no listings were found. Even continuous does not verify a complete guide update.
                            last_seen_at:
                                type: string
                                format: date-time
                                nullable: true
                                description: When Watchmode last saw this record in its data source. This does not guarantee
                                    it is still correct.
                            overlapping_intervals:
                                type: integer
                                description: Number of listings that overlap an earlier listing in the requested time range.
                            unknown_end_times:
                                type: integer
                                description: Number of listings with an unknown or invalid end time.
                            stale_airings:
                                type: integer
                                description: Number of listings whose last-seen time is too old, invalid, or unexpectedly in
                                    the future.
                            gaps:
                                type: array
                                items:
                                    type: object
                                    required:
                                        - from
                                        - to
                                    properties:
                                        from:
                                            type: string
                                            format: date-time
                                        to:
                                            type: string
                                            format: date-time
                                description: Time periods with no known listing. A gap does not prove the channel was off air.
                    description: Information about known availability and missing or outdated data for the requested countries
                        or channels.
        LivePublicLink:
            type: object
            additionalProperties: false
            required:
                - id
                - provider_id
                - region
                - platform
                - link_type
                - url
                - requires_subscription
                - affiliate
                - health_state
                - http_checked_at
                - http_last_success_at
            properties:
                id:
                    type: integer
                provider_id:
                    type: integer
                    nullable: true
                    description: ID of the viewing provider. Use /sources to look up catalog providers; a provider may be a streaming
                        service or TV channel app.
                region:
                    type: string
                    nullable: true
                platform:
                    type: string
                    nullable: true
                link_type:
                    type: string
                    enum:
                        - service_home
                        - channel_page
                        - event_page
                        - gamefinder
                        - playback_deeplink
                        - affiliate_signup
                    description: 'Destination type: service_home, channel_page, event_page, gamefinder, playback_deeplink, or
                        affiliate_signup. Only playback_deeplink points toward a player; playback is still not guaranteed.'
                url:
                    type: string
                    format: uri
                requires_subscription:
                    type: boolean
                    description: Whether the destination requires a subscription. Null means unknown where allowed by the schema.
                affiliate:
                    type: boolean
                    description: Whether this is an affiliate link.
                health_state:
                    type: string
                    enum:
                        - unverified
                        - healthy
                        - dead
                    description: 'HTTP link check result: unverified, healthy (the page responded successfully), or dead. A healthy
                        page does not prove working playback.'
                http_checked_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: Time of the most recent HTTP check of this URL, if any.
                http_last_success_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: Time this URL last passed an HTTP check, if any.
        LivePublicSource:
            type: object
            additionalProperties: false
            required:
                - id
                - provider_id
                - provider_name
                - provider_type
                - is_live_tv_bundle
                - network
                - region
                - scope
                - territory_team_id
                - restriction
                - availability_type
                - channel_package_options
                - channel_package_status
                - package_ids
                - channel_ids
                - requires_subscription
                - requires_location_check
                - subscription_access_status
                - link
                - last_seen_at
                - expires_at
            properties:
                id:
                    type: integer
                provider_id:
                    type: integer
                    description: ID of the viewing provider. Use /sources to look up catalog providers; a provider may be a streaming
                        service or TV channel app.
                provider_name:
                    type: string
                    nullable: true
                provider_type:
                    type: string
                    enum:
                        - free
                        - purchase
                        - subscription
                        - tv_everywhere
                    nullable: true
                    description: Provider access model. tv_everywhere means a TV channel app that may require a TV-provider login.
                is_live_tv_bundle:
                    type: boolean
                    description: Whether this provider is an internet-delivered bundle of live TV channels, such as Fubo or Sling
                        TV.
                network:
                    type: object
                    additionalProperties: false
                    required:
                        - id
                        - name
                    properties:
                        id:
                            type: integer
                        name:
                            type: string
                            nullable: true
                    nullable: true
                    description: The TV network associated with this viewing option, when known.
                region:
                    type: string
                scope:
                    type: string
                    enum:
                        - national
                        - local
                    description: Whether this viewing option applies nationally or to a local area. Other restrictions may still
                        apply.
                restriction:
                    type: string
                    enum:
                        - in_market_only
                        - out_of_market_only
                        - location_rules_unknown
                    description: Known location restriction. in_market_only applies within the local area; out_of_market_only
                        applies outside it; location_rules_unknown means the rules are unknown.
                territory_team_id:
                    type: integer
                    nullable: true
                    description: Team ID associated with a local viewing restriction, if known.
                availability_type:
                    type: string
                    enum:
                        - lineup
                        - service_home
                        - channel_page
                        - event_page
                        - gamefinder
                        - playback_deeplink
                        - affiliate_signup
                    description: Type of recorded viewing destination. lineup means channel/package information without a specific
                        playback destination.
                channel_package_status:
                    type: string
                    enum:
                        - recorded
                        - not_recorded
                    description: recorded means at least one channel/package relationship was found. not_recorded means unknown,
                        not that the service lacks the channel.
                channel_package_options:
                    type: array
                    items:
                        $ref: '#/components/schemas/LivePublicChannelPackageOption'
                    description: Known channel and subscription-package combinations for this viewing option. Keep each pair
                        together; a network match does not prove a specific channel.
                package_ids:
                    type: array
                    items:
                        type: integer
                    nullable: true
                    description: Known subscription-package IDs from channel_package_options. Null when none are known; not a
                        complete package directory.
                channel_ids:
                    type: array
                    items:
                        type: integer
                    nullable: true
                    description: Channel IDs. Returned lists can contain more than 30 IDs; the 30-ID limit applies only to explicit
                        request filters.
                requires_subscription:
                    type: boolean
                    nullable: true
                    description: Whether the destination requires a subscription. Null means unknown where allowed by the schema.
                requires_location_check:
                    type: boolean
                    enum:
                        - true
                    description: Whether viewer location still needs checking. Currently true, including after a TV-market filter.
                subscription_access_status:
                    type: string
                    enum:
                        - unverified
                    description: Whether Watchmode has verified this viewer can watch with their subscription. Currently unverified;
                        no viewer subscription is checked.
                link:
                    allOf:
                        -   $ref: '#/components/schemas/LivePublicLink'
                    nullable: true
                last_seen_at:
                    type: string
                    format: date-time
                    description: When Watchmode last saw this record in its data source. This does not guarantee it is still
                        correct.
                expires_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: Expiry time. On a download, finish fetching its pages before this time. On a viewing option,
                        this is the recorded availability expiry.
        LivePublicChannelPackageOption:
            type: object
            additionalProperties: false
            required:
                - package
                - channel
                - dma
                - postal_code
                - package_zip_restriction
                - matched_via
            properties:
                package:
                    type: object
                    nullable: true
                    additionalProperties: false
                    required:
                        - id
                        - name
                        - type
                    properties:
                        id:
                            type: integer
                        name:
                            type: string
                        type:
                            type: string
                            enum:
                                - base
                                - addon
                                - sports
                                - unknown
                    description: Subscription bundle or add-on associated with this option, if known.
                channel:
                    type: object
                    nullable: true
                    additionalProperties: false
                    required:
                        - id
                        - name
                    properties:
                        id:
                            type: integer
                        name:
                            type: string
                    description: The specific channel or station associated with this package, if known.
                dma:
                    type: string
                    nullable: true
                    description: Three-digit US TV market code (Nielsen DMA), when known. Identifies a viewing area, not a country.
                postal_code:
                    type: string
                    nullable: true
                    description: Recorded ZIP or postal code, when known. This is not confirmation that ZIP-code lookup is supported.
                package_zip_restriction:
                    type: string
                    nullable: true
                    description: Recorded ZIP-code restriction text for this package. ZIP-code filtering is not supported yet.
                matched_via:
                    type: string
                    enum:
                        - channel
                        - network
                        - direct_event_link
                    description: 'How this option was connected to the event: a specific channel, a network, or a direct event
                        link. A network match does not confirm a specific station or channel version.'
        LivePublicBroadcast:
            type: object
            additionalProperties: false
            required:
                - id
                - network_id
                - network_name
                - channel_id
                - channel_name
                - start_time
                - region
                - dma
                - language
            properties:
                id:
                    type: integer
                network_id:
                    type: integer
                    nullable: true
                    description: ID of the TV network brand in the Live dataset, separate from catalog /networks IDs. Multiple channels or local stations can belong to one network.
                network_name:
                    type: string
                    nullable: true
                    description: TV network brand, such as ABC or ESPN.
                channel_id:
                    type: integer
                    nullable: true
                    description: ID of this specific TV channel or local station. Use it with channel_ids on the guide endpoints.
                channel_name:
                    type: string
                    nullable: true
                    description: Name of the specific TV channel or local station, when known.
                start_time:
                    type: string
                    format: date-time
                    description: Start of the broadcast coverage block; it can precede the event start time.
                region:
                    type: string
                    nullable: true
                dma:
                    type: string
                    nullable: true
                    description: Three-digit US TV market code (Nielsen DMA), when known. Identifies a viewing area, not a country.
                language:
                    type: string
                    nullable: true
        LivePublicEvent:
            type: object
            additionalProperties: false
            required:
                - id
                - name
                - event_type
                - league
                - home_team
                - away_team
                - start_time
                - time_confirmation
                - status
                - venue
                - season
                - round
                - broadcasts
                - sources_state
            properties:
                id:
                    type: integer
                name:
                    type: string
                event_type:
                    type: string
                    enum:
                        - sport
                        - awards
                beta:
                    type: boolean
                league:
                    type: object
                    additionalProperties: false
                    required:
                        - id
                        - name
                        - sport
                    properties:
                        id:
                            type: integer
                        name:
                            type: string
                            nullable: true
                        sport:
                            type: string
                            nullable: true
                    nullable: true
                home_team:
                    type: object
                    additionalProperties: false
                    required:
                        - id
                        - name
                        - logo_url
                    properties:
                        id:
                            type: integer
                        name:
                            type: string
                            nullable: true
                        logo_url:
                            type: string
                            nullable: true
                    nullable: true
                away_team:
                    type: object
                    additionalProperties: false
                    required:
                        - id
                        - name
                        - logo_url
                    properties:
                        id:
                            type: integer
                        name:
                            type: string
                            nullable: true
                        logo_url:
                            type: string
                            nullable: true
                    nullable: true
                start_time:
                    type: string
                    format: date-time
                time_confirmation:
                    type: string
                    enum:
                        - unknown
                    description: Whether the scheduled start time has been independently confirmed. Currently unknown.
                status:
                    type: string
                    enum:
                        - scheduled
                        - live
                        - final
                        - postponed
                        - cancelled
                        - unknown
                venue:
                    type: string
                    nullable: true
                season:
                    type: string
                    nullable: true
                    description: Human-readable season when known. Known opaque provider season identifiers are returned as null.
                round:
                    type: string
                    nullable: true
                broadcasts:
                    type: array
                    items:
                        $ref: '#/components/schemas/LivePublicBroadcast'
                sources_state:
                    type: string
                    enum:
                        - not_requested
                        - not_released
                        - known_options
                        - unknown
                        - stale
                    description: 'not_requested: options were not requested; not_released: options are unavailable for this account
                        or event range; known_options: options were found; unknown: availability is unknown; stale: all returned
                        options are outdated.'
                sources:
                    type: array
                    items:
                        $ref: '#/components/schemas/LivePublicSource'
                    description: Where-to-watch options. A service homepage or signup link is not a verified player link.
        LivePublicEventsResponse:
            type: object
            additionalProperties: false
            required:
                - events
                - region
                - page
                - total_pages
                - total_results
                - date_range_limited
                - effective_date_from
                - effective_date_to
                - latest_event_time
            properties:
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/LivePublicEvent'
                region:
                    type: string
                page:
                    type: integer
                total_pages:
                    type: integer
                total_results:
                    type: integer
                    description: Total matching records, across all pages.
                date_range_limited:
                    type: boolean
                    description: True when your plan shortened the requested future date range.
                effective_date_from:
                    type: string
                    format: date-time
                    description: Start time used for the query. Your account access may restrict the returned data further.
                effective_date_to:
                    type: string
                    format: date-time
                    description: End time used for the query, after any plan limit. Your account access may restrict the returned
                        data further.
                latest_event_time:
                    type: string
                    format: date-time
                    nullable: true
                    description: Latest known event start time within your account access and selected leagues. Not a promise
                        of continuous coverage or a refresh time.
        LivePublicSourcesResponse:
            type: object
            additionalProperties: false
            required:
                - id
                - name
                - event_type
                - start_time
                - status
                - regions
                - market
                - sources
                - sources_state
                - coverage
            properties:
                id:
                    type: integer
                name:
                    type: string
                event_type:
                    type: string
                    enum:
                        - sport
                        - awards
                beta:
                    type: boolean
                start_time:
                    type: string
                    format: date-time
                status:
                    type: string
                    enum:
                        - scheduled
                        - live
                        - final
                        - postponed
                        - cancelled
                        - unknown
                regions:
                    type: array
                    items:
                        type: string
                market:
                    type: object
                    additionalProperties: false
                    required:
                        - dma
                        - resolved_from
                    properties:
                        dma:
                            type: string
                            description: Three-digit US TV market code (Nielsen DMA), when known. Identifies a viewing area,
                                not a country.
                        resolved_from:
                            type: string
                            enum:
                                - dma
                                - postal_code
                    nullable: true
                sources:
                    type: array
                    items:
                        $ref: '#/components/schemas/LivePublicSource'
                    description: Where-to-watch options. A service homepage or signup link is not a verified player link.
                sources_state:
                    type: string
                    enum:
                        - not_requested
                        - not_released
                        - known_options
                        - unknown
                        - stale
                    description: 'not_requested: options were not requested; not_released: options are unavailable for this account
                        or event range; known_options: options were found; unknown: availability is unknown; stale: all returned
                        options are outdated.'
                coverage:
                    type: array
                    items:
                        type: object
                        additionalProperties: false
                        required:
                            - region
                            - state
                        properties:
                            region:
                                type: string
                            state:
                                type: string
                                enum:
                                    - not_requested
                                    - not_released
                                    - known_options
                                    - unknown
                                    - stale
                    description: Information about known availability and missing or outdated data for the requested countries
                        or channels.
        Error:
            type: object
            required:
                - success
                - statusCode
                - statusMessage
            properties:
                success:
                    type: boolean
                    example: false
                statusCode:
                    type: integer
                    example: 400
                statusMessage:
                    type: string
                    example: 'Invalid request parameters'

        StatusResponse:
            type: object
            properties:
                quota:
                    type: integer
                    description: Monthly API quota limit
                    example: 1000
                quotaUsed:
                    type: integer
                    description: API calls used this month
                    example: 150

        Source:
            type: object
            properties:
                id:
                    type: integer
                    description: Unique source ID
                    example: 203
                name:
                    type: string
                    description: Source name
                    example: 'Netflix'
                host_source_id:
                    type: integer
                    nullable: true
                    description: The source ID of the platform carrying this offering. For example, Crunchyroll Premium (Via Amazon Prime) remains its own source but returns Amazon's source ID, `24`, here. Direct offerings return `null`.
                    example: 24
                host_source:
                    type: string
                    nullable: true
                    description: The name of the platform carrying this offering. For example, Crunchyroll Premium (Via Amazon Prime) returns `Amazon` here, while direct Crunchyroll Premium returns `null`.
                    example: 'Amazon'
                type:
                    type: string
                    description: |
                        Source type:
                        - `sub` - Subscription service (Netflix, Hulu, etc.)
                        - `purchase` - Rental/purchase service (iTunes, Vudu, etc.)
                        - `free` - Free ad-supported service (Tubi, Pluto TV, etc.)
                        - `tve` - TV Channel App (cable login required)
                    enum: [sub, purchase, free, tve]
                    example: 'sub'
                logo_100px:
                    type: string
                    format: uri
                    description: URL to 100px logo
                    example: 'https://cdn.watchmode.com/logos/203_logo_100px.jpg'
                ios_appstore_url:
                    type: string
                    format: uri
                    nullable: true
                    description: iOS App Store URL
                android_playstore_url:
                    type: string
                    format: uri
                    nullable: true
                    description: Google Play Store URL
                android_tv_url:
                    type: string
                    format: uri
                    nullable: true
                fire_tv_url:
                    type: string
                    format: uri
                    nullable: true
                roku_url:
                    type: string
                    format: uri
                    nullable: true
                tvos_url:
                    type: string
                    format: uri
                    nullable: true
                regions:
                    type: array
                    items:
                        type: string
                    description: Supported 2-letter country codes
                    example: ['US', 'GB', 'CA']

        Region:
            type: object
            properties:
                country:
                    type: string
                    description: 2-letter country code
                    example: 'US'
                name:
                    type: string
                    description: Country name
                    example: 'USA'
                flag:
                    type: string
                    format: uri
                    description: URL to flag image
                    example: 'https://cdn.watchmode.com/misc_images/icons/usFlag2.png'
                data_tier:
                    type: integer
                    description: Data quality tier (1 = highest)
                    enum: [1, 2]
                    example: 1
                plan_enabled:
                    type: boolean
                    description: Whether region is enabled for your plan
                    example: true

        Network:
            type: object
            properties:
                id:
                    type: integer
                    description: Watchmode network ID
                    example: 1
                name:
                    type: string
                    description: Network name
                    example: 'HBO'
                origin_country:
                    type: string
                    description: 2-letter country code
                    example: 'US'
                tmdb_id:
                    type: integer
                    description: TMDB network ID (0 if not available)
                    default: 0
                    example: 49

        Genre:
            type: object
            properties:
                id:
                    type: integer
                    description: Watchmode genre ID
                    example: 4
                name:
                    type: string
                    description: Genre name
                    example: 'Comedy'
                tmdb_id:
                    type: integer
                    description: TMDB genre ID (0 if not available)
                    default: 0
                    example: 35

        SearchResponse:
            type: object
            properties:
                title_results:
                    type: array
                    items:
                        $ref: '#/components/schemas/TitleSearchResult'
                people_results:
                    type: array
                    items:
                        $ref: '#/components/schemas/PersonSearchResult'

        TitleSearchResult:
            type: object
            properties:
                id:
                    type: integer
                    description: Watchmode title ID
                    example: 3173903
                name:
                    type: string
                    description: Title name
                    example: 'Breaking Bad'
                type:
                    type: string
                    enum: [movie, tv_series, tv_special, tv_miniseries, short_film, tv_movie]
                    example: 'tv_series'
                year:
                    type: integer
                    description: Release year
                    example: 2008
                imdb_id:
                    type: string
                    nullable: true
                    description: IMDB ID
                    example: 'tt0903747'
                tmdb_id:
                    type: integer
                    nullable: true
                    description: TMDB ID
                    example: 1396
                tmdb_type:
                    type: string
                    nullable: true
                    enum: [movie, tv]
                    description: TMDB type
                    example: 'tv'

        PersonSearchResult:
            type: object
            properties:
                id:
                    type: integer
                    description: Watchmode person ID
                    example: 710125611
                name:
                    type: string
                    description: Person name
                    example: 'Bryan Cranston'
                main_profession:
                    type: string
                    nullable: true
                    description: Primary profession
                    example: 'actor'
                imdb_id:
                    type: string
                    nullable: true
                    description: IMDB person ID
                    example: 'nm0186505'
                tmdb_id:
                    type: integer
                    nullable: true
                    description: TMDB person ID
                    example: 17419

        AutocompleteResponse:
            type: object
            properties:
                results:
                    type: array
                    items:
                        $ref: '#/components/schemas/AutocompleteResult'

        AutocompleteResult:
            type: object
            properties:
                name:
                    type: string
                    description: Title or person name
                    example: 'Breaking Bad'
                relevance:
                    type: number
                    description: Relevance score
                    example: 445.23
                type:
                    type: string
                    description: Title type (for titles)
                    example: 'tv_series'
                id:
                    type: integer
                    description: Watchmode ID
                    example: 3173903
                year:
                    type: integer
                    nullable: true
                    description: Release year (for titles)
                    example: 2008
                result_type:
                    type: string
                    enum: [title, person]
                    description: Whether result is a title or person
                    example: 'title'
                imdb_id:
                    type: string
                    nullable: true
                    example: 'tt0903747'
                tmdb_id:
                    type: integer
                    nullable: true
                    example: 1396
                tmdb_type:
                    type: string
                    nullable: true
                    enum: [movie, tv]
                    example: 'tv'
                image_url:
                    type: string
                    format: uri
                    nullable: true
                    description: Poster (titles) or headshot (people). May point to a third-party host. Watchmode does not grant any license to the underlying image.
                    example: 'http://www.some-poster-site.com/image.jpg'

        ListTitlesResponse:
            type: object
            properties:
                titles:
                    type: array
                    items:
                        $ref: '#/components/schemas/TitleListItem'
                page:
                    type: integer
                    description: Current page number
                    example: 1
                total_results:
                    type: integer
                    description: Total matching titles
                    example: 4592
                total_pages:
                    type: integer
                    description: Total pages available
                    example: 19

        TitleListItem:
            type: object
            properties:
                id:
                    type: integer
                    example: 1337513
                title:
                    type: string
                    example: 'Secret in Their Eyes'
                year:
                    type: integer
                    example: 2015
                imdb_id:
                    type: string
                    nullable: true
                    example: 'tt1741273'
                tmdb_id:
                    type: integer
                    nullable: true
                    example: 290751
                tmdb_type:
                    type: string
                    nullable: true
                    enum: [movie, tv]
                    example: 'movie'
                type:
                    type: string
                    enum: [movie, tv_series, tv_special, tv_miniseries, short_film, tv_movie]
                    example: 'movie'
                popularity_percentile:
                    type: number
                    nullable: true
                    description: Popularity percentile (0-100) used by popularity sorting across the global catalog, with separate movie and show comparison groups. This is not region-specific audience size or critical reception. Equal underlying values can share a percentile.
                    example: 99.421

        TitleDetails:
            type: object
            properties:
                id:
                    type: integer
                    example: 3173903
                title:
                    type: string
                    example: 'Breaking Bad'
                original_title:
                    type: string
                    nullable: true
                    example: 'Breaking Bad'
                plot_overview:
                    type: string
                    nullable: true
                    description: Plot overview (AI-enhanced when available)
                    example: 'When Walter White, a New Mexico chemistry teacher...'
                will_you_like_this:
                    type: string
                    nullable: true
                    description: AI-generated "Will you like this?" snippet
                review_summary:
                    type: string
                    nullable: true
                    description: AI-generated summary of reviews
                type:
                    type: string
                    enum: [movie, tv_series, tv_special, tv_miniseries, short_film, tv_movie]
                    example: 'tv_series'
                runtime_minutes:
                    type: integer
                    nullable: true
                    example: 45
                year:
                    type: integer
                    example: 2008
                end_year:
                    type: integer
                    nullable: true
                    description: For TV series, the year the show ended
                    example: 2013
                release_date:
                    type: string
                    format: date
                    nullable: true
                    example: '2008-01-20'
                imdb_id:
                    type: string
                    nullable: true
                    example: 'tt0903747'
                tmdb_id:
                    type: integer
                    nullable: true
                    example: 1396
                tmdb_type:
                    type: string
                    nullable: true
                    enum: [movie, tv]
                    example: 'tv'
                genres:
                    type: array
                    items:
                        type: integer
                    nullable: true
                    description: Array of genre IDs
                    example: [7]
                genre_names:
                    type: array
                    items:
                        type: string
                    nullable: true
                    description: Array of genre names
                    example: ['Drama']
                user_rating:
                    type: number
                    nullable: true
                    description: Watchmode audience score (0-10). This field does not specify a vote count or guarantee a minimum audience size. Null when no score is available.
                    example: 9.2
                critic_score:
                    type: integer
                    nullable: true
                    description: Critic score (0-100)
                    example: 85
                us_rating:
                    type: string
                    nullable: true
                    description: US content rating
                    example: 'TV-MA'
                content_ratings:
                    type: object
                    additionalProperties:
                        type: string
                    description: Content ratings keyed by ISO 3166-1 alpha-2 country code
                    example:
                        AU: 'MA 15+'
                        US: 'TV-MA'
                poster:
                    type: string
                    format: uri
                    nullable: true
                    description: Poster image URL. May point to a third-party host. Watchmode does not grant any license to the underlying image.
                    example: 'http://www.some-poster-site.com/image.jpg'
                posterMedium:
                    type: string
                    format: uri
                    nullable: true
                    description: Medium poster image URL. May point to a third-party host. Watchmode does not grant any license to the underlying image.
                    example: 'http://www.some-poster-site.com/image.jpg'
                posterLarge:
                    type: string
                    format: uri
                    nullable: true
                    description: Large poster image URL. May point to a third-party host. Watchmode does not grant any license to the underlying image.
                    example: 'http://www.some-poster-site.com/image.jpg'
                backdrop:
                    type: string
                    format: uri
                    nullable: true
                    description: Backdrop image URL. May point to a third-party host. Watchmode does not grant any license to the underlying image.
                    example: 'http://www.some-poster-site.com/image.jpg'
                original_language:
                    type: string
                    nullable: true
                    description: ISO 639-1 language code
                    example: 'en'
                similar_titles:
                    type: array
                    items:
                        type: integer
                    nullable: true
                    description: Array of similar title IDs
                    example: [330884, 343611]
                networks:
                    type: array
                    items:
                        type: integer
                    nullable: true
                    description: Network IDs (for TV)
                    example: [8]
                network_names:
                    type: array
                    items:
                        type: string
                    nullable: true
                    description: Network names (for TV)
                    example: ['AMC']
                relevance_percentile:
                    type: number
                    nullable: true
                    description: Relevance percentile (0-100)
                    example: 98.92
                popularity_percentile:
                    type: number
                    nullable: true
                    description: Popularity percentile (0-100) derived from popularity signals across the global catalog, with separate movie and show comparison groups. Movies include TV movies and short films; shows include series, miniseries and TV specials. This is not region-specific audience size or critical reception. Equal underlying values can share a percentile.
                    example: 99.99
                trailer:
                    type: string
                    format: uri
                    nullable: true
                    description: YouTube trailer URL
                    example: 'https://www.youtube.com/watch?v=5PSNL1qE6VY'
                trailer_thumbnail:
                    type: string
                    format: uri
                    nullable: true
                    description: Trailer thumbnail URL
                    example: 'http://www.some-poster-site.com/image.jpg'
                english_title:
                    type: string
                    description: English title (when language param is not EN)
                sources:
                    type: array
                    items:
                        $ref: '#/components/schemas/TitleSource'
                    description: Streaming sources (when append_to_response=sources)
                seasons:
                    type: array
                    items:
                        $ref: '#/components/schemas/Season'
                    description: Seasons (when append_to_response=seasons)
                episodes:
                    type: array
                    items:
                        $ref: '#/components/schemas/Episode'
                    description: Episodes (when append_to_response=episodes)
                cast:
                    type: array
                    items:
                        $ref: '#/components/schemas/CastCrew'
                    description: Cast/crew (when append_to_response=cast-crew)

        TitleSource:
            type: object
            description: |
                Streaming source availability for a title.

                **Plan-dependent fields:**
                - `ios_url` and `android_url`: For free plans, returns the string "Deeplinks available for paid plans only." instead of a URL
                - `tvos_url`, `android_tv_url`, `roku_url`: Only included if TV links are enabled for your account
            properties:
                source_id:
                    type: integer
                    example: 203
                name:
                    type: string
                    example: 'Netflix'
                type:
                    type: string
                    description: |
                        Availability type for this title on this source:
                        - `sub` - Available with subscription
                        - `rent` - Available for rental
                        - `buy` - Available for purchase
                        - `free` - Available for free (ad-supported)
                        - `tve` - Available with TV Channel App (cable login)
                    enum: [sub, rent, buy, free, tve]
                    example: 'sub'
                region:
                    type: string
                    example: 'US'
                ios_url:
                    type: string
                    nullable: true
                    description: |
                        iOS deep link URL. For free plans, returns "Deeplinks available for paid plans only."
                android_url:
                    type: string
                    nullable: true
                    description: |
                        Android deep link URL. For free plans, returns "Deeplinks available for paid plans only."
                web_url:
                    type: string
                    format: uri
                    nullable: true
                    description: Web URL to watch the title
                tvos_url:
                    type: string
                    format: uri
                    nullable: true
                    description: |
                        tvOS deep link. **Only included if TV links are enabled for your account.**
                android_tv_url:
                    type: string
                    format: uri
                    nullable: true
                    description: |
                        Android TV deep link. **Only included if TV links are enabled for your account.**
                roku_url:
                    type: string
                    format: uri
                    nullable: true
                    description: |
                        Roku deep link. **Only included if TV links are enabled for your account.**
                format:
                    type: string
                    nullable: true
                    description: Video quality (HD, 4K, etc.)
                    example: 'HD'
                price:
                    type: number
                    nullable: true
                    description: Price for rent/buy sources
                    example: 3.99
                seasons:
                    type: integer
                    nullable: true
                    description: Number of seasons available (for TV)
                    example: 5
                episodes:
                    type: integer
                    nullable: true
                    description: Number of episodes available (for TV)
                    example: 62

        Season:
            type: object
            properties:
                id:
                    type: integer
                    example: 12345
                poster_url:
                    type: string
                    format: uri
                    nullable: true
                    description: Season poster image URL. May point to a third-party host. Watchmode does not grant any license to the underlying image.
                name:
                    type: string
                    nullable: true
                    example: 'Season 1'
                overview:
                    type: string
                    nullable: true
                number:
                    type: integer
                    nullable: true
                    description: Season number
                    example: 1
                air_date:
                    type: string
                    format: date
                    nullable: true
                    example: '2008-01-20'
                episode_count:
                    type: integer
                    nullable: true
                    example: 7

        Episode:
            type: object
            properties:
                id:
                    type: integer
                    example: 1234567
                name:
                    type: string
                    example: 'Pilot'
                episode_number:
                    type: integer
                    example: 1
                season_number:
                    type: integer
                    example: 1
                season_id:
                    type: integer
                    nullable: true
                    example: 12345
                tmdb_id:
                    type: integer
                    nullable: true
                    example: 54321
                imdb_id:
                    type: string
                    nullable: true
                    example: 'tt0959621'
                thumbnail_url:
                    type: string
                    format: uri
                    nullable: true
                    description: Episode thumbnail image URL. May point to a third-party host. Watchmode does not grant any license to the underlying image.
                release_date:
                    type: string
                    format: date
                    nullable: true
                    example: '2008-01-20'
                runtime_minutes:
                    type: integer
                    nullable: true
                    example: 58
                overview:
                    type: string
                    nullable: true
                sources:
                    type: array
                    items:
                        $ref: '#/components/schemas/EpisodeSource'

        EpisodeSource:
            type: object
            description: |
                Streaming source for an episode.

                **Plan-dependent fields:**
                - `ios_url` and `android_url`: For free plans, returns "Deeplinks available for paid plans only."
                - `web_url`: For free plans, returns "Episode links available for paid plans only."
                - `tvos_url`, `android_tv_url`, `roku_url`: Only included if TV links are enabled for your account
            properties:
                source_id:
                    type: integer
                    example: 203
                name:
                    type: string
                    example: 'Netflix'
                type:
                    type: string
                    description: |
                        Availability type for this episode on this source:
                        - `sub` - Available with subscription
                        - `rent` - Available for rental
                        - `buy` - Available for purchase
                        - `free` - Available for free (ad-supported)
                        - `tve` - Available with TV Channel App (cable login)
                    enum: [sub, rent, buy, free, tve]
                    example: 'sub'
                region:
                    type: string
                    example: 'US'
                ios_url:
                    type: string
                    nullable: true
                    description: iOS deep link. For free plans, returns message string.
                android_url:
                    type: string
                    nullable: true
                    description: Android deep link. For free plans, returns message string.
                web_url:
                    type: string
                    nullable: true
                    description: Web URL. For free plans, returns message string.
                tvos_url:
                    type: string
                    format: uri
                    nullable: true
                    description: tvOS deep link (only if TV links enabled)
                android_tv_url:
                    type: string
                    format: uri
                    nullable: true
                    description: Android TV deep link (only if TV links enabled)
                roku_url:
                    type: string
                    format: uri
                    nullable: true
                    description: Roku deep link (only if TV links enabled)
                format:
                    type: string
                    nullable: true
                    description: Video quality
                price:
                    type: number
                    nullable: true
                    description: Price for rent/buy

        CastCrew:
            type: object
            properties:
                person_id:
                    type: integer
                    description: Watchmode person ID
                    example: 7110004
                type:
                    type: string
                    enum: [Cast, Crew]
                    example: 'Cast'
                full_name:
                    type: string
                    example: 'Bryan Cranston'
                role:
                    type: string
                    description: Character name (cast) or job title (crew)
                    example: 'Walter White'
                episode_count:
                    type: integer
                    description: Number of episodes (for TV)
                    example: 62
                order:
                    type: integer
                    nullable: true
                    description: Billing order
                    example: 1

        Person:
            type: object
            properties:
                id:
                    type: integer
                    example: 7110004
                full_name:
                    type: string
                    example: 'Brad Pitt'
                first_name:
                    type: string
                    nullable: true
                    example: 'Brad'
                last_name:
                    type: string
                    nullable: true
                    example: 'Pitt'
                tmdb_id:
                    type: integer
                    nullable: true
                    example: 287
                imdb_id:
                    type: string
                    nullable: true
                    example: 'nm0000093'
                main_profession:
                    type: string
                    nullable: true
                    example: 'actor'
                secondary_profession:
                    type: string
                    nullable: true
                    example: 'producer'
                tertiary_profession:
                    type: string
                    nullable: true
                    example: 'soundtrack'
                date_of_birth:
                    type: string
                    format: date
                    nullable: true
                    example: '1963-12-18'
                date_of_death:
                    type: string
                    format: date
                    nullable: true
                place_of_birth:
                    type: string
                    nullable: true
                    example: 'Shawnee, Oklahoma, USA'
                gender:
                    type: string
                    nullable: true
                    enum: [m, f]
                    example: 'm'
                known_for:
                    type: array
                    items:
                        type: integer
                    nullable: true
                    description: Array of title IDs person is known for
                    example: [1132806, 1336708, 1183315]
                relevance_percentile:
                    type: number
                    description: Popularity percentile (0-100)
                    example: 100

        ReleasesResponse:
            type: object
            properties:
                releases:
                    type: array
                    items:
                        $ref: '#/components/schemas/Release'

        Release:
            type: object
            properties:
                id:
                    type: integer
                    example: 3165490
                title:
                    type: string
                    example: 'Slow Horses'
                type:
                    type: string
                    enum: [movie, tv_series, tv_special, tv_miniseries, short_film, tv_movie]
                    example: 'tv_series'
                tmdb_id:
                    type: integer
                    nullable: true
                    example: 95480
                tmdb_type:
                    type: string
                    nullable: true
                    enum: [movie, tv]
                    example: 'tv'
                imdb_id:
                    type: string
                    nullable: true
                    example: 'tt5875444'
                season_number:
                    type: integer
                    nullable: true
                    description: Season number (for TV)
                    example: 1
                poster_url:
                    type: string
                    format: uri
                    nullable: true
                    description: Poster image URL. May point to a third-party host. Watchmode does not grant any license to the underlying image.
                source_release_date:
                    type: string
                    format: date
                    example: '2022-04-01'
                source_id:
                    type: integer
                    example: 371
                source_name:
                    type: string
                    example: 'AppleTV+'
                is_original:
                    type: integer
                    enum: [0, 1]
                    description: Whether this is an original release on this service
                    example: 1

        TitleReleaseDate:
            type: object
            required: [release_at, release_timezone, time_precision]
            properties:
                id:
                    type: integer
                    example: 1234567
                title:
                    type: string
                    example: 'Dune: Part Two'
                title_type:
                    type: string
                    enum: [movie, tv_series, tv_special, tv_miniseries, short_film, tv_movie]
                    example: 'movie'
                original_language:
                    type: string
                    nullable: true
                    description: Original language code for the matched Watchmode title when available.
                    example: 'en'
                region:
                    type: string
                    example: 'US'
                type:
                    type: string
                    enum: [streaming_movie_release, streaming_tv_season_release, theatrical_release]
                    example: 'theatrical_release'
                release_date:
                    type: string
                    format: date
                    example: '2024-03-01'
                release_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: Known scheduled UTC instant, or null when only a date is supported. Currently limited to fresh, matched local web-channel season premieres.
                release_timezone:
                    type: string
                    nullable: true
                    description: Source IANA time zone associated with release_at; null when the release time is unknown.
                    example: America/New_York
                time_precision:
                    type: string
                    enum: [date, time]
                    description: Date-only values must not be converted to UTC midnight notification times.
                provider_id:
                    type: integer
                    nullable: true
                    description: Streaming provider ID (null for theatrical)
                    example: null
                season:
                    type: integer
                    nullable: true
                    description: Season number (for TV releases)
                    example: null
                verification_status:
                    type: string
                    nullable: true
                    enum: [scheduled, confirmed_available, unverified]
                    description: Verification state for provider-matched digital regional streaming rows. Null for theatrical and legacy rows. Rows without exact digital provider provenance and disputed rows are not returned.
                    example: scheduled
                last_verified:
                    type: string
                    format: date-time
                    nullable: true
                    description: When regional provider availability was last checked. Null until a post-release check runs.
                    example: null

        # TEMPORARILY COMMENTED OUT - Uncomment when ready to publish
        # TitleLeavingDate:
        #     type: object
        #     properties:
        #         id:
        #             type: integer
        #             example: 1234567
        #         title:
        #             type: string
        #             example: 'The Office'
        #         title_type:
        #             type: string
        #             enum: [movie, tv_series, tv_special, tv_miniseries, short_film, tv_movie]
        #             example: 'tv_series'
        #         region:
        #             type: string
        #             example: 'US'
        #         type:
        #             type: string
        #             enum: [streaming_movie_leaving, streaming_tv_season_leaving]
        #             example: 'streaming_tv_season_leaving'
        #         leaving_date:
        #             type: string
        #             format: date
        #             example: '2024-03-01'
        #         provider_id:
        #             type: integer
        #             description: Streaming provider ID
        #             example: 203
        #         season:
        #             type: integer
        #             nullable: true
        #             description: Season number (for TV shows)
        #             example: 9

        ChangesResponse:
            type: object
            properties:
                titles:
                    type: array
                    items:
                        type: integer
                    description: Array of title IDs
                    example: [1138, 1668, 1867, 11029]
                page:
                    type: integer
                    example: 1
                total_results:
                    type: integer
                    example: 6513
                total_pages:
                    type: integer
                    example: 27

        PeopleChangesResponse:
            type: object
            properties:
                people:
                    type: array
                    items:
                        type: integer
                    description: Array of person IDs
                    example: [710203130, 73333445, 710203131]
                page:
                    type: integer
                    example: 1
                total_results:
                    type: integer
                    example: 15113
                total_pages:
                    type: integer
                    example: 61