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/Companies' seriesId: format: int64 type: integer x-go-name: SeriesID example: 12345 type: $ref: '#/components/schemas/SeasonType' year: type: string example: '2024' type: object x-go-package: github.com/whip-networks/tvdb-api-v4-core/tvdb-api-v4-core/pkg/model Company: description: A company record properties: activeDate: type: string example: '2024-01-15' aliases: items: $ref: '#/components/schemas/Alias' type: array x-go-name: Aliases country: type: string example: usa id: format: int64 type: integer x-go-name: ID example: 12345 inactiveDate: type: string example: '2024-01-15' name: type: string example: Example Name nameTranslations: items: type: string type: array x-go-name: NameTranslations example: - example overviewTranslations: items: type: string type: array x-go-name: OverviewTranslations example: - example primaryCompanyType: format: int64 type: integer x-go-name: PrimaryCompanyType nullable: true example: 12345 slug: type: string x-go-name: Slug example: example-slug parentCompany: type: object $ref: '#/components/schemas/ParentCompany' tagOptions: items: $ref: '#/components/schemas/TagOption' type: array x-go-name: TagOptions type: object x-go-package: github.com/whip-networks/tvdb-api-v4-core/tvdb-api-v4-core/pkg/model Alias: description: An alias model, which can be associated with a series, season, movie, person, or list. properties: language: type: string maximum: 4 description: A 3-4 character string indicating the language of the alias, as defined in Language. example: eng name: type: string maximum: 100 description: A string containing the alias itself. example: Example Name type: object CompanyRelationShip: description: A company relationship properties: id: type: integer nullable: true example: 12345 typeName: type: string example: example SeasonType: description: season type record properties: alternateName: type: string x-go-name: Name example: example id: format: int64 type: integer x-go-name: ID example: 12345 name: type: string x-go-name: Name example: Example Name type: type: string x-go-name: Type example: example type: object x-go-package: github.com/whip-networks/tvdb-api-v4-core/tvdb-api-v4-core/pkg/model Trailer: description: trailer record properties: id: format: int64 type: integer x-go-name: ID example: 12345 language: type: string example: eng name: type: string example: Example Name url: type: string example: https://artworks.thetvdb.com/banners/example.jpg runtime: type: integer example: 1 type: object x-go-package: github.com/whip-networks/tvdb-api-v4-core/tvdb-api-v4-core/pkg/model EpisodeBaseRecord: description: base episode record properties: absoluteNumber: type: integer example: 1 aired: type: string example: example airsAfterSeason: type: integer example: 1 airsBeforeEpisode: type: integer example: 1 airsBeforeSeason: type: integer example: 1 finaleType: description: season, midseason, or series type: string example: example id: format: int64 type: integer x-go-name: ID example: 12345 image: type: string example: https://artworks.thetvdb.com/banners/example.jpg imageType: type: integer nullable: true example: 1 isMovie: format: int64 type: integer x-go-name: IsMovie example: 12345 lastUpdated: type: string example: '2024-01-15' linkedMovie: type: integer example: 1 name: type: string example: Example Name nameTranslations: items: type: string type: array x-go-name: NameTranslations example: - example number: type: integer example: 1 overview: type: string example: A descriptive paragraph of text. overviewTranslations: items: type: string type: array x-go-name: OverviewTranslations example: - example runtime: type: integer nullable: true example: 1 seasonNumber: type: integer example: 1 seasons: items: $ref: '#/components/schemas/SeasonBaseRecord' type: array x-go-name: Seasons seriesId: format: int64 type: integer x-go-name: SeriesID example: 12345 seasonName: type: string example: example year: type: string example: '2024' type: object x-go-package: github.com/whip-networks/tvdb-api-v4-core/tvdb-api-v4-core/pkg/model Companies: description: Companies by type record properties: studio: type: array items: $ref: '#/components/schemas/Company' network: type: array items: $ref: '#/components/schemas/Company' production: type: array items: $ref: '#/components/schemas/Company' distributor: type: array items: $ref: '#/components/schemas/Company' special_effects: type: array items: $ref: '#/components/schemas/Company' ArtworkBaseRecord: description: base artwork record properties: height: format: int64 type: integer x-go-name: Height example: 12345 id: type: integer example: 12345 image: type: string x-go-name: Image example: https://artworks.thetvdb.com/banners/example.jpg includesText: type: boolean example: true language: type: string example: eng score: type: number example: 100 thumbnail: type: string x-go-name: Thumbnail example: example type: format: int64 type: integer x-go-name: Type description: The artwork type corresponds to the ids from the /artwork/types endpoint. example: 12345 width: format: int64 type: integer x-go-name: Width example: 12345 type: object x-go-package: github.com/whip-networks/tvdb-api-v4-core/tvdb-api-v4-core/pkg/model ParentCompany: description: A parent company record type: object properties: id: type: integer nullable: true example: 12345 name: type: string example: Example Name relation: type: object $ref: '#/components/schemas/CompanyRelationShip' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT