{
  "openapi": "3.1.0",
  "info": {
    "title": "Trakt.tv AI Connector",
    "version": "1.0.0",
    "description": "Comprehensive Trakt.tv AI Connector for ChatGPT and LLMs. Search movies/TV shows, check trending & popular content, manage watchlists, track watched history, rate titles, get personalized recommendations, check-in to active viewing, and sync user library.",
    "contact": {
      "name": "TraktGPT Support",
      "url": "https://traktgpt.pcro.eu"
    }
  },
  "servers": [
    {
      "url": "https://traktgpt.pcro.eu",
      "description": "Production TraktGPT Connector Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "TraktOAuth": {
        "type": "oauth2",
        "description": "Trakt.tv OAuth 2.0 Authorization Code Flow",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://traktgpt.pcro.eu/oauth/authorize",
            "tokenUrl": "https://traktgpt.pcro.eu/oauth/token",
            "scopes": {
              "public": "Full access to user watchlist, watch history, ratings, and profile"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "TraktOAuth": []
    }
  ],
  "paths": {
    "/api/search/movies": {
      "get": {
        "operationId": "searchMovies",
        "summary": "Search for movies",
        "description": "Search movies by title query, release year, genres, or language.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Movie title to search for (e.g. \"Inception\", \"Dune\")"
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "4-digit year of release"
          },
          {
            "name": "genres",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Genre slugs separated by commas (e.g. \"action,sci-fi\")"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Page number"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            },
            "description": "Results per page"
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching movies with synopsis, ratings, and IDs"
          }
        }
      }
    },
    "/api/search/shows": {
      "get": {
        "operationId": "searchShows",
        "summary": "Search for TV shows",
        "description": "Search TV shows by title query, release year, genres, or language.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Show title to search for (e.g. \"Breaking Bad\", \"Severance\")"
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Year of premiere"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Page number"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            },
            "description": "Results per page"
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching TV shows"
          }
        }
      }
    },
    "/api/search/id": {
      "get": {
        "operationId": "searchById",
        "summary": "Lookup item by external ID",
        "description": "Lookup a movie, show, or episode by IMDb ID (e.g. tt0133093), TMDB ID, or Trakt ID.",
        "parameters": [
          {
            "name": "id_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "imdb",
                "tmdb",
                "trakt",
                "tvdb"
              ]
            },
            "description": "ID type"
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID value (e.g. tt0133093)"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "movie",
                "show",
                "episode",
                "person"
              ]
            },
            "description": "Media type filter"
          }
        ],
        "responses": {
          "200": {
            "description": "Found media item"
          }
        }
      }
    },
    "/api/movies/trending": {
      "get": {
        "operationId": "getTrendingMovies",
        "summary": "Get trending movies",
        "description": "Returns top trending movies right now on Trakt with current watcher counts.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trending movies list"
          }
        }
      }
    },
    "/api/movies/popular": {
      "get": {
        "operationId": "getPopularMovies",
        "summary": "Get most popular movies",
        "description": "Returns the most popular movies on Trakt.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Popular movies list"
          }
        }
      }
    },
    "/api/movies/anticipated": {
      "get": {
        "operationId": "getAnticipatedMovies",
        "summary": "Get most anticipated upcoming movies",
        "description": "Returns the most anticipated upcoming movies.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Anticipated movies list"
          }
        }
      }
    },
    "/api/movies/boxoffice": {
      "get": {
        "operationId": "getBoxOfficeMovies",
        "summary": "Get current weekend box office",
        "description": "Returns top weekend box office revenue rankings.",
        "responses": {
          "200": {
            "description": "Box office rankings"
          }
        }
      }
    },
    "/api/movies/{id}": {
      "get": {
        "operationId": "getMovieDetails",
        "summary": "Get single movie details",
        "description": "Returns complete details for a movie including overview, runtime, rating, votes, trailer, genres, and certification.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Trakt ID, slug, or IMDb ID (e.g. \"inception-2010\" or \"tt1375666\")"
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed movie object"
          }
        }
      }
    },
    "/api/movies/{id}/related": {
      "get": {
        "operationId": "getRelatedMovies",
        "summary": "Get related movies",
        "description": "Returns similar and related movies for a given movie.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Related movies list"
          }
        }
      }
    },
    "/api/movies/{id}/comments": {
      "get": {
        "operationId": "getMovieComments",
        "summary": "Get movie reviews and user comments",
        "description": "Returns reviews, ratings, and user comments for a movie.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest",
                "likes",
                "replies"
              ],
              "default": "newest"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Comments list"
          }
        }
      }
    },
    "/api/shows/trending": {
      "get": {
        "operationId": "getTrendingShows",
        "summary": "Get trending TV shows",
        "description": "Returns top trending TV shows right now.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trending shows list"
          }
        }
      }
    },
    "/api/shows/popular": {
      "get": {
        "operationId": "getPopularShows",
        "summary": "Get most popular TV shows",
        "description": "Returns most popular TV shows on Trakt.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Popular shows list"
          }
        }
      }
    },
    "/api/shows/{id}": {
      "get": {
        "operationId": "getShowDetails",
        "summary": "Get single TV show details",
        "description": "Returns complete details for a TV show including status, network, overview, runtime, ratings, and genres.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Trakt ID, slug, or IMDb ID (e.g. \"game-of-thrones\" or \"tt0944947\")"
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed TV show object"
          }
        }
      }
    },
    "/api/shows/{id}/seasons": {
      "get": {
        "operationId": "getShowSeasons",
        "summary": "Get TV show seasons list",
        "description": "Returns list of all seasons for a show with episode counts and air dates.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Seasons list"
          }
        }
      }
    },
    "/api/shows/{id}/seasons/{season}": {
      "get": {
        "operationId": "getSeasonEpisodes",
        "summary": "Get episodes in a specific season",
        "description": "Returns all episodes in a given season with titles, overviews, ratings, and premiere dates.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "season",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Season number (e.g. 1)"
          }
        ],
        "responses": {
          "200": {
            "description": "Episodes list"
          }
        }
      }
    },
    "/api/shows/{id}/seasons/{season}/episodes/{episode}": {
      "get": {
        "operationId": "getEpisodeDetails",
        "summary": "Get single episode details",
        "description": "Returns detailed information for a specific episode.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "season",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "episode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Episode details"
          }
        }
      }
    },
    "/api/shows/{id}/next_episode": {
      "get": {
        "operationId": "getNextEpisode",
        "summary": "Get next upcoming episode",
        "description": "Returns the next upcoming episode scheduled to air for a show.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Next episode details"
          }
        }
      }
    },
    "/api/shows/{id}/last_episode": {
      "get": {
        "operationId": "getLastEpisode",
        "summary": "Get last aired episode",
        "description": "Returns the most recently aired episode for a show.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Last episode details"
          }
        }
      }
    },
    "/api/user/profile": {
      "get": {
        "operationId": "getUserProfile",
        "summary": "Get current user profile",
        "description": "Returns the authenticated user Trakt profile, VIP status, username, and account settings.",
        "responses": {
          "200": {
            "description": "User profile details"
          }
        }
      }
    },
    "/api/user/stats": {
      "get": {
        "operationId": "getUserStats",
        "summary": "Get current user watch stats",
        "description": "Returns total movies watched, shows watched, episodes watched, hours spent watching, and rating statistics.",
        "responses": {
          "200": {
            "description": "User statistics"
          }
        }
      }
    },
    "/api/watchlist": {
      "get": {
        "operationId": "getWatchlist",
        "summary": "Get user watchlist",
        "description": "Returns the authenticated user watchlist. Filter by type (movies, shows, seasons, episodes).",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "movies",
                "shows",
                "seasons",
                "episodes"
              ]
            },
            "description": "Filter by media type"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Watchlist items"
          }
        }
      },
      "post": {
        "operationId": "addToWatchlist",
        "summary": "Add item to user watchlist",
        "description": "Add a movie or show to the authenticated user watchlist.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "movie",
                      "show"
                    ],
                    "default": "movie"
                  },
                  "trakt_id": {
                    "type": "integer",
                    "description": "Trakt numeric ID"
                  },
                  "imdb_id": {
                    "type": "string",
                    "description": "IMDb ID (e.g. tt1375666)"
                  },
                  "title": {
                    "type": "string",
                    "description": "Title"
                  },
                  "year": {
                    "type": "integer",
                    "description": "Year"
                  },
                  "movies": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "shows": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Added items count confirmation"
          }
        }
      }
    },
    "/api/watchlist/remove": {
      "post": {
        "operationId": "removeFromWatchlist",
        "summary": "Remove item from user watchlist",
        "description": "Remove a movie or show from the user watchlist.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "movie",
                      "show"
                    ],
                    "default": "movie"
                  },
                  "trakt_id": {
                    "type": "integer"
                  },
                  "imdb_id": {
                    "type": "string"
                  },
                  "movies": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "shows": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Removal confirmation"
          }
        }
      }
    },
    "/api/history": {
      "get": {
        "operationId": "getWatchHistory",
        "summary": "Get user watch history",
        "description": "Returns recently watched movies, shows, or episodes with watched_at timestamps.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "movies",
                "shows",
                "seasons",
                "episodes"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Watch history list"
          }
        }
      },
      "post": {
        "operationId": "addToHistory",
        "summary": "Mark item as watched (add to history)",
        "description": "Mark a movie, show, or episode as watched on Trakt with optional timestamp.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "movie",
                      "show",
                      "episode"
                    ],
                    "default": "movie"
                  },
                  "trakt_id": {
                    "type": "integer"
                  },
                  "imdb_id": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "year": {
                    "type": "integer"
                  },
                  "watched_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "ISO 8601 timestamp (defaults to now)"
                  },
                  "movies": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "shows": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "episodes": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Marked as watched confirmation"
          }
        }
      }
    },
    "/api/history/remove": {
      "post": {
        "operationId": "removeFromHistory",
        "summary": "Remove item from watch history",
        "description": "Remove a movie, show, or episode from watched history.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "movie",
                      "show",
                      "episode"
                    ],
                    "default": "movie"
                  },
                  "trakt_id": {
                    "type": "integer"
                  },
                  "imdb_id": {
                    "type": "string"
                  },
                  "movies": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "shows": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Removal confirmation"
          }
        }
      }
    },
    "/api/ratings": {
      "get": {
        "operationId": "getUserRatings",
        "summary": "Get user ratings",
        "description": "Returns movies and TV shows rated by the user (1 to 10 scale).",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "movies",
                "shows",
                "seasons",
                "episodes"
              ]
            }
          },
          {
            "name": "rating",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10
            },
            "description": "Filter by specific rating number (1-10)"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "User ratings list"
          }
        }
      },
      "post": {
        "operationId": "rateItem",
        "summary": "Rate a movie or show",
        "description": "Submit a rating from 1 to 10 for a movie, show, season, or episode.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "rating"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "movie",
                      "show",
                      "episode"
                    ],
                    "default": "movie"
                  },
                  "rating": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "description": "Rating score from 1 to 10"
                  },
                  "trakt_id": {
                    "type": "integer"
                  },
                  "imdb_id": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "movies": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "shows": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rating submitted confirmation"
          }
        }
      }
    },
    "/api/ratings/remove": {
      "post": {
        "operationId": "removeRating",
        "summary": "Remove rating from movie or show",
        "description": "Remove a rating from a movie or TV show.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "movie",
                      "show",
                      "episode"
                    ],
                    "default": "movie"
                  },
                  "trakt_id": {
                    "type": "integer"
                  },
                  "imdb_id": {
                    "type": "string"
                  },
                  "movies": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "shows": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rating removed confirmation"
          }
        }
      }
    },
    "/api/recommendations/movies": {
      "get": {
        "operationId": "getMovieRecommendations",
        "summary": "Get personalized movie recommendations",
        "description": "Returns personalized movie recommendations calculated by Trakt based on user watch history and ratings.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          },
          {
            "name": "ignore_collected",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "ignore_watchlisted",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recommended movies list"
          }
        }
      }
    },
    "/api/recommendations/shows": {
      "get": {
        "operationId": "getShowRecommendations",
        "summary": "Get personalized TV show recommendations",
        "description": "Returns personalized TV show recommendations calculated by Trakt.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recommended TV shows list"
          }
        }
      }
    },
    "/api/checkin": {
      "post": {
        "operationId": "checkin",
        "summary": "Check in to a movie or episode",
        "description": "Check in to what the user is watching right now on Trakt.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "movie": {
                    "type": "object",
                    "properties": {
                      "title": {
                        "type": "string"
                      },
                      "year": {
                        "type": "integer"
                      },
                      "ids": {
                        "type": "object"
                      }
                    }
                  },
                  "episode": {
                    "type": "object",
                    "properties": {
                      "ids": {
                        "type": "object"
                      }
                    }
                  },
                  "message": {
                    "type": "string",
                    "description": "Optional status message or tweet"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkin active confirmation with watching timestamp"
          }
        }
      },
      "delete": {
        "operationId": "cancelCheckin",
        "summary": "Cancel active checkin",
        "description": "Cancels any active check-in on Trakt.",
        "responses": {
          "200": {
            "description": "Checkin cancelled"
          }
        }
      }
    },
    "/api/calendar/my/shows": {
      "get": {
        "operationId": "getMyUpcomingShows",
        "summary": "Get upcoming shows schedule",
        "description": "Returns all upcoming TV show episodes airing on the user calendar (e.g. watchlist/favorited shows).",
        "parameters": [
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Start date (YYYY-MM-DD), default is today"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 7
            },
            "description": "Number of days to look ahead (1-31)"
          }
        ],
        "responses": {
          "200": {
            "description": "Upcoming episodes list"
          }
        }
      }
    },
    "/api/calendar/my/movies": {
      "get": {
        "operationId": "getMyUpcomingMovies",
        "summary": "Get upcoming movies schedule",
        "description": "Returns upcoming movies releasing on the user calendar (theatrical/digital).",
        "parameters": [
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Upcoming movies list"
          }
        }
      }
    }
  }
}