Trakt

Trakt Sync API

History, watchlist, ratings, favorites, collection, playback progress.

GitHub OpenAPI

Documentation

📖
Documentation
https://trakt.docs.apiary.io/
📖
Authentication
https://trakt.docs.apiary.io/#reference/authentication-oauth
📖
APIReference
https://trakt.docs.apiary.io/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/openapi/trakt-sync-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/json-schema/trakt-movie-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/json-schema/trakt-show-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/json-schema/trakt-episode-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/json-schema/trakt-user-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/json-schema/trakt-scrobble-schema.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/json-structure/trakt-movie-structure.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/json-structure/trakt-show-structure.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/json-structure/trakt-history-structure.json

Other Resources

🔗
Examples
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/examples/trakt-getTrendingMovies-example.json
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/examples/trakt-getMovie-example.json
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/examples/trakt-generateDeviceCode-example.json
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/examples/trakt-pollDeviceToken-example.json
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/examples/trakt-scrobbleStart-example.json
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/examples/trakt-addToHistory-example.json
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/examples/trakt-searchText-example.json
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/trakt/refs/heads/main/examples/trakt-getShowWatchedProgress-example.json

OpenAPI Specification

trakt-sync-api-openapi.yml Raw ↑ 
openapi: 3.0.3
info:
  title: Trakt Calendars Sync 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: Sync
  description: History, watchlist, ratings, favorites, collection, playback progress.
paths:
  /sync/last_activities:
    get:
      tags:
      - Sync
      operationId: getLastActivities
      summary: Get Last Activity
      description: Returns timestamps for the last activity of each Sync resource, so apps can determine what to refresh.
      responses:
        '200':
          description: Last activities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastActivities'
  /sync/playback:
    get:
      tags:
      - Sync
      operationId: getPlaybackProgress
      summary: Get Playback Progress
      description: Returns paused and unfinished playback progress for the authenticated user.
      responses:
        '200':
          description: Playback progress.
  /sync/playback/{id}:
    delete:
      tags:
      - Sync
      operationId: removePlaybackItem
      summary: Remove A Playback Item
      description: Remove a playback item from a user's playback progress list.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Removed.
  /sync/collection/movies:
    get:
      tags:
      - Sync
      operationId: getCollectionMovies
      summary: Get Movie Collection
      description: Returns movies in the authenticated user collection.
      responses:
        '200':
          description: Movie collection.
  /sync/collection/shows:
    get:
      tags:
      - Sync
      operationId: getCollectionShows
      summary: Get Show Collection
      description: Returns shows in the authenticated user collection, including collected seasons and episodes.
      responses:
        '200':
          description: Show collection.
  /sync/collection:
    post:
      tags:
      - Sync
      operationId: addToCollection
      summary: Add Items To Collection
      description: Add items to a user's collection. Accepts movies, shows, seasons, episodes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMediaRequest'
      responses:
        '201':
          description: Added.
  /sync/collection/remove:
    post:
      tags:
      - Sync
      operationId: removeFromCollection
      summary: Remove Items From Collection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMediaRequest'
      responses:
        '200':
          description: Removed.
  /sync/watched/movies:
    get:
      tags:
      - Sync
      operationId: getWatchedMovies
      summary: Get Watched Movies
      description: Returns all movies a user has watched, sorted by most plays.
      responses:
        '200':
          description: Watched movies.
  /sync/watched/shows:
    get:
      tags:
      - Sync
      operationId: getWatchedShows
      summary: Get Watched Shows
      description: Returns all shows a user has watched, sorted by most plays.
      responses:
        '200':
          description: Watched shows.
  /sync/history:
    get:
      tags:
      - Sync
      operationId: getWatchedHistory
      summary: Get Watched History
      description: Returns movies and episodes that a user has watched, sorted by most recent.
      parameters:
      - name: type
        in: query
        schema:
          type: string
          enum:
          - movies
          - shows
          - seasons
          - episodes
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: History entries.
    post:
      tags:
      - Sync
      operationId: addToHistory
      summary: Add Items To Watched History
      description: Add items to a user's watch history.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMediaRequest'
      responses:
        '200':
          description: History add result.
  /sync/history/remove:
    post:
      tags:
      - Sync
      operationId: removeFromHistory
      summary: Remove Items From History
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMediaRequest'
      responses:
        '200':
          description: Removed.
  /sync/ratings:
    post:
      tags:
      - Sync
      operationId: addRatings
      summary: Add New Ratings
      description: Rate one or more items.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMediaRequest'
      responses:
        '201':
          description: Ratings added.
  /sync/ratings/remove:
    post:
      tags:
      - Sync
      operationId: removeRatings
      summary: Remove Ratings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMediaRequest'
      responses:
        '200':
          description: Ratings removed.
  /sync/watchlist:
    get:
      tags:
      - Sync
      operationId: getWatchlist
      summary: Get Watchlist
      description: Returns all items in a user's watchlist.
      responses:
        '200':
          description: Watchlist items.
    post:
      tags:
      - Sync
      operationId: addToWatchlist
      summary: Add Items To Watchlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMediaRequest'
      responses:
        '201':
          description: Watchlist add result.
  /sync/watchlist/remove:
    post:
      tags:
      - Sync
      operationId: removeFromWatchlist
      summary: Remove Items From Watchlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMediaRequest'
      responses:
        '200':
          description: Removed.
  /sync/favorites:
    get:
      tags:
      - Sync
      operationId: getFavorites
      summary: Get Favorites
      responses:
        '200':
          description: Favorites items.
    post:
      tags:
      - Sync
      operationId: addToFavorites
      summary: Add Items To Favorites
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMediaRequest'
      responses:
        '201':
          description: Favorites add result.
  /sync/favorites/remove:
    post:
      tags:
      - Sync
      operationId: removeFromFavorites
      summary: Remove Items From Favorites
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMediaRequest'
      responses:
        '200':
          description: Removed.
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.
  schemas:
    Ids:
      type: object
      properties:
        trakt:
          type: integer
        slug:
          type: string
        imdb:
          type: string
        tmdb:
          type: integer
        tvdb:
          type: integer
    LastActivities:
      type: object
      properties:
        all:
          type: string
          format: date-time
        movies:
          type: object
        episodes:
          type: object
        shows:
          type: object
        seasons:
          type: object
        comments:
          type: object
        lists:
          type: object
        watchlist:
          type: object
        favorites:
          type: object
        recommendations:
          type: object
    BulkMediaRequest:
      type: object
      properties:
        movies:
          type: array
          items:
            type: object
            properties:
              ids:
                $ref: '#/components/schemas/Ids'
              watched_at:
                type: string
                format: date-time
              rating:
                type: integer
                minimum: 1
                maximum: 10
        shows:
          type: array
          items:
            type: object
            properties:
              ids:
                $ref: '#/components/schemas/Ids'
        seasons:
          type: array
          items:
            type: object
        episodes:
          type: array
          items:
            type: object
            properties:
              ids:
                $ref: '#/components/schemas/Ids'
              watched_at:
                type: string
                format: date-time
        ids:
          type: array
          items:
            type: integer
  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).