openapi: 3.0.3
info:
  title: TVmaze Public API
  description: |
    The TVmaze API is a free RESTful API that returns rich television show, episode, season,
    cast, crew, and schedule data. The public endpoints require no authentication and are
    licensed under CC BY-SA — attribution to tvmaze.com is required. A paid Premium tier
    unlocks a separate user-scoped API documented as `tvmaze-premium-openapi.yml`.

    Rate limit: at least 20 calls every 10 seconds per IP. HTTP 429 indicates the limit
    was exceeded.
  version: '1.0'
  contact:
    name: TVmaze
    url: https://www.tvmaze.com/api
  license:
    name: CC BY-SA 4.0
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://api.tvmaze.com
  description: Production API (HTTPS)
- url: http://api.tvmaze.com
  description: Production API (HTTP)
tags:
- name: Search
  description: Free-text search and lookup endpoints for shows and people.
- name: Schedule
  description: Daily and rolling TV and web/streaming schedules.
- name: Shows
  description: Show metadata, episodes, seasons, cast, crew, images, and aliases.
- name: Episodes
  description: Individual episode details including guest cast and crew.
- name: Seasons
  description: Season-level metadata and episode listings.
- name: People
  description: Person profiles, cast credits, and crew credits.
- name: Updates
  description: Bulk timestamps useful for incremental sync of shows and people.
