Thetvdb

TheTVDB API v3

API v3 targets v2 functionality with a few minor additions. The API is accessible via https://api.thetvdb.com and provides the following REST endpoints in…

Media & content#openapi#media#open-data

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

API v3 targets v2 functionality with a few minor additions. The API is accessible via https://api.thetvdb.com and provides the following REST endpoints in JSON format.

How to use this API documentation


You may browse the API routes without authentication, but if you wish to send requests to the API and see response data, then you must authenticate.

  1. Obtain a JWT token by POSTing to the /login route in the Authentication section with your API key and credentials.
  2. Paste the JWT token from the response into the "JWT Token" field at the top of the page and click the 'Add Token' button.

You will now be able to use the remaining routes to send requests to the API and get a response.

Language Selection


Language selection is done via the Accept-Language header. At the moment, you may only pass one language abbreviation in the header at a time. Valid language abbreviations can be found at the /languages route..

Authentication


Authentication to use the API is similar to the How-to section above. Users must POST to the /login route with their API key and credentials in the following format in order to obtain a JWT token.

{"apikey":"APIKEY","username":"USERNAME","userkey":"USERKEY"}

Note that the username and key are ONLY required for the /user routes. The user's key is labled Account Identifier in the account section of the main site.
The token is then used in all subsequent requests by providing it in the Authorization header. The header will look like: Authorization: Bearer . Currently, the token expires after 24 hours. You can GET the /refresh_token route to extend that expiration date.

Versioning


You may request a different version of the API by including an Accept header in your request with the following format: Accept:application/vnd.thetvdb.v$VERSION. This documentation automatically uses the version seen at the top and bottom of the page.

Endpoints 32

Authentication

  • POSTPOST /login/loginReturns a session token to be included in the rest of the requests. Note that API key authentication is required for all subsequent requests and user auth is…
  • GETGET /refresh_token/refresh_tokenRefreshes your current, valid JWT token and returns a new token. Hit this route so that you do not have to post to /login with your API key and credentials…

Episodes

  • GETGET /episodes/{id}/episodes/:idReturns the full information for a given episode id. __Deprecation Warning:__ The _director_ key will be deprecated in favor of the new _directors_ key in a…

Series

  • GETGET /series/{id}/series/:idReturns a series records that contains all information known about a particular series id.
  • HEADHEAD /series/{id}/series/:idReturns header information only about the given series ID.
  • GETGET /series/{id}/actors/series/:id/actorsReturns actors for the given series id
  • GETGET /series/{id}/episodes/series/:id/episodes?page=stringAll episodes for a given series. Paginated with 100 results per page.
  • GETGET /series/{id}/episodes/query/series/:id/episodes/query?absoluteNumber=string&airedSeason=string&airedEpisode=string&dvdSeason=string&dvdEpisode=string&imdbId=string&page=stringThis route allows the user to query against episodes for the given series. The response is a paginated array of episode records.
  • GETGET /series/{id}/episodes/query/params/series/:id/episodes/query/paramsReturns the allowed query keys for the /series/{id}/episodes/query route
  • GETGET /series/{id}/episodes/summary/series/:id/episodes/summaryReturns a summary of the episodes and seasons available for the series. __Note__: Season "0" is for all episodes that are considered to be specials.
  • GETGET /series/{id}/filter/series/:id/filter?keys=stringReturns a series records, filtered by the supplied comma-separated list of keys. Query keys can be found at the /series/{id}/filter/params route.
  • GETGET /series/{id}/filter/params/series/:id/filter/paramsReturns the list of keys available for the /series/{id}/filter route
  • GETGET /series/{id}/images/series/:id/imagesReturns a summary of the images for a particular series
  • GETGET /series/{id}/images/query/series/:id/images/query?keyType=string&resolution=string&subKey=stringQuery images for the given series ID.
  • GETGET /series/{id}/images/query/params/series/:id/images/query/paramsReturns the allowed query keys for the /series/{id}/images/query route. Contains a parameter record for each unique keyType, listing values that will return…

Search

  • GETGET /search/series/search/series?name=string&imdbId=string&zap2itId=string&slug=stringAllows the user to search for a series based on the following parameters.
  • GETGET /search/series/params/search/series/paramsReturns an array of parameters to query by in the /search/series route.

Updates

  • GETGET /updated/query/updated/query?fromTime=string&toTime=stringReturns an array of series that have changed in a maximum of one week blocks since the provided fromTime. The user may specify a toTime to grab results for…
  • GETGET /updated/query/params/updated/query/paramsReturns an array of valid query keys for the /updated/query/params route.

Users

  • GETGET /user/userReturns basic information about the currently authenticated user.
  • GETGET /user/favorites/user/favoritesReturns an array of favorite series for a given user, will be a blank array if no favorites exist.
  • PUTPUT /user/favorites/{id}/user/favorites/:idAdds the supplied series ID to the user’s favorite’s list and returns the updated list.
  • DELETEDELETE /user/favorites/{id}/user/favorites/:idDeletes the given series ID from the user’s favorite’s list and returns the updated list.
  • GETGET /user/ratings/user/ratingsReturns an array of ratings for the given user.
  • GETGET /user/ratings/query/user/ratings/query?itemType=stringReturns an array of ratings for a given user that match the query.
  • GETGET /user/ratings/query/params/user/ratings/query/paramsReturns a list of query params for use in the /user/ratings/query route.
  • DELETEDELETE /user/ratings/{itemType}/{itemId}/user/ratings/:itemType/:itemIdThis route deletes a given rating of a given type.
  • PUTPUT /user/ratings/{itemType}/{itemId}/{itemRating}/user/ratings/:itemType/:itemId/:itemRatingThis route updates a given rating of a given type.

Languages

  • GETGET /languages/languagesAll available languages. These language abbreviations can be used in the Accept-Language header for routes that return translation records.
  • GETGET /languages/{id}/languages/:idInformation about a particular language, given the language ID.

Movies

  • GETGET /movies/{id}/movies/:idReturns a movies records that contains all information known about a particular movies id.
  • GETGET /movieupdates/movieupdates?since=stringReturns all movies ids updated since a given timestamp.

API details

Authentication
An API key in the Authorization header
Operations
32 operations on 30 pathsGET 26PUT 2DELETE 2HEAD 1POST 1
Main resources
Series 12Users 9Authentication 2Languages 2Movies 2Search 2Updates 2Episodes 1
Response formats
application/json
Description format
Swagger 2.0, API version 3.0.0
Listed from
APIs.guru OpenAPI Directory (CC0-1.0)
Source updated

How to test the TheTVDB API v3 in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the TheTVDB API v3 collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “POST /login” (POST /login), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the TheTVDB API v3?

API v3 targets v2 functionality with a few minor additions. The API is accessible via https://api.thetvdb.com and provides the following REST endpoints in… It is listed under Media & content and has 32 endpoints.

Who publishes the TheTVDB API v3?

It is listed from Thetvdb's public API description (an OpenAPI document), not published by Thetvdb on Swastik Codes. Anyone who controls thetvdb.com can claim the profile by adding a DNS TXT record.

How do I authenticate with the TheTVDB API v3?

With an API key in the Authorization header.

How many endpoints does the TheTVDB API v3 have?

32 operations on 30 paths (26 GET, 2 PUT, 2 DELETE, 1 HEAD, 1 POST). The largest groups are Series, Users, Authentication, Languages.

Is forking the TheTVDB API v3 free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.