openapi: 3.0.0
info:
  title: TVmaze Premium User auth scrobbling 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: scrobbling
paths:
  /scrobble/episodes:
    post:
      description: This endpoint can be used by all users, even without premium
      requestBody:
        content:
          application/json:
            schema:
              items:
                properties:
                  episode_id:
                    description: The TVmaze episode ID
                    type: integer
                  marked_at:
                    description: Epoch timestamp for when the user watched the episode, or 0 for unknown.
                    type: integer
                  type:
                    $ref: '#/components/schemas/MarkType'
                type: object
              type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResponse'
          description: All episodes were succesfully marked
        '207':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResponse'
          description: Some episodes were succesfully marked, but there are errors
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResponse'
          description: None of the episodes were succesfully marked
      summary: Mark Episodes as Acquired or Watched Based on Their IDs
      tags:
      - scrobbling
  /scrobble/episodes/{episode_id}:
    parameters:
    - in: path
      name: episode_id
      required: true
      schema:
        type: integer
    put:
      description: This endpoint can be used by all users, even without premium
      requestBody:
        $ref: '#/components/requestBodies/MarkedEpisode'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkedEpisode'
          description: this episode is now marked
        '404':
          description: this episode does not exist
        '422':
          description: invalid input data
      summary: Mark an Episode as Acquired or Watched Based on Its ID
      tags:
      - scrobbling
  /scrobble/shows:
    post:
      description: 'To specify a show, supply either `tvmaze_id`, `thetvdb_id` or `imdb_id`. To specify an episode, supply either both `season` and `episode`, or `airdate`.


        This endpoint can be used by all users, even without premium.

        '
      parameters:
      - description: The show's TVmaze ID
        in: query
        name: tvmaze_id
        schema:
          type: integer
      - description: The show's TheTVDB ID
        in: query
        name: thetvdb_id
        schema:
          type: integer
      - description: The show's IMDB ID
        in: query
        name: imdb_id
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              items:
                properties:
                  airdate:
                    description: The episode airdate
                    format: date
                    type: string
                  episode:
                    description: The episode number
                    type: integer
                  marked_at:
                    description: Epoch timestamp for when the user watched the episode, or 0 for unknown.
                    type: integer
                  season:
                    description: The season number
                    type: integer
                  type:
                    $ref: '#/components/schemas/MarkType'
                type: object
              type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResponse'
          description: All episodes were succesfully marked
        '207':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResponse'
          description: Some episodes were succesfully marked, but there are errors
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkResponse'
          description: None of the episodes were succesfully marked
      summary: Mark Episodes Within a Show as Acquired or Watched Based on Their Attributes
      tags:
      - scrobbling
  /scrobble/shows/{show_id}:
    parameters:
    - description: ID of the target show
      in: path
      name: show_id
      required: true
      schema:
        type: integer
    - description: Embed full episode info
      in: query
      name: embed
      required: false
      schema:
        enum:
        - episode
        type: string
    get:
      description: This endpoint can be used by all users, even without premium
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/MarkedEpisode'
                type: array
          description: An array of marked episodes
      summary: List Watched and Acquired Episodes for a Show
      tags:
      - scrobbling
components:
  schemas:
    BulkResponse:
      description: A list of responses to your bulk input, ordered the same as your input
      items:
        properties:
          code:
            description: The HTTP code that corresponds to this item
            type: integer
          errors:
            description: A list of validation errors for this item (in case of error)
            type: object
          input:
            description: The request data that belonged to this response (in case of error)
            type: object
          message:
            description: A human-readable error message (in case of error)
            type: string
          result:
            description: The resulting created/updated object (in case of success)
            type: object
      type: array
    MarkedEpisode:
      properties:
        _embedded:
          properties:
            episode:
              $ref: '#/components/schemas/Episode'
          type: object
        episode_id:
          readOnly: true
          type: integer
        marked_at:
          description: Epoch timestamp for when the user watched the episode, or 0 for unknown.
          type: integer
        type:
          $ref: '#/components/schemas/MarkType'
      type: object
    Episode:
      type: object
    MarkType:
      description: 0 for watched, 1 for acquired, 2 for skipped
  requestBodies:
    MarkedEpisode:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MarkedEpisode'
  securitySchemes:
    usertoken:
      scheme: basic
      type: http