Trakt Scrobble API

openapi: 3.0.3
info:
  title: Trakt Calendars Scrobble 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: Scrobble
  description: Start, pause, and stop scrobbles for movies and episodes.
paths:
  /scrobble/start:
    post:
      tags:
      - Scrobble
      operationId: scrobbleStart
      summary: Start Watching In A Media Center
      description: Use when the video initially starts playing or is unpaused.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrobbleRequest'
      responses:
        '201':
          description: Scrobble started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrobbleResponse'
  /scrobble/pause:
    post:
      tags:
      - Scrobble
      operationId: scrobblePause
      summary: Pause Watching In A Media Center
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrobbleRequest'
      responses:
        '201':
          description: Scrobble paused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrobbleResponse'
  /scrobble/stop:
    post:
      tags:
      - Scrobble
      operationId: scrobbleStop
      summary: Stop Or Finish Watching In A Media Center
      description: If progress is above 80% the item is marked scrobble; if 1–79% it is treated as pause.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrobbleRequest'
      responses:
        '201':
          description: Scrobble stopped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrobbleResponse'
components:
  schemas:
    ScrobbleResponse:
      type: object
      properties:
        id:
          type: integer
        action:
          type: string
          enum:
          - start
          - pause
          - scrobble
        progress:
          type: number
        sharing:
          type: object
          properties:
            twitter:
              type: boolean
            mastodon:
              type: boolean
            tumblr:
              type: boolean
        movie:
          $ref: '#/components/schemas/Movie'
        episode:
          $ref: '#/components/schemas/Episode'
        show:
          $ref: '#/components/schemas/Show'
    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
    ScrobbleRequest:
      type: object
      required:
      - progress
      properties:
        progress:
          type: number
          minimum: 0
          maximum: 100
        movie:
          $ref: '#/components/schemas/Movie'
        episode:
          $ref: '#/components/schemas/Episode'
        app_version:
          type: string
        app_date:
          type: string
          format: date
    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
    Movie:
      type: object
      properties:
        title:
          type: string
        year:
          type: integer
        ids:
          $ref: '#/components/schemas/Ids'
        tagline:
          type: string
        overview:
          type: string
        released:
          type: string
          format: date
        runtime:
          type: integer
        country:
          type: string
        trailer:
          type: string
          format: uri
          nullable: true
        homepage:
          type: string
          format: uri
          nullable: true
        rating:
          type: number
        votes:
          type: integer
        comment_count:
          type: integer
        updated_at:
          type: string
          format: date-time
        language:
          type: string
        languages:
          type: array
          items:
            type: string
        available_translations:
          type: array
          items:
            type: string
        genres:
          type: array
          items:
            type: string
        certification:
          type: string
        status:
          type: string
          enum:
          - released
          - in production
          - post production
          - planned
          - rumored
          - canceled
  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).