paths:
  /search/shows:
    get:
      tags: [Search]
      operationId: searchShows
      summary: Search Shows
      description: Search for shows using a fuzzy text query.
      parameters:
      - name: q
        in: query
        required: true
        schema: {type: string}
        description: Search query string.
      responses:
        '200':
          description: List of show search hits scored by match.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    score: {type: number}
                    show: {$ref: '#/components/schemas/Show'}
              examples:
                default:
                  summary: Example response for /search/shows
                  value:
                  - score: 0.902979
                    show:
                      id: 139
                      url: https://www.tvmaze.com/shows/139/girls
                      name: Girls
                      type: Scripted
                      language: English
                      genres:
                      - Drama
                      - Romance
                      status: Ended
                      runtime: 30
                      averageRuntime: 30
                      premiered: '2012-04-15'
                      ended: '2017-04-16'
                      officialSite: http://www.hbo.com/girls
                      schedule:
                        time: 22:00
                        days:
                        - Sunday
                      rating:
                        average: 6.5
                      weight: 98
                      network:
                        id: 8
                        name: HBO
                        country:
                          name: United States
                          code: US
                          timezone: America/New_York
                        officialSite: https://www.hbo.com/
                      webChannel:
                      dvdCountry:
                      externals:
                        tvrage: 30124
                        thetvdb: 220411
                        imdb: tt1723816
                      image:
                        medium: https://static.tvmaze.com/uploads/images/medium_portrait/31/78286.jpg
                        original: https://static.tvmaze.com/uploads/images/original_untouched/31/78286.jpg
                      summary: <p>This Emmy winning series is a comic look at the assorted humiliations and rare triumphs of a group of girls in their 20s.</p>
                      updated: 1704794122
                      _links:
                        self:
                          href: https://api.tvmaze.com/shows/139
                        previousepisode:
                          href: https://api.tvmaze.com/episodes/1079686
                          name: Latching
                  - score: 0.8784869
                    show:
                      id: 41734
                      url: https://www.tvmaze.com/shows/41734/girls
                      name: GIRLS
                      type: Scripted
                      language: Mongolian
                      genres:
                      - Comedy
                      status: Ended
                      runtime: 41
                      averageRuntime: 41
                      premiered: '2018-06-15'
                      ended: '2019-10-14'
                      officialSite: https://www.ubstv.mn/tech-blog/index1.html
                      schedule:
                        time: ''
                        days:
                        - Thursday
                      rating:
                        average:
                      weight: 59
                      network:
                        id: 1672
                        name: UBS
                        country:
                          name: Mongolia
                          code: MN
                          timezone: Asia/Ulaanbaatar
                        officialSite:
                      webChannel:
                      dvdCountry:
                      externals:
                        tvrage:
                        thetvdb:
                        imdb: tt8709752
                      image:
                        medium: https://static.tvmaze.com/uploads/images/medium_portrait/191/478539.jpg
                        original: https://static.tvmaze.com/uploads/images/original_untouched/191/478539.jpg
                      summary:
                      updated: 1743150150
                      _links:
                        self:
                          href: https://api.tvmaze.com/shows/41734
                        previousepisode:
                          href: https://api.tvmaze.com/episodes/3187423
                          name: Episode 1
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /singlesearch/shows:
    get:
      tags: [Search]
      operationId: singleSearchShows
      summary: Single Search Shows
      description: Return the single best matching show for a query, optionally embedding related data.
      parameters:
      - name: q
        in: query
        required: true
        schema: {type: string}
      - name: embed
        in: query
        required: false
        schema: {type: string, enum: [episodes, cast]}
      responses:
        '200':
          description: A single show record.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Show'}
        '404': {description: Not Found}
  /lookup/shows:
    get:
      tags: [Search]
      operationId: lookupShows
      summary: Lookup Shows By External ID
      description: Look up a show using a TVRage, TheTVDB, or IMDb identifier.
      parameters:
      - name: tvrage
        in: query
        required: false
        schema: {type: integer}
      - name: thetvdb
        in: query
        required: false
        schema: {type: integer}
      - name: imdb
        in: query
        required: false
        schema: {type: string}
      responses:
        '200':
          description: Matching show.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Show'}
        '404': {description: Not Found}
  /search/people:
    get:
      tags: [Search]
      operationId: searchPeople
      summary: Search People
      description: Search for people (actors, crew) using a fuzzy text query.
      parameters:
      - name: q
        in: query
        required: true
        schema: {type: string}
      responses:
        '200':
          description: List of person search hits.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    score: {type: number}
                    person: {$ref: '#/components/schemas/Person'}
  /schedule:
    get:
      tags: [Schedule]
      operationId: getSchedule
      summary: Get Schedule
      description: Return the TV schedule for a country on a given date.
      parameters:
      - name: country
        in: query
        required: false
        schema: {type: string}
        description: ISO 3166-1 alpha-2 country code (default US).
      - name: date
        in: query
        required: false
        schema: {type: string, format: date}
        description: ISO 8601 date (default today).
      responses:
        '200':
          description: Array of scheduled episodes.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Episode'}
              examples:
                default:
                  summary: Example response for /schedule
                  value:
                  - id: 3623136
                    url: https://www.tvmaze.com/episodes/3623136/the-story-is-with-elex-michaelson-2026-05-29-episode-105
                    name: Episode 105
                    season: 2026
                    number: 105
                    type: regular
                    airdate: '2026-05-29'
                    airtime: 00:00
                    airstamp: '2026-05-30T04:00:00+00:00'
                    runtime: 120
                    rating:
                      average:
                    image:
                    summary:
                    show:
                      id: 87855
                      url: https://www.tvmaze.com/shows/87855/the-story-is-with-elex-michaelson
                      name: The Story Is with Elex Michaelson
                      type: News
                      language: English
                      genres: []
                      status: Running
                      runtime: 120
                      averageRuntime: 123
                      premiered: '2025-10-27'
                      ended:
                      officialSite:
                      schedule:
                        time: 00:00
                        days:
                        - Monday
                        - Tuesday
                        - Wednesday
                        - Thursday
                        - Friday
                      rating:
                        average:
                      weight: 55
                      network:
                        id: 40
                        name: CNN
                        country:
                          name: United States
                          code: US
                          timezone: America/New_York
                        officialSite:
                      webChannel:
                      dvdCountry:
                      externals:
                        tvrage:
                        thetvdb:
                        imdb:
                      image:
                        medium: https://static.tvmaze.com/uploads/images/medium_portrait/614/1536142.jpg
                        original: https://static.tvmaze.com/uploads/images/original_untouched/614/1536142.jpg
                      summary: <p><b>The Story Is</b> will feature live nightly panels and debates on set featuring a range of voices including attorneys Gloria Allred and Areva Martin, conservative talk radio hosts Larry Elder and Jennifer Horn, progressive podcast host Brian Tyler Cohen, former California GOP chair Jessica Millan Patterson and journalists Peter Hamby from Puck and POLITICO's Melanie Mason.</p>
                      updated: 1779503802
                      _links:
                        self:
                          href: https://api.tvmaze.com/shows/87855
                        previousepisode:
                          href: https://api.tvmaze.com/episodes/3623136
                          name: Episode 105
                        nextepisode:
                          href: https://api.tvmaze.com/episodes/3623137
                          name: Episode 106
                    _links:
                      self:
                        href: https://api.tvmaze.com/episodes/3623136
                      show:
                        href: https://api.tvmaze.com/shows/87855
                        name: The Story Is with Elex Michaelson
                  - id: 3624338
                    url: https://www.tvmaze.com/episodes/3624338/bloomberg-the-opening-trade-2026-05-29-episode-106
                    name: Episode 106
                    season: 2026
                    number: 106
                    type: regular
                    airdate: '2026-05-29'
                    airtime: 02:00
                    airstamp: '2026-05-30T06:00:00+00:00'
                    runtime: 120
                    rating:
                      average:
                    image:
                    summary:
                    show:
                      id: 85938
                      url: https://www.tvmaze.com/shows/85938/bloomberg-the-opening-trade
                      name: Bloomberg The Opening Trade
                      type: News
                      language: English
                      genres: []
                      status: Running
                      runtime: 120
                      averageRuntime: 115
                      premiered: '2024-07-01'
                      ended:
                      officialSite: https://www.bloomberg.com/btv/series/the-opening-trade
                      schedule:
                        time: 02:00
                        days:
                        - Monday
                        - Tuesday
                        - Wednesday
                        - Thursday
                        - Friday
                      rating:
                        average:
                      weight: 57
                      network:
                        id: 172
                        name: Bloomberg TV
                        country:
                          name: United States
                          code: US
                          timezone: America/New_York
                        officialSite:
                      webChannel:
                      dvdCountry:
                      externals:
                        tvrage:
                        thetvdb:
                        imdb:
                      image:
                        medium: https://static.tvmaze.com/uploads/images/medium_portrait/578/1445883.jpg
                        original: https://static.tvmaze.com/uploads/images/original_untouched/578/1445883.jpg
                      summary: <p>Everything you need to know as markets open across Europe. With analysis you won't find anywhere else, we break down the biggest stories of the day and speak to top guests who have skin in the game. Hosted by Anna Edwards, Guy Johnson and Kriti Gupta.</p>
                      updated: 1779661117
                      _links:
                        self:
                          href: https://api.tvmaze.com/shows/85938
                        previousepisode:
                          href: https://api.tvmaze.com/episodes/3624338
                          name: Episode 106
                        nextepisode:
                          href: https://api.tvmaze.com/episodes/3624339
                          name: Episode 107
                    _links:
                      self:
                        href: https://api.tvmaze.com/episodes/3624338
                      show:
                        href: https://api.tvmaze.com/shows/85938
                        name: Bloomberg The Opening Trade
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /schedule/web:
    get:
      tags: [Schedule]
      operationId: getWebSchedule
      summary: Get Web Schedule
      description: Return the web/streaming schedule for a country (or worldwide) on a given date.
      parameters:
      - name: country
        in: query
        required: false
        schema: {type: string}
      - name: date
        in: query
        required: false
        schema: {type: string, format: date}
      responses:
        '200':
          description: Array of web-released episodes.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Episode'}
  /schedule/full:
    get:
      tags: [Schedule]
      operationId: getFullSchedule
      summary: Get Full Schedule
      description: Return all future scheduled episodes (large response, cached 24h).
      responses:
        '200':
          description: Array of future episodes.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Episode'}
  /shows:
    get:
      tags: [Shows]
      operationId: listShows
      summary: List Shows
      description: Paginated index of every show on TVmaze (250 per page).
      parameters:
      - name: page
        in: query
        required: false
        schema: {type: integer, minimum: 0}
      responses:
        '200':
          description: Array of shows for the requested page.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Show'}
        '404': {description: Page out of range}
  /shows/{id}:
    get:
      tags: [Shows]
      operationId: getShow
      summary: Get Show
      description: Return a single show, optionally embedding related resources.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      - name: embed
        in: query
        required: false
        schema:
          type: array
          items: {type: string, enum: [episodes, cast, seasons, nextepisode, previousepisode]}
        style: form
        explode: true
      responses:
        '200':
          description: Show record.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Show'}
              examples:
                default:
                  summary: Example response for /shows/{id}
                  value:
                    id: 1
                    url: https://www.tvmaze.com/shows/1/under-the-dome
                    name: Under the Dome
                    type: Scripted
                    language: English
                    genres:
                    - Drama
                    - Science-Fiction
                    - Thriller
                    status: Ended
                    runtime: 60
                    averageRuntime: 60
                    premiered: '2013-06-24'
                    ended: '2015-09-10'
                    officialSite: http://www.cbs.com/shows/under-the-dome/
                    schedule:
                      time: 22:00
                      days:
                      - Thursday
                    rating:
                      average: 6.6
                    weight: 99
                    network:
                      id: 2
                      name: CBS
                      country:
                        name: United States
                        code: US
                        timezone: America/New_York
                      officialSite: https://www.cbs.com/
                    webChannel:
                    dvdCountry:
                    externals:
                      tvrage: 25988
                      thetvdb: 264492
                      imdb: tt1553656
                    image:
                      medium: https://static.tvmaze.com/uploads/images/medium_portrait/610/1525272.jpg
                      original: https://static.tvmaze.com/uploads/images/original_untouched/610/1525272.jpg
                    summary: <p><b>Under the Dome</b> is the story of a small town that is suddenly and inexplicably sealed off from the rest of the world by an enormous transparent dome. The town's inhabitants must deal with surviving the post-apocalyptic conditions while searching for answers about the dome, where it came from and if and when it will go away.</p>
                    updated: 1769177765
                    _links:
                      self:
                        href: https://api.tvmaze.com/shows/1
                      previousepisode:
                        href: https://api.tvmaze.com/episodes/185054
                        name: The Enemy Within
        '404': {description: Not Found}
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /shows/{id}/episodes:
    get:
      tags: [Shows]
      operationId: getShowEpisodes
      summary: Get Show Episodes
      description: List every episode of a show, optionally including specials.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      - name: specials
        in: query
        required: false
        schema: {type: integer, enum: [0, 1]}
      responses:
        '200':
          description: Array of episodes.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Episode'}
              examples:
                default:
                  summary: Example response for /shows/{id}/episodes
                  value:
                  - id: 1
                    url: https://www.tvmaze.com/episodes/1/under-the-dome-1x01-pilot
                    name: Pilot
                    season: 1
                    number: 1
                    type: regular
                    airdate: '2013-06-24'
                    airtime: 22:00
                    airstamp: '2013-06-25T02:00:00+00:00'
                    runtime: 60
                    rating:
                      average: 7
                    image:
                      medium: https://static.tvmaze.com/uploads/images/medium_landscape/1/4388.jpg
                      original: https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg
                    summary: <p>When the residents of Chester's Mill find themselves trapped under a massive transparent dome with no way out, they struggle to survive as resources rapidly dwindle and panic quickly escalates.</p>
                    _links:
                      self:
                        href: https://api.tvmaze.com/episodes/1
                      show:
                        href: https://api.tvmaze.com/shows/1
                        name: Under the Dome
                  - id: 2
                    url: https://www.tvmaze.com/episodes/2/under-the-dome-1x02-the-fire
                    name: The Fire
                    season: 1
                    number: 2
                    type: regular
                    airdate: '2013-07-01'
                    airtime: 22:00
                    airstamp: '2013-07-02T02:00:00+00:00'
                    runtime: 60
                    rating:
                      average: 6.8
                    image:
                      medium: https://static.tvmaze.com/uploads/images/medium_landscape/1/4389.jpg
                      original: https://static.tvmaze.com/uploads/images/original_untouched/1/4389.jpg
                    summary: <p>While the residents of Chester's Mill face the uncertainty of life in the dome, panic is heightened when a house goes up in flames and their fire department is outside of the dome.</p>
                    _links:
                      self:
                        href: https://api.tvmaze.com/episodes/2
                      show:
                        href: https://api.tvmaze.com/shows/1
                        name: Under the Dome
                  - id: 3
                    url: https://www.tvmaze.com/episodes/3/under-the-dome-1x03-manhunt
                    name: Manhunt
                    season: 1
                    number: 3
                    type: regular
                    airdate: '2013-07-08'
                    airtime: 22:00
                    airstamp: '2013-07-09T02:00:00+00:00'
                    runtime: 60
                    rating:
                      average: 6.5
                    image:
                      medium: https://static.tvmaze.com/uploads/images/medium_landscape/1/4390.jpg
                      original: https://static.tvmaze.com/uploads/images/original_untouched/1/4390.jpg
                    summary: <p>When a former deputy goes rogue, Big Jim recruits Barbie to join the manhunt to keep the town safe. Meanwhile, Junior is determined to escape the dome by going underground.</p>
                    _links:
                      self:
                        href: https://api.tvmaze.com/episodes/3
                      show:
                        href: https://api.tvmaze.com/shows/1
                        name: Under the Dome
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /shows/{id}/episodebynumber:
    get:
      tags: [Shows]
      operationId: getShowEpisodeByNumber
      summary: Get Show Episode By Number
      description: Return the specific episode for a show by season and episode number.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      - name: season
        in: query
        required: true
        schema: {type: integer}
      - name: number
        in: query
        required: true
        schema: {type: integer}
      responses:
        '200':
          description: Episode record.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Episode'}
  /shows/{id}/episodesbydate:
    get:
      tags: [Shows]
      operationId: getShowEpisodesByDate
      summary: Get Show Episodes By Date
      description: Return episodes that aired on a specific date for a show.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      - name: date
        in: query
        required: true
        schema: {type: string, format: date}
      responses:
        '200':
          description: Array of episodes.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Episode'}
  /shows/{id}/seasons:
    get:
      tags: [Shows]
      operationId: getShowSeasons
      summary: Get Show Seasons
      description: Return the list of seasons for a show.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      responses:
        '200':
          description: Array of seasons.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Season'}
              examples:
                default:
                  summary: Example response for /shows/{id}/seasons
                  value:
                  - id: 1
                    url: https://www.tvmaze.com/seasons/1/under-the-dome-season-1
                    number: 1
                    name: ''
                    episodeOrder: 13
                    premiereDate: '2013-06-24'
                    endDate: '2013-09-16'
                    network:
                      id: 2
                      name: CBS
                      country:
                        name: United States
                        code: US
                        timezone: America/New_York
                      officialSite: https://www.cbs.com/
                    webChannel:
                    image:
                      medium: https://static.tvmaze.com/uploads/images/medium_portrait/24/60941.jpg
                      original: https://static.tvmaze.com/uploads/images/original_untouched/24/60941.jpg
                    summary: ''
                    _links:
                      self:
                        href: https://api.tvmaze.com/seasons/1
                  - id: 2
                    url: https://www.tvmaze.com/seasons/2/under-the-dome-season-2
                    number: 2
                    name: ''
                    episodeOrder: 13
                    premiereDate: '2014-06-30'
                    endDate: '2014-09-22'
                    network:
                      id: 2
                      name: CBS
                      country:
                        name: United States
                        code: US
                        timezone: America/New_York
                      officialSite: https://www.cbs.com/
                    webChannel:
                    image:
                      medium: https://static.tvmaze.com/uploads/images/medium_portrait/24/60942.jpg
                      original: https://static.tvmaze.com/uploads/images/original_untouched/24/60942.jpg
                    summary: ''
                    _links:
                      self:
                        href: https://api.tvmaze.com/seasons/2
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /shows/{id}/cast:
    get:
      tags: [Shows]
      operationId: getShowCast
      summary: Get Show Cast
      description: Return the main cast of a show.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      responses:
        '200':
          description: Array of cast entries.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/CastCredit'}
              examples:
                default:
                  summary: Example response for /shows/{id}/cast
                  value:
                  - person:
                      id: 1
                      url: https://www.tvmaze.com/people/1/mike-vogel
                      name: Mike Vogel
                      country:
                        name: United States
                        code: US
                        timezone: America/New_York
                      birthday: '1979-07-17'
                      deathday:
                      gender: Male
                      image:
                        medium: https://static.tvmaze.com/uploads/images/medium_portrait/0/1815.jpg
                        original: https://static.tvmaze.com/uploads/images/original_untouched/0/1815.jpg
                      updated: 1779526576
                      _links:
                        self:
                          href: https://api.tvmaze.com/people/1
                    character:
                      id: 1
                      url: https://www.tvmaze.com/characters/1/under-the-dome-dale-barbie-barbara
                      name: Dale "Barbie" Barbara
                      image:
                        medium: https://static.tvmaze.com/uploads/images/medium_portrait/0/3.jpg
                        original: https://static.tvmaze.com/uploads/images/original_untouched/0/3.jpg
                      _links:
                        self:
                          href: https://api.tvmaze.com/characters/1
                    self: false
                    voice: false
                  - person:
                      id: 2
                      url: https://www.tvmaze.com/people/2/rachelle-lefevre
                      name: Rachelle Lefevre
                      country:
                        name: Canada
                        code: CA
                        timezone: America/Toronto
                      birthday: '1979-02-01'
                      deathday:
                      gender: Female
                      image:
                        medium: https://static.tvmaze.com/uploads/images/medium_portrait/82/207417.jpg
                        original: https://static.tvmaze.com/uploads/images/original_untouched/82/207417.jpg
                      updated: 1748315017
                      _links:
                        self:
                          href: https://api.tvmaze.com/people/2
                    character:
                      id: 2
                      url: https://www.tvmaze.com/characters/2/under-the-dome-julia-shumway
                      name: Julia Shumway
                      image:
                        medium: https://static.tvmaze.com/uploads/images/medium_portrait/0/6.jpg
                        original: https://static.tvmaze.com/uploads/images/original_untouched/0/6.jpg
                      _links:
                        self:
                          href: https://api.tvmaze.com/characters/2
                    self: false
                    voice: false
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /shows/{id}/crew:
    get:
      tags: [Shows]
      operationId: getShowCrew
      summary: Get Show Crew
      description: Return the crew of a show.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      responses:
        '200':
          description: Array of crew entries.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/CrewCredit'}
  /shows/{id}/akas:
    get:
      tags: [Shows]
      operationId: getShowAkas
      summary: Get Show Akas
      description: Return alternate titles (also-known-as) for a show.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      responses:
        '200':
          description: Array of aliases.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Aka'}
  /shows/{id}/images:
    get:
      tags: [Shows]
      operationId: getShowImages
      summary: Get Show Images
      description: Return image assets associated with a show.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      responses:
        '200':
          description: Array of images.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Image'}
  /shows/{id}/alternatelists:
    get:
      tags: [Shows]
      operationId: getShowAlternateLists
      summary: Get Show Alternate Lists
      description: Return alternate episode orderings for a show.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      responses:
        '200':
          description: Array of alternate-list metadata.
          content:
            application/json:
              schema:
                type: array
                items: {type: object, additionalProperties: true}
  /seasons/{id}:
    get:
      tags: [Seasons]
      operationId: getSeason
      summary: Get Season
      description: Return a single season.
      parameters:
      - name: id
        in: path
        required: true
        schema: {type: integer}
      responses:
        '200':
          description: Season record.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Season'}
              examples:
                default:
                  summary: Example response for /seasons/{id}
                  value:
                    id: 1
                    url: https://www.tvmaze.com/seasons/1/under-the-dome-season-1
                    number: 1
                    name: ''
                    episodeOrder: 13
                    premiereDate: '2013-06-24'
                    endDate: '2013-09-16'
                    network:
                      id: 2
                      name: CBS
                      country:
                        name: United States
                        code: US
                        timezone: America/New_York
                      officialSite: https://www.cbs.com/
                    webChannel:
                    image:
                      medium: https://static.tvmaze.com/uploads/images/medium_portrait/24/60941.jpg
                      original: https://static.tvmaze.com/uploads/images/original_untouched/24/60941.jpg
                    summary: ''
                    _links:
                      self:
                        href: https://api.tvmaze.com/seasons/1
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /seasons/{id}/episodes:
    get:
      tags: [Seasons]
      operationId: getSeasonEpisodes
      summary: Get Season Episodes
      description: Return the episodes of a season.
      parameters:
      - name: id
        in: path
        required: true
        schema: {type: integer}
      responses:
        '200':
          description: Array of episodes.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Episode'}
  /episodes/{id}:
    get:
      tags: [Episodes]
      operationId: getEpisode
      summary: Get Episode
      description: Return a single episode, optionally embedding related resources.
      parameters:
      - name: id
        in: path
        required: true
        schema: {type: integer}
      - name: embed
        in: query
        required: false
        schema:
          type: array
          items: {type: string, enum: [show, guestcast, guestcrew]}
        style: form
        explode: true
      responses:
        '200':
          description: Episode record.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Episode'}
              examples:
                default:
                  summary: Example response for /episodes/{id}
                  value:
                    id: 1
                    url: https://www.tvmaze.com/episodes/1/under-the-dome-1x01-pilot
                    name: Pilot
                    season: 1
                    number: 1
                    type: regular
                    airdate: '2013-06-24'
                    airtime: 22:00
                    airstamp: '2013-06-25T02:00:00+00:00'
                    runtime: 60
                    rating:
                      average: 7
                    image:
                      medium: https://static.tvmaze.com/uploads/images/medium_landscape/1/4388.jpg
                      original: https://static.tvmaze.com/uploads/images/original_untouched/1/4388.jpg
                    summary: <p>When the residents of Chester's Mill find themselves trapped under a massive transparent dome with no way out, they struggle to survive as resources rapidly dwindle and panic quickly escalates.</p>
                    _links:
                      self:
                        href: https://api.tvmaze.com/episodes/1
                      show:
                        href: https://api.tvmaze.com/shows/1
                        name: Under the Dome
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /episodes/{id}/guestcast:
    get:
      tags: [Episodes]
      operationId: getEpisodeGuestCast
      summary: Get Episode Guest Cast
      description: Return the guest cast for an episode.
      parameters:
      - name: id
        in: path
        required: true
        schema: {type: integer}
      responses:
        '200':
          description: Array of guest-cast entries.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/CastCredit'}
  /episodes/{id}/guestcrew:
    get:
      tags: [Episodes]
      operationId: getEpisodeGuestCrew
      summary: Get Episode Guest Crew
      description: Return the guest crew for an episode.
      parameters:
      - name: id
        in: path
        required: true
        schema: {type: integer}
      responses:
        '200':
          description: Array of guest-crew entries.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/CrewCredit'}
  /people:
    get:
      tags: [People]
      operationId: listPeople
      summary: List People
      description: Paginated index of every person on TVmaze (1000 per page).
      parameters:
      - name: page
        in: query
        required: false
        schema: {type: integer, minimum: 0}
      responses:
        '200':
          description: Array of people.
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/Person'}
        '404': {description: Page out of range}
  /people/{id}:
    get:
      tags: [People]
      operationId: getPerson
      summary: Get Person
      description: Return a single person.
      parameters:
      - name: id
        in: path
        required: true
        schema: {type: integer}
      responses:
        '200':
          description: Person record.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Person'}
              examples:
                default:
                  summary: Example response for /people/{id}
                  value:
                    id: 1
                    url: https://www.tvmaze.com/people/1/mike-vogel
                    name: Mike Vogel
                    country:
                      name: United States
                      code: US
                      timezone: America/New_York
                    birthday: '1979-07-17'
                    deathday:
                    gender: Male
                    image:
                      medium: https://static.tvmaze.com/uploads/images/medium_portrait/0/1815.jpg
                      original: https://static.tvmaze.com/uploads/images/original_untouched/0/1815.jpg
                    updated: 1779526576
                    _links:
                      self:
                        href: https://api.tvmaze.com/people/1
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /people/{id}/castcredits:
    get:
      tags: [People]
      operationId: getPersonCastCredits
      summary: Get Person Cast Credits
      description: Return show-level cast credits for a person.
      parameters:
      - name: id
        in: path
        required: true
        schema: {type: integer}
      responses:
        '200':
          description: Array of cast credits.
          content:
            application/json:
              schema:
                type: array
                items: {type: object, additionalProperties: true}
  /people/{id}/crewcredits:
    get:
      tags: [People]
      operationId: getPersonCrewCredits
      summary: Get Person Crew Credits
      description: Return show-level crew credits for a person.
      parameters:
      - name: id
        in: path
        required: true
        schema: {type: integer}
      responses:
        '200':
          description: Array of crew credits.
          content:
            application/json:
              schema:
                type: array
                items: {type: object, additionalProperties: true}
  /people/{id}/guestcastcredits:
    get:
      tags: [People]
      operationId: getPersonGuestCastCredits
      summary: Get Person Guest Cast Credits
      description: Return episode-level guest cast credits for a person.
      parameters:
      - name: id
        in: path
        required: true
        schema: {type: integer}
      responses:
        '200':
          description: Array of guest cast credits.
          content:
            application/json:
              schema:
                type: array
                items: {type: object, additionalProperties: true}
  /updates/shows:
    get:
      tags: [Updates]
      operationId: getShowUpdates
      summary: Get Show Updates
      description: Return a map of show IDs to last-updated timestamps for incremental sync.
      parameters:
      - name: since
        in: query
        required: false
        schema: {type: string, enum: [day, week, month]}
      responses:
        '200':
          description: Object keyed by show ID with timestamp values.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {type: integer, format: int64}
              examples:
                default:
                  summary: Example response for /updates/shows
                  value:
                    '81': 1780096192
                    '240': 1780096286
                    '279': 1780134751
                    '289': 1780109768
                    '675': 1780088592
      x-microcks-operation:
        defaultExample: default
      x-microcks-default: default
  /updates/people:
    get:
      tags: [Updates]
      operationId: getPersonUpdates
      summary: Get Person Updates
      description: Return a map of person IDs to last-updated timestamps for incremental sync.
      parameters:
      - name: since
        in: query
        required: false
        schema: {type: string, enum: [day, week, month]}
      responses:
        '200':
          description: Object keyed by person ID with timestamp values.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {type: integer, format: int64}
