openapi: 3.0.3
info:
  title: Trakt Calendars OAuth 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: OAuth
  description: Authorization Code and Device OAuth flows.
paths:
  /oauth/device/code:
    post:
      tags:
      - OAuth
      operationId: generateDeviceCode
      summary: Generate New Device Codes
      description: Generate new codes to start the device authentication process. The device_code and interval are used to poll for the access_token. The user_code and verification_url should be presented to the user.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceCodeRequest'
      responses:
        '200':
          description: Device code issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceCodeResponse'
  /oauth/device/token:
    post:
      tags:
      - OAuth
      operationId: pollDeviceToken
      summary: Poll For The Access Token
      description: Poll using the device_code at the returned interval until the user authorizes the app. Returns access_token on success. Status codes 400/404/409/410/418/429 indicate pending, expired, denied, or polling-too-fast states.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceTokenRequest'
      responses:
        '200':
          description: Token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Pending — keep polling.
  /oauth/token:
    post:
      tags:
      - OAuth
      operationId: exchangeToken
      summary: Exchange A Token
      description: Exchange an OAuth authorization code or refresh token for an access token.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/TokenRequest'
              - $ref: '#/components/schemas/TokenRefreshRequest'
      responses:
        '200':
          description: Token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Invalid request.
  /oauth/revoke:
    post:
      tags:
      - OAuth
      operationId: revokeToken
      summary: Revoke An Access Token
      description: Revoke an access_token when the user signs out of the app.
      security: []
      responses:
        '200':
          description: Token revoked.
components:
  schemas:
    DeviceCodeRequest:
      type: object
      required:
      - client_id
      properties:
        client_id:
          type: string
    DeviceTokenRequest:
      type: object
      required:
      - code
      - client_id
      - client_secret
      properties:
        code:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        refresh_token:
          type: string
        scope:
          type: string
        created_at:
          type: integer
    TokenRequest:
      type: object
      required:
      - code
      - client_id
      - client_secret
      - redirect_uri
      - grant_type
      properties:
        code:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
        redirect_uri:
          type: string
          format: uri
        grant_type:
          type: string
          enum:
          - authorization_code
    TokenRefreshRequest:
      type: object
      required:
      - refresh_token
      - client_id
      - client_secret
      - redirect_uri
      - grant_type
      properties:
        refresh_token:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
        redirect_uri:
          type: string
          format: uri
        grant_type:
          type: string
          enum:
          - refresh_token
    DeviceCodeResponse:
      type: object
      properties:
        device_code:
          type: string
        user_code:
          type: string
        verification_url:
          type: string
          format: uri
        expires_in:
          type: integer
        interval:
          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).