openapi: 3.0.3
info:
  title: Trakt Calendars Shows API
  description: 'The Trakt API is a RESTful API for integrating TV show and movie tracking

    features into applications. It exposes Trakt''s media database, user

    watch history, lists, watchlists, ratings, comments, scrobbling, and

    recommendations. Authentication is OAuth 2.0 (Authorization Code and

    Device flows).


    This OpenAPI is a representative sampling of the full Trakt API v2

    surface, covering authentication, movies, shows, episodes, seasons,

    people, search, users, sync, scrobble, checkin, lists, calendars,

    recommendations, comments, notes, and reference data. The canonical

    contract is the ts-rest router published at github.com/trakt/trakt-api.

    '
  version: '2.0'
  contact:
    name: Trakt API Support
    url: https://forums.trakt.tv
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.trakt.tv
  description: Production
- url: https://api-staging.trakt.tv
  description: Staging
security:
- bearerAuth: []
tags:
- name: Shows
  description: Show metadata, trending, watched, anticipated, popular, progress, seasons, episodes.
paths:
  /shows/trending:
    get:
      tags:
      - Shows
      operationId: getTrendingShows
      summary: Get Trending Shows
      description: Returns the most watched shows over the last 24 hours.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Extended'
      responses:
        '200':
          description: Trending shows.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShowTrending'
  /shows/popular:
    get:
      tags:
      - Shows
      operationId: getPopularShows
      summary: Get Popular Shows
      description: Returns the most popular shows.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Extended'
      responses:
        '200':
          description: Popular shows.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Show'
  /shows/watched/{period}:
    get:
      tags:
      - Shows
      operationId: getMostWatchedShows
      summary: Get The Most Watched Shows
      description: Returns the most watched shows in the specified time period.
      parameters:
      - $ref: '#/components/parameters/Period'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Most watched shows.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShowWatched'
  /shows/anticipated:
    get:
      tags:
      - Shows
      operationId: getAnticipatedShows
      summary: Get The Most Anticipated Shows
      description: Returns the most anticipated shows based on the number of lists a show appears on.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Anticipated shows.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Show'
  /shows/{id}:
    get:
      tags:
      - Shows
      operationId: getShow
      summary: Get A Single Show
      description: Returns a single show's details.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      - $ref: '#/components/parameters/Extended'
      responses:
        '200':
          description: Show details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Show'
  /shows/{id}/seasons:
    get:
      tags:
      - Shows
      operationId: getShowSeasons
      summary: Get All Seasons For A Show
      description: Returns all seasons for a show including the number of episodes in each season.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      responses:
        '200':
          description: Show seasons.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Season'
  /shows/{id}/progress/watched:
    get:
      tags:
      - Shows
      operationId: getShowWatchedProgress
      summary: Get Show Watched Progress
      description: Returns watched progress for a show including details on all aired seasons and episodes.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      responses:
        '200':
          description: Watched progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowProgress'
  /shows/{id}/people:
    get:
      tags:
      - Shows
      operationId: getShowPeople
      summary: Get All People For A Show
      description: Returns all cast and crew for a show.
      parameters:
      - $ref: '#/components/parameters/ShowId'
      responses:
        '200':
          description: Show people.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/People'
components:
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        default: 10
      description: Items per page.
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number for pagination.
    Period:
      name: period
      in: path
      required: true
      schema:
        type: string
        enum:
        - daily
        - weekly
        - monthly
        - yearly
        - all
    ShowId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Trakt ID, Trakt slug, IMDB ID, TMDB ID, or TVDB ID.
    Extended:
      name: extended
      in: query
      schema:
        type: string
        enum:
        - full
        - metadata
        - noseasons
        - images
        - episodes
        - guest_stars
        - vip
      description: Request extra fields in the response.
  schemas:
    Episode:
      type: object
      properties:
        season:
          type: integer
        number:
          type: integer
        title:
          type: string
        ids:
          $ref: '#/components/schemas/Ids'
        number_abs:
          type: integer
          nullable: true
        overview:
          type: string
        first_aired:
          type: string
          format: date-time
          nullable: true
        runtime:
          type: integer
        episode_type:
          type: string
          enum:
          - standard
          - series_premiere
          - season_premiere
          - mid_season_finale
          - mid_season_premiere
          - season_finale
          - series_finale
    ShowWatched:
      type: object
      properties:
        watcher_count:
          type: integer
        play_count:
          type: integer
        collected_count:
          type: integer
        show:
          $ref: '#/components/schemas/Show'
    People:
      type: object
      properties:
        cast:
          type: array
          items:
            type: object
            properties:
              characters:
                type: array
                items:
                  type: string
              person:
                $ref: '#/components/schemas/Person'
        crew:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                jobs:
                  type: array
                  items:
                    type: string
                person:
                  $ref: '#/components/schemas/Person'
    ShowTrending:
      type: object
      properties:
        watchers:
          type: integer
        show:
          $ref: '#/components/schemas/Show'
    Person:
      type: object
      properties:
        name:
          type: string
        ids:
          $ref: '#/components/schemas/Ids'
        biography:
          type: string
        birthday:
          type: string
          format: date
          nullable: true
        death:
          type: string
          format: date
          nullable: true
        birthplace:
          type: string
          nullable: true
        homepage:
          type: string
          format: uri
          nullable: true
    Season:
      type: object
      properties:
        number:
          type: integer
        ids:
          $ref: '#/components/schemas/Ids'
        episode_count:
          type: integer
        aired_episodes:
          type: integer
        title:
          type: string
        overview:
          type: string
        first_aired:
          type: string
          format: date-time
          nullable: true
        network:
          type: string
          nullable: true
    Ids:
      type: object
      properties:
        trakt:
          type: integer
        slug:
          type: string
        imdb:
          type: string
        tmdb:
          type: integer
        tvdb:
          type: integer
    Show:
      type: object
      properties:
        title:
          type: string
        year:
          type: integer
        ids:
          $ref: '#/components/schemas/Ids'
        overview:
          type: string
        first_aired:
          type: string
          format: date-time
        runtime:
          type: integer
        certification:
          type: string
        network:
          type: string
        country:
          type: string
        trailer:
          type: string
          format: uri
          nullable: true
        homepage:
          type: string
          format: uri
          nullable: true
        status:
          type: string
          enum:
          - returning series
          - continuing
          - in production
          - planned
          - upcoming
          - pilot
          - canceled
          - ended
        rating:
          type: number
        votes:
          type: integer
        comment_count:
          type: integer
        updated_at:
          type: string
          format: date-time
        language:
          type: string
        genres:
          type: array
          items:
            type: string
        aired_episodes:
          type: integer
    ShowProgress:
      type: object
      properties:
        aired:
          type: integer
        completed:
          type: integer
        last_watched_at:
          type: string
          format: date-time
          nullable: true
        reset_at:
          type: string
          format: date-time
          nullable: true
        seasons:
          type: array
          items:
            type: object
            properties:
              number:
                type: integer
              aired:
                type: integer
              completed:
                type: integer
              episodes:
                type: array
                items:
                  type: object
                  properties:
                    number:
                      type: integer
                    completed:
                      type: boolean
                    last_watched_at:
                      type: string
                      format: date-time
                      nullable: true
        hidden_seasons:
          type: array
          items:
            $ref: '#/components/schemas/Season'
        next_episode:
          $ref: '#/components/schemas/Episode'
        last_episode:
          $ref: '#/components/schemas/Episode'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token from /oauth/token or /oauth/device/token. Send via Authorization header and required headers trakt-api-version (2) and trakt-api-key (client_id).