components:
  parameters:
    ShowId:
      name: id
      in: path
      required: true
      schema: {type: integer}
      description: TVmaze show identifier.
  schemas:
    Country:
      type: object
      properties:
        name: {type: string}
        code: {type: string}
        timezone: {type: string}
    Network:
      type: object
      properties:
        id: {type: integer}
        name: {type: string}
        country: {$ref: '#/components/schemas/Country'}
        officialSite: {type: string, nullable: true}
    WebChannel:
      allOf:
      - $ref: '#/components/schemas/Network'
    Image:
      type: object
      properties:
        medium: {type: string, format: uri}
        original: {type: string, format: uri}
    Schedule:
      type: object
      properties:
        time: {type: string}
        days:
          type: array
          items: {type: string}
    Rating:
      type: object
      properties:
        average: {type: number, nullable: true}
    Externals:
      type: object
      properties:
        tvrage: {type: integer, nullable: true}
        thetvdb: {type: integer, nullable: true}
        imdb: {type: string, nullable: true}
    Links:
      type: object
      additionalProperties:
        type: object
        properties:
          href: {type: string, format: uri}
          name: {type: string}
    Show:
      type: object
      properties:
        id: {type: integer}
        url: {type: string, format: uri}
        name: {type: string}
        type: {type: string, description: "e.g. Scripted, Reality, Documentary"}
        language: {type: string, nullable: true}
        genres:
          type: array
          items: {type: string}
        status: {type: string, description: "e.g. Running, Ended, To Be Determined"}
        runtime: {type: integer, nullable: true}
        averageRuntime: {type: integer, nullable: true}
        premiered: {type: string, format: date, nullable: true}
        ended: {type: string, format: date, nullable: true}
        officialSite: {type: string, nullable: true}
        schedule: {$ref: '#/components/schemas/Schedule'}
        rating: {$ref: '#/components/schemas/Rating'}
        weight: {type: integer}
        network: {allOf: [$ref: '#/components/schemas/Network'], nullable: true}
        webChannel: {allOf: [$ref: '#/components/schemas/WebChannel'], nullable: true}
        dvdCountry: {allOf: [$ref: '#/components/schemas/Country'], nullable: true}
        externals: {$ref: '#/components/schemas/Externals'}
        image: {allOf: [$ref: '#/components/schemas/Image'], nullable: true}
        summary: {type: string, nullable: true, description: "HTML summary"}
        updated: {type: integer, format: int64}
        _links: {$ref: '#/components/schemas/Links'}
    Episode:
      type: object
      properties:
        id: {type: integer}
        url: {type: string, format: uri}
        name: {type: string}
        season: {type: integer}
        number: {type: integer, nullable: true}
        type: {type: string, description: "regular, significant_special, insignificant_special"}
        airdate: {type: string, format: date, nullable: true}
        airtime: {type: string, nullable: true}
        airstamp: {type: string, format: date-time, nullable: true}
        runtime: {type: integer, nullable: true}
        rating: {$ref: '#/components/schemas/Rating'}
        image: {allOf: [$ref: '#/components/schemas/Image'], nullable: true}
        summary: {type: string, nullable: true}
        _links: {$ref: '#/components/schemas/Links'}
    Season:
      type: object
      properties:
        id: {type: integer}
        url: {type: string, format: uri}
        number: {type: integer}
        name: {type: string}
        episodeOrder: {type: integer, nullable: true}
        premiereDate: {type: string, format: date, nullable: true}
        endDate: {type: string, format: date, nullable: true}
        network: {allOf: [$ref: '#/components/schemas/Network'], nullable: true}
        webChannel: {allOf: [$ref: '#/components/schemas/WebChannel'], nullable: true}
        image: {allOf: [$ref: '#/components/schemas/Image'], nullable: true}
        summary: {type: string, nullable: true}
        _links: {$ref: '#/components/schemas/Links'}
    Person:
      type: object
      properties:
        id: {type: integer}
        url: {type: string, format: uri}
        name: {type: string}
        country: {allOf: [$ref: '#/components/schemas/Country'], nullable: true}
        birthday: {type: string, format: date, nullable: true}
        deathday: {type: string, format: date, nullable: true}
        gender: {type: string, nullable: true}
        image: {allOf: [$ref: '#/components/schemas/Image'], nullable: true}
        updated: {type: integer, format: int64}
        _links: {$ref: '#/components/schemas/Links'}
    Character:
      type: object
      properties:
        id: {type: integer}
        url: {type: string, format: uri}
        name: {type: string}
        image: {allOf: [$ref: '#/components/schemas/Image'], nullable: true}
        _links: {$ref: '#/components/schemas/Links'}
    CastCredit:
      type: object
      properties:
        person: {$ref: '#/components/schemas/Person'}
        character: {$ref: '#/components/schemas/Character'}
        self: {type: boolean}
        voice: {type: boolean}
    CrewCredit:
      type: object
      properties:
        type: {type: string, description: "Crew role type, e.g. Director, Writer"}
        person: {$ref: '#/components/schemas/Person'}
    Aka:
      type: object
      properties:
        name: {type: string}
        country: {allOf: [$ref: '#/components/schemas/Country'], nullable: true}