TVDB Getting Started: Quick Guide to API Access (2026)

Getting started overview

To begin using the TVDB API, the foundational steps involve creating a user account, generating the necessary API credentials, and successfully authenticating to make your first data request. The TVDB API provides access to a database of television series, movies, anime, and company metadata for developers. The authentication mechanism is based on the OAuth 2.0 authorization framework, requiring both an API Key and a User Key for session authorization.

This guide outlines the process from account creation to a successful API call, focusing on the Developer Plan, which offers a free tier suitable for initial exploration and small-scale projects. This plan provides 500 API calls per day, which is generally sufficient for development and testing purposes before considering a paid subscription plan for higher call volumes.

The primary resource for in-depth information regarding the API's capabilities and endpoint specifics is the TVDB API Wiki, which hosts the V4 API Reference. This reference details all available endpoints, request parameters, and response structures.

Here's a quick reference table for getting started:

Create an account and get keys

Accessing the TVDB API requires a free user account and the generation of specific API credentials. These credentials are vital for authenticating your requests and include an API Key and a User Key. The TVDB API uses an OAuth 2.0 based authentication system, which means you'll exchange these keys for a temporary access token.

1. Register for a TVDB account

Navigate to the TVDB registration page. You will need to provide an email address, choose a username, and set a password. After registration, verify your email address as instructed.

2. Generate an API Key

Once your account is active, log in and proceed to the API Key management page. Here, you can generate a new API Key for your application. Each API Key is unique to an application or project you register. Make sure to assign a descriptive name to your key for easier management, especially if you plan to use the API for multiple projects. The API Key is a public identifier for your application.

3. Locate your User Key

Your User Key is a personal identifier linked to your TVDB user account. It is used in conjunction with your API Key to obtain an access token. You can find your User Key by logging into your TVDB account and visiting your API Access page. This key is sensitive and should be kept secure, similar to a password.

Your first request

Making your first request to the TVDB API involves two primary steps: authenticating to obtain an access token and then using that token to fetch data. All API requests should be made to the base URL https://api4.thetvdb.com/v4.

Step 1: Obtain an Access Token (Authentication)

The TVDB API uses a token-based authentication system. You'll need to send a POST request to the /login endpoint, providing your API Key (apikey) and User Key (userkey) in the request body. The request body should be a JSON object.

Request URL: https://api4.thetvdb.com/v4/login
Method: POST
Headers: Content-Type: application/json

Request Body Example:

{
  "apikey": "YOUR_API_KEY",
  "userkey": "YOUR_USER_KEY"
}

A successful response will return a JSON object containing your token. This token is your access token and is typically valid for 24 hours. You must include this token in the Authorization header of all subsequent API requests.

Successful Response Example:

{
  "status": "success",
  "data": {
    "token": "YOUR_ACCESS_TOKEN"
  }
}

Step 2: Make a Data Request

Once you have your access token, you can make authenticated requests to retrieve data. For your first data request, you might try searching for a TV series, such as "The Office".

Request URL: https://api4.thetvdb.com/v4/series/search?query=The%20Office
Method: GET
Headers:
  Content-Type: application/json
  Authorization: Bearer YOUR_ACCESS_TOKEN

Replace YOUR_ACCESS_TOKEN with the token you received in the previous step. The Bearer prefix is a standard part of Bearer Token authentication.

A successful response will return a list of TV series matching "The Office", including metadata like IDs, names, and overview information. This confirms that your authentication and API call were successful.

Successful Search Response Snippet:

{
  "status": "success",
  "data": [
    {
      "id": 73244,
      "name": "The Office (US)",
      "overview": "A mockumentary on a group of typical office workers...",
      "image": "https://artworks.thetvdb.com/banners/v4/series/73244/posters/613c75f564f15.jpg"
    },
    // ... more results
  ]
}

Common next steps

After successfully making your first API call, you can explore the extensive capabilities of the TVDB API to enrich your application or media management system. Here are some common next steps:

• Explore More Endpoints: Consult the TVDB V4 API Reference to discover other available endpoints for movies, anime, people, companies, and more. You can retrieve detailed information about specific series or films using their unique IDs.
• Implement Refresh Token Logic: Since access tokens expire, you'll need to manage token refreshing. The TVDB API provides an endpoint (/refresh_token) to get a new access token using your existing (but soon-to-expire) token. This helps maintain continuous access without requiring users to re-authenticate with their API and User Keys.
• Handle Rate Limits: Be aware of the API call limits associated with your plan (e.g., 500 calls/day for the Developer Plan). Implement logic in your application to respect these limits and handle 429 Too Many Requests responses gracefully. Consider upgrading your plan if your usage exceeds the free tier limits. TVDB's pricing page details higher call limits for paid plans.
• Error Handling: Implement robust error handling for various HTTP status codes and API-specific error messages. This includes handling authentication failures, invalid requests, and server errors.
• Integrate with a Library: For easier development, consider using an HTTP client library in your preferred programming language (e.g., Axios in JavaScript, Requests in Python) to manage API calls, headers, and JSON parsing.
• Explore Webhooks: While not a primary "getting started" feature, TVDB offers webhooks for real-time notifications about data changes. If your application requires immediate updates, investigate implementing webhook listeners.

Troubleshooting the first call

Encountering issues during your first API calls is common. Here are some troubleshooting tips for common problems:

• Invalid API Key or User Key (Authentication):
  • Symptom: You receive an authentication error (e.g., 401 Unauthorized or 403 Forbidden) when trying to get an access token.
  • Solution: Double-check that your apikey and userkey in the /login POST request body are exactly correct. Ensure there are no leading/trailing spaces or typos. Verify that your API Key is active on the TVDB API Keys page and your User Key is correct on your API Access page.
• Missing or Incorrect Authorization Header (Data Requests):
  • Symptom: After successfully obtaining a token, subsequent data requests fail with 401 Unauthorized.
  • Solution: Ensure you are including the Authorization: Bearer YOUR_ACCESS_TOKEN header in your data requests. The token must be prefixed with Bearer and a space. Verify that the token itself is correct and hasn't expired.
• Token Expiration:
  • Symptom: Requests work for a period, then start failing with 401 Unauthorized after approximately 24 hours.
  • Solution: Your access token has expired. You need to obtain a new token using the /login endpoint or the /refresh_token endpoint as described in the API documentation.
• Incorrect Endpoint URL or Method:
  • Symptom: You receive 404 Not Found or 405 Method Not Allowed errors.
  • Solution: Verify the exact endpoint URL against the TVDB V4 API Reference. Ensure you are using the correct HTTP method (e.g., GET for data retrieval, POST for login). The API base URL is https://api4.thetvdb.com/v4.
• Rate Limit Exceeded:
  • Symptom: You receive a 429 Too Many Requests error.
  • Solution: You have exceeded your plan's API call limit. Wait for the rate limit period to reset (typically daily) or consider upgrading your API plan for higher limits. Implement exponential backoff or similar strategies in your application to handle these errors.
• JSON Formatting Issues:
  • Symptom: 400 Bad Request when sending a POST request (e.g., for login).
  • Solution: Ensure your request body is valid JSON and that the Content-Type: application/json header is correctly set. Check for syntax errors in your JSON payload.
• Network Issues:
  • Symptom: Requests time out or fail with network-related errors.
  • Solution: Verify your internet connection and ensure no firewalls or proxies are blocking access to api4.thetvdb.com.