TheTVDB Seasons 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 Artwork Seasons API
  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: []
tags:
- name: Seasons
paths:
  /seasons:
    get:
      description: returns list of seasons base records
      operationId: getAllSeasons
      parameters:
      - description: page number
        in: query
        name: page
        schema:
          type: number
        example: 1.0
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/SeasonBaseRecord'
                    type: array
                  status:
                    type: string
                type: object
              examples:
                GetAllSeasons200Example:
                  summary: Default getAllSeasons 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: 12345
                      image: https://artworks.thetvdb.com/banners/example.jpg
                      imageType: 1
                      lastUpdated: '2024-01-15'
                      name: Example Name
                      nameTranslations:
                      - example
                      number: 12345
                      overviewTranslations:
                      - example
                      companies:
                        studio:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: &id001
                          - example
                          overviewTranslations: &id002
                          - example
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        network:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id001
                          overviewTranslations: *id002
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        production:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id001
                          overviewTranslations: *id002
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        distributor:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id001
                          overviewTranslations: *id002
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        special_effects:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id001
                          overviewTranslations: *id002
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                      seriesId: 12345
                      type:
                        alternateName: example
                        id: 12345
                        name: Example Name
                        type: example
                      year: '2024'
                    status: Continuing
        '401':
          description: Unauthorized
      tags:
      - Seasons
      summary: TheTVDB Get All Seasons
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /seasons/{id}:
    get:
      description: Returns season base record
      operationId: getSeasonBase
      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/SeasonBaseRecord'
                  status:
                    type: string
                type: object
              examples:
                GetSeasonBase200Example:
                  summary: Default getSeasonBase 200 response
                  x-microcks-default: true
                  value:
                    data:
                      id: 12345
                      image: https://artworks.thetvdb.com/banners/example.jpg
                      imageType: 1
                      lastUpdated: '2024-01-15'
                      name: Example Name
                      nameTranslations:
                      - example
                      number: 12345
                      overviewTranslations:
                      - example
                      companies:
                        studio:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: &id003
                          - example
                          overviewTranslations: &id004
                          - example
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        network:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id003
                          overviewTranslations: *id004
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        production:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id003
                          overviewTranslations: *id004
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        distributor:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id003
                          overviewTranslations: *id004
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        special_effects:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id003
                          overviewTranslations: *id004
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                      seriesId: 12345
                      type:
                        alternateName: example
                        id: 12345
                        name: Example Name
                        type: example
                      year: '2024'
                    status: Continuing
        '400':
          description: Invalid season id
        '401':
          description: Unauthorized
        '404':
          description: Season not found
      tags:
      - Seasons
      summary: TheTVDB Get Season Base
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /seasons/{id}/extended:
    get:
      description: Returns season extended record
      operationId: getSeasonExtended
      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/SeasonExtendedRecord'
                  status:
                    type: string
                type: object
              examples:
                GetSeasonExtended200Example:
                  summary: Default getSeasonExtended 200 response
                  x-microcks-default: true
                  value:
                    data:
                      artwork:
                      - height: 12345
                        id: 12345
                        image: https://artworks.thetvdb.com/banners/example.jpg
                        includesText: true
                        language: eng
                        score: 100
                        thumbnail: example
                        type: 12345
                        width: 12345
                      companies:
                        studio:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: &id005
                          - example
                          overviewTranslations: &id006
                          - example
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        network:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id005
                          overviewTranslations: *id006
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        production:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id005
                          overviewTranslations: *id006
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        distributor:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id005
                          overviewTranslations: *id006
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                        special_effects:
                        - activeDate: '2024-01-15'
                          aliases:
                          - language: null
                            name: null
                          country: usa
                          id: 12345
                          inactiveDate: '2024-01-15'
                          name: Example Name
                          nameTranslations: *id005
                          overviewTranslations: *id006
                          primaryCompanyType: 12345
                          slug: example-slug
                          parentCompany:
                            id: null
                            name: null
                            relation: {}
                          tagOptions:
                          - helpText: null
                            id: null
                            name: null
                            tag: null
                            tagName: null
                      episodes:
                      - 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:
                        - example
                        number: 1
                        overview: A descriptive paragraph of text.
                        overviewTranslations:
                        - example
                        runtime: 1
                        seasonNumber: 1
                        seasons:
                        - id: 12345
                          image: https://artworks.thetvdb.com/banners/example.jpg
                          imageType: 1
                          lastUpdated: '2024-01-15'
                          name: Example Name
                          nameTranslations:
                          - example
                          number: 12345
                          overviewTranslations:
                          - example
                          companies:
                            studio:
                            - {}
                            network:
                            - {}
                            production:
                            - {}
                            distributor:
                            - {}
                            special_effects:
                            - {}
                          seriesId: 12345
                          type:
                            alternateName: null
                            id: null
                            name: null
                            type: null
                          year: '2024'
                        seriesId: 12345
                        seasonName: example
                        year: '2024'
                      id: 12345
                      image: https://artworks.thetvdb.com/banners/example.jpg
                      imageType: 1
                      lastUpdated: '2024-01-15'
                      name: Example Name
                      nameTranslations:
                      - example
                      number: 12345
                      overviewTranslations:
                      - example
                      seriesId: 12345
                      trailers:
                      - id: 12345
                        language: eng
                        name: Example Name
                        url: https://artworks.thetvdb.com/banners/example.jpg
                        runtime: 1
                      type:
                        alternateName: example
                        id: 12345
                        name: Example Name
                        type: example
                      tagOptions:
                      - helpText: example
                        id: 12345
                        name: Example Name
                        tag: 12345
                        tagName: example
                      translations:
                      - aliases:
                        - example
                        isAlias: true
                        isPrimary: true
                        language: eng
                        name: Example Name
                        overview: A descriptive paragraph of text.
                        tagline: example
                      year: '2024'
                    status: Continuing
        '400':
          description: Invalid seasons id
        '401':
          description: Unauthorized
        '404':
          description: Season not found
      tags:
      - Seasons
      summary: TheTVDB Get Season Extended
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /seasons/types:
    get:
      description: Returns season type records
      operationId: getSeasonTypes
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/SeasonType'
                    type: array
                  status:
                    type: string
                type: object
              examples:
                GetSeasonTypes200Example:
                  summary: Default getSeasonTypes 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - alternateName: example
                      id: 12345
                      name: Example Name
                      type: example
                    status: Continuing
        '401':
          description: Unauthorized
      tags:
      - Seasons
      summary: TheTVDB Get Season Types
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /seasons/{id}/translations/{language}:
    get:
      description: Returns season translation record
      operationId: getSeasonTranslation
      parameters:
      - description: id
        in: path
        name: id
        required: true
        schema:
          type: number
        example: 12345
      - description: language
        in: path
        name: language
        required: true
        schema:
          type: string
        example: eng
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/Translation'
                  status:
                    type: string
                type: object
              examples:
                GetSeasonTranslation200Example:
                  summary: Default getSeasonTranslation 200 response
                  x-microcks-default: true
                  value:
                    data:
                      aliases:
                      - example
                      isAlias: true
                      isPrimary: true
                      language: eng
                      name: Example Name
                      overview: A descriptive paragraph of text.
                      tagline: example
                    status: Continuing
        '400':
          description: Invalid season id, language not found.
        '401':
          description: Unauthorized
        '404':
          description: Season not found
      tags:
      - Seasons
      summary: TheTVDB Get Season Translation
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SeasonExtendedRecord:
      description: extended season record
      properties:
        artwork:
          items:
            $ref: '#/components/schemas/ArtworkBaseRecord'
          type: array
          x-go-name: Artwork
        companies:
          type: object
          $ref: '#/components/schemas/Companies'
        episodes:
          items:
            $ref: '#/components/schemas/EpisodeBaseRecord'
          type: array
          x-go-name: Episodes
        id:
          type: integer
          example: 12345
        image:
          type: string
          example: https://artworks.thetvdb.com/banners/example.jpg
        imageType:
          type: integer
          example: 1
        lastUpdated:
          type: string
          example: '2024-01-15'
        name:
          type: string
          example: Example Name
        nameTranslations:
          items:
            type: string
          type: array
          x-go-name: NameTranslations
          example:
          - example
        number:
          format: int64
          type: integer
          x-go-name: Number
          example: 12345
        overviewTranslations:
          items:
            type: string
          type: array
          x-go-name: OverviewTranslations
          example:
          - example
        seriesId:
          format: int64
          type: integer
          x-go-name: SeriesID
          example: 12345
        trailers:
          items:
            $ref: '#/components/schemas/Trailer'
          type: array
          x-go-name: Trailers
        type:
          $ref: '#/components/schemas/SeasonType'
        tagOptions:
          items:
            $ref: '#/components/schemas/TagOption'
          type: array
          x-go-name: TagOptions
        translations:
          items:
            $ref: '#/components/schemas/Translation'
          type: array
        year:
          type: string
          example: '2024'
      type: object
      x-go-package: github.com/whip-networks/tvdb-api-v4-core/tvdb-api-v4-core/pkg/model
    TagOption:
      description: tag option record
      properties:
        helpText:
          type: string
          example: example
        id:
          format: int64
          type: integer
          x-go-name: ID
          example: 12345
        name:
          type: string
          x-go-name: Name
          example: Example Name
        tag:
          format: int64
          type: integer
          x-go-name: Tag
          example: 12345
        tagName:
          type: string
          x-go-name: TagName
          example: example
      type: object
      x-go-package: github.com/whip-networks/tvdb-api-v4-core/tvdb-api-v4-core/pkg/model
    Translation:
      description: translation record
      properties:
        aliases:
          items:
            type: string
          type: array
          example:
          - example
        isAlias:
          type: boolean
          example: true
        isPrimary:
          type: boolean
          example: true
        language:
          type: string
          x-go-name: Language
          example: eng
        name:
          type: string
          example: Example Name
        overview:
          type: string
          example: A descriptive paragraph of text.
        tagline:
          type: string
          description: Only populated for movie translations.  We disallow taglines without a title.
          example: example
      type: object
      x-go-package: github.com/whip-networks/tvdb-api-v4-core/tvdb-api-v4-core/pkg/model
    SeasonBaseRecord:
      description: season genre record
      properties:
        id:
          type: integer
          example: 12345
        image:
          type: string
          example: https://artworks.thetvdb.com/banners/example.jpg
        imageType:
          type: integer
          example: 1
        lastUpdated:
          type: string
          example: '2024-01-15'
        name:
          type: string
          example: Example Name
        nameTranslations:
          items:
            type: string
          type: array
          x-go-name: NameTranslations
          example:
          - example
        number:
          format: int64
          type: integer
          x-go-name: Number
          example: 12345
        overviewTranslations:
          items:
            type: string
          type: array
          x-go-name: OverviewTranslations
          example:
          - example
        companies:
          type: object
          $ref: '#/components/schemas/

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