openapi: 3.0.3
info:
  title: Trakt Calendars Users 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: Users
  description: Profiles, settings, follows, friends, social activity, comments, watching.
paths:
  /users/settings:
    get:
      tags:
      - Users
      operationId: getUserSettings
      summary: Retrieve Settings
      description: Get the user's settings (account, profile, sharing, limits, permissions, browsing).
      responses:
        '200':
          description: User settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSettings'
  /users/{id}:
    get:
      tags:
      - Users
      operationId: getUserProfile
      summary: Get User Profile
      description: Get a user's profile information.
      parameters:
      - $ref: '#/components/parameters/UserSlug'
      - $ref: '#/components/parameters/Extended'
      responses:
        '200':
          description: User profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
  /users/{id}/stats:
    get:
      tags:
      - Users
      operationId: getUserStats
      summary: Get Stats
      description: Returns stats about the movies, shows, and episodes a user has watched, collected, and rated.
      parameters:
      - $ref: '#/components/parameters/UserSlug'
      responses:
        '200':
          description: User stats.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStats'
  /users/{id}/watching:
    get:
      tags:
      - Users
      operationId: getUserWatching
      summary: Get Watching
      description: Returns a movie or episode if the user is currently watching something.
      parameters:
      - $ref: '#/components/parameters/UserSlug'
      responses:
        '200':
          description: User watching.
        '204':
          description: User is not watching anything.
  /users/{id}/followers:
    get:
      tags:
      - Users
      operationId: getUserFollowers
      summary: Get Followers
      parameters:
      - $ref: '#/components/parameters/UserSlug'
      responses:
        '200':
          description: Followers list.
  /users/{id}/following:
    get:
      tags:
      - Users
      operationId: getUserFollowing
      summary: Get Following
      parameters:
      - $ref: '#/components/parameters/UserSlug'
      responses:
        '200':
          description: Following list.
  /users/{id}/friends:
    get:
      tags:
      - Users
      operationId: getUserFriends
      summary: Get Friends
      parameters:
      - $ref: '#/components/parameters/UserSlug'
      responses:
        '200':
          description: Friends list.
  /users/{id}/follow:
    post:
      tags:
      - Users
      operationId: followUser
      summary: Follow This User
      parameters:
      - $ref: '#/components/parameters/UserSlug'
      responses:
        '201':
          description: Follow created.
    delete:
      tags:
      - Users
      operationId: unfollowUser
      summary: Unfollow This User
      parameters:
      - $ref: '#/components/parameters/UserSlug'
      responses:
        '204':
          description: Unfollowed.
  /users/{id}/lists:
    get:
      tags:
      - Users
      operationId: getUserLists
      summary: Get A User's Custom Lists
      parameters:
      - $ref: '#/components/parameters/UserSlug'
      responses:
        '200':
          description: User lists.
    post:
      tags:
      - Users
      operationId: createUserList
      summary: Create A Custom List
      parameters:
      - $ref: '#/components/parameters/UserSlug'
      responses:
        '201':
          description: List created.
components:
  parameters:
    UserSlug:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: User slug or 'me' for the authenticated user.
    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:
    UserSettings:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserProfile'
        account:
          type: object
          properties:
            timezone:
              type: string
            date_format:
              type: string
            time_24hr:
              type: boolean
            cover_image:
              type: string
              format: uri
              nullable: true
            token:
              type: string
        sharing_text:
          type: object
        limits:
          type: object
        permissions:
          type: object
    UserProfile:
      type: object
      properties:
        username:
          type: string
        private:
          type: boolean
        deleted:
          type: boolean
        name:
          type: string
        vip:
          type: boolean
        vip_ep:
          type: boolean
        ids:
          type: object
          properties:
            slug:
              type: string
            uuid:
              type: string
    UserStats:
      type: object
      properties:
        movies:
          type: object
        shows:
          type: object
        seasons:
          type: object
        episodes:
          type: object
        network:
          type: object
        ratings:
          type: object
  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).