Watchmode Getting Started: Setup and First API Call (2026)

Getting started overview

This guide outlines the process for new users to initiate their integration with the Watchmode API. It focuses on the fundamental steps required to go from account creation to a successful API request, providing a quick path to begin developing applications that utilize Watchmode's streaming availability and content metadata. The Watchmode API provides programmatic access to a comprehensive database of movie and TV show information, including where content is available to stream, rent, or buy across various platforms.

To ensure a smooth onboarding experience, this guide covers:

• Creating a Watchmode developer account.
• Locating and securing your API key.
• Constructing and executing your first API call using cURL.
• Common next steps for further integration.
• Troubleshooting tips for initial requests.

The Watchmode API utilizes a RESTful architecture, meaning it interacts with HTTP methods (like GET) to perform operations on resources, typically returning data in JSON format, which is a common data interchange format for web APIs JSON official website.

Quick reference table

Create an account and get keys

Accessing the Watchmode API requires a developer account and a unique API key. The API key serves as an authentication credential that verifies your identity when making requests Google Maps API key security.

Step 1: Sign up for a developer account

1. Navigate to the Watchmode API documentation page.
2. Click on the "Sign Up" or "Get API Key" button, typically found in the navigation bar or prominent on the landing page.
3. Complete the registration form by providing your email address, creating a password, and agreeing to the terms of service.
4. Verify your email address if prompted. This step is crucial for activating your account.

Upon successful registration, you will typically be redirected to your developer dashboard.

Step 2: Retrieve your API key

1. Once logged into your Watchmode developer dashboard, locate the section dedicated to API keys or credentials. This is often labeled "API Keys," "Dashboard," or "Settings."
2. Your unique API key will be displayed. It is a string of alphanumeric characters.
3. Copy your API key. Keep this key secure and do not expose it in client-side code or public repositories.

The Watchmode Developer Plan offers a free tier allowing up to 500 requests per day, which is suitable for initial testing and development.

Your first request

With an API key in hand, you can now make your first request to the Watchmode API. This example demonstrates fetching details for a specific title using the /v1/title/{title_id}/details/ endpoint.

API endpoint and parameters

For this example, we will use the Title Details endpoint. A typical request requires:

• Endpoint: https://api.watchmode.com/v1/title/{title_id}/details/
• Path Parameter: {title_id} - A unique identifier for the movie or TV show. For this example, we'll use 2128704 (which corresponds to "Dune").
• Query Parameter: apiKey - Your unique Watchmode API key.
• Query Parameter: append_to_response - Optional, to include additional data like sources. Use sources to include streaming availability.

Making the request with cURL

cURL is a command-line tool and library for transferring data with URLs, widely used for making HTTP requests cURL man page.

Replace YOUR_API_KEY with the actual API key you retrieved from your dashboard.

curl "https://api.watchmode.com/v1/title/2128704/details/?apiKey=YOUR_API_KEY&append_to_response=sources"

Expected response

A successful request will return a JSON object containing detailed information about the title, including its streaming availability. The response will resemble the following (truncated for brevity):

{
  "id": 2128704,
  "title": "Dune",
  "type": "movie",
  "year": 2021,
  "genre_ids": [18, 878],
  "user_rating": 7.8,
  "plot_overview": "Paul Atreides, a brilliant and gifted young man...",
  "poster": "https://cdn.watchmode.com/posters/2128704_poster_w185.jpg",
  "sources": [
    {
      "source_id": 203,
      "name": "Max",
      "type": "sub",
      "region": "US",
      "web_url": "https://play.max.com/movie/...
    },
    {
      "source_id": 372,
      "name": "Hulu",
      "type": "sub",
      "region": "US",
      "web_url": "https://www.hulu.com/movie/...
    }
    // ... more sources
  ],
  "runtime_minutes": 155,
  "critic_score": 83
}

This response confirms that the API call was successful and data for "Dune" (ID 2128704) was retrieved, including its streaming sources.

Common next steps

After successfully making your first API call, consider these next steps to further integrate Watchmode into your application:

1. Explore Endpoints: Review the Watchmode API documentation to discover other available endpoints, such as searching for titles, fetching cast and crew information, or exploring upcoming releases.
2. Integrate with a Programming Language: Move beyond cURL and integrate the API into your preferred programming language (e.g., Python, Node.js, PHP) using an HTTP client library.
3. Implement Error Handling: Develop robust error handling mechanisms to manage API rate limits, invalid requests, or unexpected responses.
4. Manage API Keys Securely: Implement best practices for storing and managing your API key, such as using environment variables or a secrets management service, rather than hardcoding it into your application.
5. Monitor Usage: Keep track of your API request usage through your Watchmode developer dashboard to stay within your plan's limits.
6. Consider Paid Plans: If your application requires higher request volumes, explore the Watchmode pricing plans.

Troubleshooting the first call

If your first API call does not return the expected results, consider the following common issues and solutions:

• Invalid API Key:

  • Issue: You receive an authentication error (e.g., 401 Unauthorized) or a message indicating an invalid API key.
  • Solution: Double-check that you have copied your API key correctly from your Watchmode dashboard. Ensure there are no leading or trailing spaces. Confirm it is passed as a query parameter named apiKey.

• Incorrect Endpoint or Parameters:

  • Issue: The API returns a 404 Not Found or 400 Bad Request error.
  • Solution: Verify the URL for the endpoint. Ensure the title_id is correct and that all required query parameters (like append_to_response if used) are spelled correctly and formatted as key-value pairs. Refer to the official Watchmode API documentation for exact endpoint paths and parameter names.

• Rate Limiting:

  • Issue: You receive a 429 Too Many Requests error.
  • Solution: This indicates you've exceeded your plan's request limit. For the free Developer Plan, this is 500 requests per day. Wait for the rate limit to reset, or consider upgrading your plan if sustained higher usage is necessary.

• Network Connectivity Issues:

  • Issue: The request times out or fails to connect.
  • Solution: Check your internet connection. Ensure there are no firewall rules or proxy settings preventing your system from reaching the api.watchmode.com domain.

• JSON Parsing Errors:

  • Issue: Your application fails to parse the API response.
  • Solution: Confirm the API is returning valid JSON. Use a JSON linter or formatter to inspect the raw response if you are encountering parsing issues in your code. Most HTTP client libraries handle JSON parsing automatically.