TVmaze Schedule API

openapi: 3.0.0
info:
  title: TVmaze Premium User auth Schedule API
  description: 'Premium-only user API for TVmaze. Access is restricted to users with a paid

    [Premium subscription](https://www.tvmaze.com/premium). A user can only access

    their own data.


    Authentication uses HTTP Basic: the TVmaze username is the basic-auth username and

    the API key (visible on the user dashboard) is the basic-auth password. There is

    also a device-style auth-pairing flow exposed at `/auth/start` and `/auth/poll`.

    '
  version: '1.0'
  contact:
    name: TVmaze
    url: https://www.tvmaze.com
  license:
    name: CC BY-SA 4.0
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://api.tvmaze.com/v1
- url: http://api.tvmaze.com/v1
security:
- usertoken: []
tags:
- name: Schedule
  description: Daily and rolling TV and web/streaming schedules.
paths:
  /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: null
                    image: null
                    summary: null
                    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: null
                      officialSite: null
                      schedule:
                        time: 00:00
                        days:
                        - Monday
                        - Tuesday
                        - Wednesday
                        - Thursday
                        - Friday
                      rating:
                        average: null
                      weight: 55
                      network:
                        id: 40
                        name: CNN
                        country:
                          name: United States
                          code: US
                          timezone: America/New_York
                        officialSite: null
                      webChannel: null
                      dvdCountry: null
                      externals:
                        tvrage: null
                        thetvdb: null
                        imdb: null
                      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: null
                    image: null
                    summary: null
                    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: null
                      officialSite: https://www.bloomberg.com/btv/series/the-opening-trade
                      schedule:
                        time: 02:00
                        days:
                        - Monday
                        - Tuesday
                        - Wednesday
                        - Thursday
                        - Friday
                      rating:
                        average: null
                      weight: 57
                      network:
                        id: 172
                        name: Bloomberg TV
                        country:
                          name: United States
                          code: US
                          timezone: America/New_York
                        officialSite: null
                      webChannel: null
                      dvdCountry: null
                      externals:
                        tvrage: null
                        thetvdb: null
                        imdb: null
                      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'
components:
  schemas:
    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'
    Links:
      type: object
      additionalProperties:
        type: object
        properties:
          href:
            type: string
            format: uri
          name:
            type: string
    Rating:
      type: object
      properties:
        average:
          type: number
          nullable: true
    Image:
      type: object
      properties:
        medium:
          type: string
          format: uri
        original:
          type: string
          format: uri
  securitySchemes:
    usertoken:
      scheme: basic
      type: http