TheTVDB v4 API

openapi: 3.0.0
info:
  description: |
    Documentation of [TheTVDB](https://thetvdb.com/) API V4. All related information is linked from our [Github repo](https://github.com/thetvdb/v4-api). You might also want to use our [Postman collection] (https://www.getpostman.com/collections/7a9397ce69ff246f74d0)
    ## Authentication
    1. Use the /login endpoint and provide your API key as "apikey". If you have a user-supported key, also provide your subscriber PIN as "pin". Otherwise completely remove "pin" from your call.
    2. Executing this call will provide you with a bearer token, which is valid for 1 month.
    3. Provide your bearer token for subsequent API calls by clicking Authorize below or including in the header of all direct API calls: `Authorization: Bearer [your-token]`

    ## Notes
    1. "score" is a field across almost all entities.  We generate scores for different types of entities in various ways, so no assumptions should be made about the meaning of this value.  It is simply used to hint at relative popularity for sorting purposes.
  title: TVDB API V4
  version: 4.7.10
  x-last-validated: '2026-05-30'
  x-spec-source: https://github.com/thetvdb/v4-api/blob/main/docs/swagger.yml
servers:
- url: 'https://api4.thetvdb.com/v4'
  description: TheTVDB v4 API production
security:
- bearerAuth: []
paths:
  /login:
    post:
      summary: TheTVDB Create an Auth Token. the Token Has One Month Validation Length.
      operationId: login
      tags:
      - Login
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - apikey
              properties:
                apikey:
                  type: string
                pin:
                  type: string
            examples:
              LoginRequestExample:
                summary: Default login request
                x-microcks-default: true
                value:
                  apikey: YOUR_API_KEY
                  pin: A1B2C3D4
        required: true
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      token:
                        type: string
                    type: object
                  status:
                    type: string
                type: object
              examples:
                Login200Example:
                  summary: Default login 200 response
                  x-microcks-default: true
                  value:
                    data:
                      token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.payload.signature
                    status: Continuing
        '401':
          description: invalid credentials
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/artwork/{id}':
    get:
      description: Returns a single artwork base record.
      operationId: getArtworkBase
      parameters:
      - description: id
        in: path
        name: id
        required: true
        schema:
          type: number
        example: 12345
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ArtworkBaseRecord'
                  status:
                    type: string
                type: object
              examples:
                GetArtworkBase200Example:
                  summary: Default getArtworkBase 200 response
                  x-microcks-default: true
                  value:
                    data:
                      height: 12345
                      id: 12345
                      image: https://artworks.thetvdb.com/banners/example.jpg
                      includesText: true
                      language: eng
                      score: 100
                      thumbnail: example
                      type: 12345
                      width: 12345
                    status: Continuing
        '400':
          description: Invalid artwork id
        '401':
          description: Unauthorized
        '404':
          description: Artwork not found
      tags:
      - Artwork

      summary: TheTVDB Get Artwork Base
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/artwork/{id}/extended':
    get:
      description: Returns a single artwork extended record.
      operationId: getArtworkExtended
      parameters:
      - description: id
        in: path
        name: id
        required: true
        schema:
          type: number
        example: 12345
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ArtworkExtendedRecord'
                  status:
                    type: string
                type: object
              examples:
                GetArtworkExtended200Example:
                  summary: Default getArtworkExtended 200 response
                  x-microcks-default: true
                  value:
                    data:
                      episodeId: 12345
                      height: 12345
                      id: 12345
                      image: https://artworks.thetvdb.com/banners/example.jpg
                      includesText: true
                      language: eng
                      movieId: 12345
                      networkId: 12345
                      peopleId: 12345
                      score: 100
                      seasonId: 12345
                      seriesId: 12345
                      seriesPeopleId: 12345
                      status:
                        id: 12345
                        name: Example Name
                      tagOptions:
                      - helpText: example
                        id: 12345
                        name: Example Name
                        tag: 12345
                        tagName: example
                      thumbnail: example
                      thumbnailHeight: 12345
                      thumbnailWidth: 12345
                      type: 12345
                      updatedAt: '2024-01-15'
                      width: 12345
                    status: Continuing
        '400':
          description: Invalid artwork id
        '401':
          description: Unauthorized
        '404':
          description: Artwork not found
      tags:
      - Artwork

      summary: TheTVDB Get Artwork Extended
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/artwork/statuses':
    get:
      description: Returns list of artwork status records.
      operationId: getAllArtworkStatuses
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/ArtworkStatus'
                    type: array
                  status:
                    type: string
                type: object
              examples:
                GetAllArtworkStatuses200Example:
                  summary: Default getAllArtworkStatuses 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: 12345
                      name: Example Name
                    status: Continuing
        '401':
          description: Unauthorized
      tags:
      - Artwork Statuses

      summary: TheTVDB Get All Artwork Statuses
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/artwork/types':
    get:
      description: Returns a list of artworkType records
      operationId: getAllArtworkTypes
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/ArtworkType'
                    type: array
                  status:
                    type: string
                type: object
              examples:
                GetAllArtworkTypes200Example:
                  summary: Default getAllArtworkTypes 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - height: 12345
                      id: 12345
                      imageFormat: example
                      name: Example Name
                      recordType: example
                      slug: example-slug
                      thumbHeight: 12345
                      thumbWidth: 12345
                      width: 12345
                    status: Continuing
        '401':
          description: Unauthorized
      tags:
      - Artwork Types

      summary: TheTVDB Get All Artwork Types
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /awards:
    get:
      description: Returns a list of award base records
      operationId: getAllAwards
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/AwardBaseRecord'
                    type: array
                  status:
                    type: string
                type: object
              examples:
                GetAllAwards200Example:
                  summary: Default getAllAwards 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: 12345
                      name: Example Name
                    status: Continuing
        '401':
          description: Unauthorized
      tags:
      - Awards

      summary: TheTVDB Get All Awards
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/awards/{id}':
    get:
      description: Returns a single award base record
      operationId: getAward
      parameters:
      - description: id
        in: path
        name: id
        required: true
        schema:
          type: number
        example: 12345
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/AwardBaseRecord'
                  status:
                    type: string
                type: object
              examples:
                GetAward200Example:
                  summary: Default getAward 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: 12345
                      name: Example Name
                    status: Continuing
        '400':
          description: Invalid awards id
        '401':
          description: Unauthorized
        '404':
          description: Awards not found
      tags:
      - Awards

      summary: TheTVDB Get Award
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/awards/{id}/extended':
    get:
      description: Returns a single award extended record
      operationId: getAwardExtended
      parameters:
      - description: id
        in: path
        name: id
        required: true
        schema:
          type: number
        example: 12345
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/AwardExtendedRecord'
                  status:
                    type: string
                type: object
              examples:
                GetAwardExtended200Example:
                  summary: Default getAwardExtended 200 response
                  x-microcks-default: true
                  value:
                    data:
                      categories:
                      - allowCoNominees: true
                        award:
                          id: 12345
                          name: Example Name
                        forMovies: true
                        forSeries: true
                        id: 12345
                        name: Example Name
                      id: 12345
                      name: Example Name
                      score: 100
                    status: Continuing
        '400':
          description: Invalid awards id
        '401':
          description: Unauthorized
        '404':
          description: Awards not found
      tags:
      - Awards

      summary: TheTVDB Get Award Extended
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/awards/categories/{id}':
    get:
      description: Returns a single award category base record
      operationId: getAwardCategory
      parameters:
      - description: id
        in: path
        name: id
        required: true
        schema:
          type: number
        example: 12345
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/AwardCategoryBaseRecord'
                  status:
                    type: string
                type: object
              examples:
                GetAwardCategory200Example:
                  summary: Default getAwardCategory 200 response
                  x-microcks-default: true
                  value:
                    data:
                      allowCoNominees: true
                      award:
                        id: 12345
                        name: Example Name
                      forMovies: true
                      forSeries: true
                      id: 12345
                      name: Example Name
                    status: Continuing
        '400':
          description: Invalid category id
        '401':
          description: Unauthorized
        '404':
          description: Category not found
      tags:
      - Award Categories

      summary: TheTVDB Get Award Category
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/awards/categories/{id}/extended':
    get:
      description: Returns a single award category extended record
      operationId: getAwardCategoryExtended
      parameters:
      - description: id
        in: path
        name: id
        required: true
        schema:
          type: number
        example: 12345
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/AwardCategoryExtendedRecord'
                  status:
                    type: string
                type: object
              examples:
                GetAwardCategoryExtended200Example:
                  summary: Default getAwardCategoryExtended 200 response
                  x-microcks-default: true
                  value:
                    data:
                      allowCoNominees: true
                      award:
                        id: 12345
                        name: Example Name
                      forMovies: true
                      forSeries: true
                      id: 12345
                      name: Example Name
                      nominees:
                      - character:
                          aliases:
                          - language:
                            name:
                          episode:
                            image:
                            name:
                            year:
                          episodeId: 12345
                          id: 12345
                          image: https://artworks.thetvdb.com/banners/example.jpg
                          isFeatured: true
                          movieId: 12345
                          movie:
                            image:
                            name:
                            year:
                          name: Example Name
                          nameTranslations: &id001
                          - example
                          overviewTranslations: &id002
                          - example
                          peopleId: 12345
                          personImgURL: https://artworks.thetvdb.com/banners/example.jpg
                          peopleType: example
                          seriesId: 12345
                          series:
                            image:
                            name:
                            year:
                          sort: 12345
                          tagOptions:
                          - helpText:
                            id:
                            name:
                            tag:
                            tagName:
                          type: 12345
                          url: https://artworks.thetvdb.com/banners/example.jpg
                          personName: example
                        details: example
                        episode:
                          absoluteNumber: 1
                          aired: example
                          airsAfterSeason: 1
                          airsBeforeEpisode: 1
                          airsBeforeSeason: 1
                          finaleType: example
                          id: 12345
                          image: https://artworks.thetvdb.com/banners/example.jpg
                          imageType: 1
                          isMovie: 12345
                          lastUpdated: '2024-01-15'
                          linkedMovie: 1
                          name: Example Name
                          nameTranslations: &id005
                          - example
                          number: 1
                          overview: A descriptive paragraph of text.
                          overviewTranslations: &id006
                          - example
                          runtime: 1
                          seasonNumber: 1
                          seasons:
                          - id:
                            image:
                            imageType:
                            lastUpdated:
                            name:
                            nameTranslations:
                            number:
                            overviewTranslations:
                            companies: {}
                            seriesId:
                            type: {}
                            year:
                          seriesId: 12345
                          seasonName: example
                          year: '2024'
                        id: 12345
                        isWinner: true
                        movie:
                          aliases:
                          - language:
                            name:
                          id: 12345
                          image: https://artworks.thetvdb.com/banners/example.jpg
                          lastUpdated: '2024-01-15'
                          name: Example Name
                          nameTranslations: &id009
                          - example
                          overviewTranslations: &id010
                          - example
                          score: 100
                          slug: example-slug
                          status:
                            id:
                            keepUpdated:
                            name:
                            recordType:
                          runtime: 1
                          year: '2024'
                        series:
                          aliases:
                          - language:
                            name:
                          averageRuntime: 1
                          country: usa
                          defaultSeasonType: 12345
                          episodes:
                          - absoluteNumber:
                            aired:
                            airsAfterSeason:
                            airsBeforeEpisode:
                            airsBeforeSeason:
                            finaleType:
                            id:
                            image:
                            imageType:
                            isMovie:
                            lastUpdated:
                            linkedMovie:
                            name:
                            nameTranslations:
                            number:
                            overview:
                            overviewTranslations:
                            runtime:
                            seasonNumber:
                            seasons:
                            - {}
                            seriesId:
                            seasonName:
                            year:
                          firstAired: example
                          id: 12345
                          image: https://artworks.thetvdb.com/banners/example.jpg
                          isOrderRandomized: true
                          lastAired: example
                          lastUpdated: '2024-01-15'
                          name: Example Name
                          nameTranslations: &id011
                          - example
                          nextAired: example
                          originalCountry: example
                          originalLanguage: example
                          overviewTranslations: &id012
                          - example
                          score: 100
                          slug: example-slug
                          status:
                            id:
                            keepUpdated:
                            name:
                            recordType:
                          year: '2024'
                        year: '2024'
                        category: example
                        name: Example Name
                    status: Continuing
        '400':
          description: Invalid category id
        '401':
          description: Unauthorized
        '404':
          description: Category not found
      tags:
      - Award Categories

      summary: TheTVDB Get Award Category Extended
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/characters/{id}':
    get:
      description: Returns character base record
      operationId: getCharacterBase
      parameters:
      - description: id
        in: path
        name: id
        required: true
        schema:
          type: number
        example: 12345
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Character'
                  status:
                    type: string
                type: object
              examples:
                GetCharacterBase200Example:
                  summary: Default getCharacterBase 200 response
                  x-microcks-default: true
                  value:
                    data:
                      aliases:
                      - language: eng
                        name: Example Name
                      episode:
                        image: https://artworks.thetvdb.com/banners/example.jpg
                        name: Example Name
                        year: '2024'
                      episodeId: 12345
                      id: 12345
                      image: https://artworks.thetvdb.com/banners/example.jpg
                      isFeatured: true
                      movieId: 12345
                      movie:
                        image: https://artworks.thetvdb.com/banners/example.jpg
                        name: Example Name
                        year: '2024'
                      name: Example Name
                      nameTranslations: *id001
                      overviewTranslations: *id002
                      peopleId: 12345
                      personImgURL: https://artworks.thetvdb.com/banners/example.jpg
                      peopleType: example
                      seriesId: 12345
                      series:
                        image: https://artworks.thetvdb.com/banners/example.jpg
                        name: Example Name
                        year: '2024'
                      sort: 12345
                      tagOptions:
                      - helpText: example
                        id: 12345
                        name: Example Name
                        tag: 12345
                        tagName: example
                      type: 12345
                      url: https://artworks.thetvdb.com/banners/example.jpg
                      personName: example
                    status: Continuing
        '400':
          description: Invalid character id
        '401':
          description: Unauthorized
        '404':
          description: Character not found
      tags:
      - Characters
      summary: TheTVDB Get Character Base
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies:
    get:
      description: returns a paginated list of company records
      operationId: getAllCompanies
      parameters:
      - description: name
        in: query
        name: page
        schema:
          type: number
        example: 1.0
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Company'
                    type: array
                  status:
                    type: string
                  links:
                    $ref: '#/components/schemas/Links'
                type: object
              examples:
                GetAllCompanies200Example:
                  summary: Default getAllCompanies 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - activeDate: '2024-01-15'
                      aliases:
                      - language: eng
                        name: Example Name
                      country: usa
                      id: 12345
                      inactiveDate: '2024-01-15'
                      name: Example Name
                      nameTranslations: &id003
                      - example
                      overviewTranslations: &id004
                      - example
                      primaryCompanyType: 12345
                      slug: example-slug
                      parentCompany:
                        id: 12345
                        name: Example Name
                        relation:
                          id: 12345
                          typeName: example
                      tagOptions:
                      - helpText: example
                        id: 12345
                        name: Example Name
                        tag: 12345
                        tagName: example
                    status: Continuing
                    links:
                      prev: example
                      self: example
                      next: example
                      total_items: 1
                      page_size: 1
        '401':
          description: Unauthorized
      tags:
      - Companies
      summary: TheTVDB Get All Companies
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/companies/types':
    get:
      description: returns all company type records
      operationId: getCompanyTypes
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompanyType'
                  status:
                    type: string
                type: object
              examples:
                GetCompanyTypes200Example:
                  summary: Default getCompanyTypes 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - companyTypeId: 12345
                      companyTypeName: example
                    status: Continuing
        '401':
          description: Unauthorized
      tags:
      - Companies
      summary: TheTVDB Get Company Types
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  '/companies/{id}':
    get:
      description: returns a company record
      operationId: getCompany
      parameters:
      - description: id
        in: path
        name: id
        required: true
        schema:
          type: number
        example: 12345
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Company'
                  status:
                    type: string
                type: object
              examples:
                GetCompany200Example:
                  summary: Default getCompany 200 response
                  x-microcks-default: true
                  value:
                    data:
                      activeDate: '2024-01-15'
                      aliases:
                      - language: eng
                        name: Example Name
                      country: usa
                      id: 12345
                      inactiveDate: '2024-01-15'
                      name: Example Name
                      nameTranslations: *id003
                      overviewTranslations: *id004
                      primaryCompanyType: 12345
                      slug: example-slug
                      parentCompany:
                        id: 12345
                        name: Example Name
                        relation:
                          id: 12345
                          typeName: example
                      tagOptions:
                      - helpText: example
                        id: 12345
                        name: Example Name
                        tag: 12345
                        tagName: example
                    status: Continuing
        '400':
          description: Invalid company id
        '401':
          description: Unauthorized
        '404':
          description: Company not found
      tags:
      - Companies
      summary: TheTVDB Get Company
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /content/ratings:
    get:
      description: returns list content rating records
      operationId: getAllContentRatings
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/ContentRating'
                    type: array
                  status:
                    type: string
                type: object
              examples:
                GetAllContentRatings200Example:
                  summary: Default getAllContentRatings 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: 12345
                      name: Example Name
                      description: A descriptive paragraph of text.
                      country: usa
                      contentType: example
                      order: 1
                      fullName: example
                    status: Continuing
        '401':
          description: Unauthorized
      tags:
      - Content Ratings
      summary: TheTVDB Get All Content Ratings
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /countries:
    get:
      description: returns list of country records


# --- truncated at 32 KB (300 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tvdb/refs/heads/main/openapi/tvdb-openapi.yml