seerr-api.yml

openapi: '3.0.2'
info:
  title: 'Foreseerr API'
  version: '1.0.0'
  description: |
    This is the documentation for the Foreseerr API backend.

    Two primary authentication methods are supported:

    - **Cookie Authentication**: A valid sign-in to the `/auth/plex` or `/auth/local` will generate a valid authentication cookie.
    - **API Key Authentication**: Sign-in is also possible by passing an `X-Api-Key` header along with a valid API Key generated by Foreseerr.
tags:
  - name: public
    description: Public API endpoints requiring no authentication.
  - name: settings
    description: Endpoints related to Foreseerr's settings and configuration.
  - name: auth
    description: Endpoints related to logging in or out, and the currently authenticated user.
  - name: users
    description: Endpoints related to user management.
  - name: search
    description: Endpoints related to search and discovery.
  - name: request
    description: Endpoints related to request management.
  - name: movies
    description: Endpoints related to retrieving movies and their details.
  - name: tv
    description: Endpoints related to retrieving TV series and their details.
  - name: other
    description: Endpoints related to other TMDB data
  - name: person
    description: Endpoints related to retrieving person details.
  - name: media
    description: Endpoints related to media management.
  - name: collection
    description: Endpoints related to retrieving collection details.
  - name: service
    description: Endpoints related to getting service (Radarr/Sonarr) details.
  - name: watchlist
    description: Collection of media to watch later
  - name: blocklist
    description: Blocklisted media from discovery page.
  - name: calendar
    description: Unified Sonarr and Radarr release calendar.
  - name: library
    description: Owned-media Watch Now shelves and available library browse.
servers:
  - url: '{server}/api/v1'
    variables:
      server:
        default: http://localhost:5055

components:
  schemas:
    Blocklist:
      type: object
      properties:
        tmdbId:
          type: number
          example: 1
        title:
          type: string
        media:
          $ref: '#/components/schemas/MediaInfo'
        userId:
          type: number
          example: 1
    Watchlist:
      type: object
      properties:
        id:
          type: integer
          example: 1
          readOnly: true
        tmdbId:
          type: number
          example: 1
        ratingKey:
          type: string
        type:
          type: string
        title:
          type: string
        media:
          $ref: '#/components/schemas/MediaInfo'
        createdAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        updatedAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        requestedBy:
          $ref: '#/components/schemas/User'
    MappingNamespace:
      type: string
      description: |
        Identity namespace in the mapping graph. `tmdb_movie` and `tmdb_show`
        are separate because the same integer is a valid id in both catalogues
        for two unrelated titles, so media type is part of an id's identity.
      enum:
        - tmdb_movie
        - tmdb_show
        - tvdb_movie
        - tvdb_show
        - imdb
        - anidb
        - anilist
        - mal
        - kitsu
        - simkl
        - trakt
        - livechart
        - animeplanet
        - anisearch
    DiscoverMappingInfo:
      type: object
      description: How a discover item was mapped to TMDB, or why it was not.
      properties:
        state:
          type: string
          enum: [mapped, unmapped, ambiguous]
        namespace:
          $ref: '#/components/schemas/MappingNamespace'
        externalId:
          type: string
        sourceKey:
          type: string
          description: Resolver or pack that produced the answer.
          example: anibridge
        confidence:
          type: number
          example: 90
        layer:
          type: string
          enum: [override, graph, pack, live, heuristic, cache, none]
    MappingGap:
      type: object
      description: An unresolved discover item, recorded so misses are measurable.
      properties:
        id:
          type: number
          readOnly: true
        namespace:
          $ref: '#/components/schemas/MappingNamespace'
        externalId:
          type: string
        season:
          type: number
          description: '-1 when the gap is not season-scoped.'
          example: -1
        title:
          type: string
        year:
          type: number
        mediaType:
          type: string
          enum: [movie, tv]
        discoverSource:
          type: string
          example: simkl/trending/anime
        reason:
          type: string
          enum: [unresolved, ambiguous, phantom, wrong-type]
        status:
          type: string
          enum: [open, resolved, ignored]
        rejectedTarget:
          type: string
        sourceKey:
          type: string
        suggestedTarget:
          type: string
          description: |
            Quarantined heuristic guess, as a ref key. Shown for review only; it
            is never consulted by the resolver chain.
          example: tmdb_show:1429
        suggestedConfidence:
          type: number
        suggestedBy:
          type: string
        hitCount:
          type: number
        firstSeenAt:
          type: string
        lastSeenAt:
          type: string
    MappingOverride:
      type: object
      description: |
        An admin correction, which wins over every other resolver. `id` is not
        read-only so that an exported file can be re-imported verbatim; the
        server matches on the from/to identity and ignores any id supplied.
      properties:
        id:
          type: number
        fromNamespace:
          $ref: '#/components/schemas/MappingNamespace'
        fromExternalId:
          type: string
        fromSeason:
          type: number
          nullable: true
        toNamespace:
          $ref: '#/components/schemas/MappingNamespace'
        toExternalId:
          type: string
          description: Empty records that no counterpart exists.
        toSeason:
          type: number
          nullable: true
        note:
          type: string
          nullable: true
    MappingSource:
      type: object
      description: A registered mapping pack or live resolver.
      properties:
        key:
          type: string
          example: anibridge
        kind:
          type: string
          enum: [pack, live]
        enabled:
          type: boolean
        priority:
          type: number
        trust:
          type: number
        format:
          type: string
          enum: [json-graph, json-array, ndjson, yaml-map, xml-animelist]
        mirrors:
          type: array
          items:
            type: string
        licence:
          type: string
        legalNote:
          type: string
        version:
          type: string
        entryCount:
          type: number
        lastFetchedAt:
          type: string
        lastSuccessAt:
          type: string
        lastError:
          type: string
        circuitState:
          type: string
          enum: [closed, open, half-open]
        consecutiveFailures:
          type: number
    MappingHealth:
      type: object
      properties:
        gaps:
          type: object
          properties:
            openGaps:
              type: number
            totalHits:
              type: number
            byReason:
              type: object
              additionalProperties:
                type: number
            bySource:
              type: object
              additionalProperties:
                type: number
            byNamespace:
              type: object
              additionalProperties:
                type: number
        budgets:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              costClass:
                type: string
                enum: [interactive, bulk, both]
              tokens:
                type: number
              inFlight:
                type: number
              queued:
                type: number
              active:
                type: number
              quotaUsed:
                type: number
              dailyQuota:
                type: number
              circuitState:
                type: string
                enum: [closed, open, half-open]
              consecutiveFailures:
                type: number
        usage:
          type: array
          description: Per-source request counters, one row per UTC day.
          items:
            type: object
            properties:
              sourceKey:
                type: string
              day:
                type: string
                example: '2026-08-28'
              requests:
                type: number
              failures:
                type: number
              itemsResolved:
                type: number
        sources:
          type: array
          items:
            $ref: '#/components/schemas/MappingSource'
        available:
          type: array
          description: Manifest packs that have no MappingSource row yet.
          items:
            type: object
            properties:
              key:
                type: string
              format:
                type: string
              mirrors:
                type: array
                items:
                  type: string
              licence:
                type: string
              legalNote:
                type: string
              enabled:
                type: boolean
              priority:
                type: number
              trust:
                type: number
        resolvers:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              kind:
                type: string
                enum: [override, graph, pack, live, heuristic]
              trust:
                type: number
        providers:
          type: array
          description: >-
            Access health of providers the mapping layer depends on but does
            not own. Trakt refuses requests carrying only the application
            client_id, so list search and unlinked users degrade.
          items:
            type: object
            properties:
              key:
                type: string
              state:
                type: string
                enum: [ok, failing, unconfigured]
              detail:
                type: string
              checkedAt:
                type: string
                format: date-time
        refreshes:
          type: array
          description: In-flight mapping pack downloads and ingests.
          items:
            type: object
            properties:
              key:
                type: string
              phase:
                type: string
                enum: [downloading, validating, parsing, ingesting]
              mirror:
                type: string
              bytesReceived:
                type: number
              bytesTotal:
                type: number
              recordsDone:
                type: number
              recordsTotal:
                type: number
              startedAt:
                type: string
                format: date-time
              updatedAt:
                type: string
                format: date-time
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
          readOnly: true
        email:
          type: string
          example: 'hey@itsme.com'
          readOnly: true
        username:
          type: string
        plexUsername:
          type: string
          readOnly: true
        plexToken:
          type: string
          readOnly: true
        jellyfinAuthToken:
          type: string
          readOnly: true
        userType:
          type: integer
          example: 1
          readOnly: true
        permissions:
          type: number
          example: 0
        avatar:
          type: string
          readOnly: true
        createdAt:
          type: string
          example: '2020-09-02T05:02:23.000Z'
          readOnly: true
        updatedAt:
          type: string
          example: '2020-09-02T05:02:23.000Z'
          readOnly: true
        requestCount:
          type: number
          example: 5
          readOnly: true
      required:
        - id
        - email
        - createdAt
        - updatedAt
    UserSettings:
      type: object
      properties:
        username:
          type: string
          nullable: true
          example: 'Mr User'
        email:
          type: string
          example: 'user@example.com'
        locale:
          type: string
          nullable: true
          example: 'en'
        discoverRegion:
          type: string
          nullable: true
          example: 'US'
        streamingRegion:
          type: string
          nullable: true
          example: 'US'
        originalLanguage:
          type: string
          nullable: true
          example: 'en'
        movieQuotaLimit:
          type: number
          nullable: true
          description: 'Maximum number of movie requests allowed'
          example: 10
        movieQuotaDays:
          type: number
          nullable: true
          description: 'Time period in days for movie quota'
          example: 30
        tvQuotaLimit:
          type: number
          nullable: true
          description: 'Maximum number of TV requests allowed'
          example: 5
        tvQuotaDays:
          type: number
          nullable: true
          description: 'Time period in days for TV quota'
          example: 14
        globalMovieQuotaDays:
          type: number
          nullable: true
          description: 'Global movie quota days setting'
          example: 30
        globalMovieQuotaLimit:
          type: number
          nullable: true
          description: 'Global movie quota limit setting'
          example: 10
        globalTvQuotaLimit:
          type: number
          nullable: true
          description: 'Global TV quota limit setting'
          example: 5
        globalTvQuotaDays:
          type: number
          nullable: true
          description: 'Global TV quota days setting'
          example: 14
        watchlistSyncMovies:
          type: boolean
          nullable: true
          description: 'Enable watchlist sync for movies'
          example: true
        watchlistSyncTv:
          type: boolean
          nullable: true
          description: 'Enable watchlist sync for TV'
          example: false
        autoCompleteSkippedEpisodeEndings:
          type: boolean
          nullable: true
          description: 'Mark stale resumed episodes watched in Jellyfin and Trakt when Library loads'
          example: false
        autoCompleteSkippedEpisodeThreshold:
          type: integer
          nullable: true
          minimum: 1
          maximum: 100
          description: 'Minimum leftover progress percent required before a skipped episode is auto-completed. Defaults to 50 when unset.'
          example: 50
        watchAheadEpisodeCount:
          type: integer
          nullable: true
          minimum: 1
          maximum: 50
          description: 'Default number of unwatched episodes to keep requested when using Watch ahead. Defaults to 10 when unset.'
          example: 10
    DiscoverFilterDefaults:
      type: object
      description: >
        Per-user Discover browse filter defaults. Boolean flags use JSON booleans;
        other fields use the same string shapes as Discover URL query params.
        Omitted keys mean no default. Unknown keys are rejected on write.
      additionalProperties: false
      properties:
        ignoreWatched:
          type: boolean
        ignoreCollected:
          type: boolean
        ignoreWatchlisted:
          type: boolean
        hideUnmapped:
          type: boolean
        includeNoRating:
          type: boolean
        language:
          type: string
        primaryReleaseDateGte:
          type: string
        primaryReleaseDateLte:
          type: string
        firstAirDateGte:
          type: string
        firstAirDateLte:
          type: string
        genre:
          type: string
          description: Comma-separated TMDB genre ids
        voteAverageGte:
          type: string
        voteAverageLte:
          type: string
        voteCountGte:
          type: string
        voteCountLte:
          type: string
        imdbRatingGte:
          type: string
        imdbRatingLte:
          type: string
        imdbVotesGte:
          type: string
        imdbVotesLte:
          type: string
        rtCriticsGte:
          type: string
        rtCriticsLte:
          type: string
        rtAudienceGte:
          type: string
        rtAudienceLte:
          type: string
        metacriticGte:
          type: string
        metacriticLte:
          type: string
        traktRatingGte:
          type: string
        traktRatingLte:
          type: string
    MainSettings:
      type: object
      properties:
        apiKey:
          type: string
          readOnly: true
        appLanguage:
          type: string
          example: en
        applicationTitle:
          type: string
          example: Foreseerr
        applicationUrl:
          type: string
          example: https://os.example.com
        hideAvailable:
          type: boolean
          example: false
        partialRequestsEnabled:
          type: boolean
          example: false
        episodeRequestsEnabled:
          type: boolean
          description: Whether TVDB-backed episode requests are available.
          example: false
        localLogin:
          type: boolean
          example: true
        mediaServerType:
          type: number
          example: 1
        newPlexLogin:
          type: boolean
          example: true
        defaultPermissions:
          type: number
          example: 32
        enableSpecialEpisodes:
          type: boolean
          example: false
        versionCheck:
          type: boolean
          example: false
        cacheImages:
          type: boolean
          example: false
        imageCacheIdleDays:
          type: integer
          minimum: 1
          maximum: 90
          example: 7
          description: Delete cached images that have not been requested for this many days.
    NetworkSettings:
      type: object
      properties:
        csrfProtection:
          type: boolean
          example: false
        forceIpv4First:
          type: boolean
          example: false
        trustProxy:
          type: boolean
          example: false
        proxy:
          type: object
          properties:
            enabled:
              type: boolean
              example: false
            hostname:
              type: string
              example: ''
            port:
              type: number
              example: 8080
            useSsl:
              type: boolean
              example: false
            user:
              type: string
              example: ''
            password:
              type: string
              example: ''
            bypassFilter:
              type: string
              example: ''
            bypassLocalAddresses:
              type: boolean
              example: true
        dnsCache:
          type: object
          properties:
            enabled:
              type: boolean
              example: false
            forceMinTtl:
              type: number
              example: 0
            forceMaxTtl:
              type: number
              example: -1
    PlexLibrary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          example: Movies
        enabled:
          type: boolean
          example: false
      required:
        - id
        - name
        - enabled
    PlexSettings:
      type: object
      properties:
        name:
          type: string
          example: 'Main Server'
          readOnly: true
        machineId:
          type: string
          example: '1234123412341234'
          readOnly: true
        ip:
          type: string
          example: '127.0.0.1'
        port:
          type: number
          example: 32400
        useSsl:
          type: boolean
          nullable: true
        libraries:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/PlexLibrary'
        webAppUrl:
          type: string
          nullable: true
          example: 'https://app.plex.tv/desktop'
      required:
        - name
        - machineId
        - ip
        - port
    PlexConnection:
      type: object
      properties:
        protocol:
          type: string
          example: 'https'
        address:
          type: string
          example: '127.0.0.1'
        port:
          type: number
          example: 32400
        uri:
          type: string
          example: 'https://127-0-0-1.2ab6ce1a093d465e910def96cf4e4799.plex.direct:32400'
        local:
          type: boolean
          example: true
        status:
          type: number
          example: 200
        message:
          type: string
          example: 'OK'
      required:
        - protocol
        - address
        - port
        - uri
        - local
    PlexDevice:
      type: object
      properties:
        name:
          type: string
          example: 'My Plex Server'
        product:
          type: string
          example: 'Plex Media Server'
        productVersion:
          type: string
          example: '1.21'
        platform:
          type: string
          example: 'Linux'
        platformVersion:
          type: string
          example: 'default/linux/amd64/17.1/systemd'
        device:
          type: string
          example: 'PC'
        clientIdentifier:
          type: string
          example: '85a943ce-a0cc-4d2a-a4ec-f74f06e40feb'
        createdAt:
          type: string
          example: '2021-01-01T00:00:00.000Z'
        lastSeenAt:
          type: string
          example: '2021-01-01T00:00:00.000Z'
        provides:
          type: array
          items:
            type: string
            example: 'server'
        owned:
          type: boolean
          example: true
        ownerID:
          type: string
          example: '12345'
        home:
          type: boolean
          example: true
        sourceTitle:
          type: string
          example: 'xyzabc'
        accessToken:
          type: string
          example: 'supersecretaccesstoken'
        publicAddress:
          type: string
          example: '127.0.0.1'
        httpsRequired:
          type: boolean
          example: true
        synced:
          type: boolean
          example: true
        relay:
          type: boolean
          example: true
        dnsRebindingProtection:
          type: boolean
          example: false
        natLoopbackSupported:
          type: boolean
          example: false
        publicAddressMatches:
          type: boolean
          example: false
        presence:
          type: boolean
          example: true
        connection:
          type: array
          items:
            $ref: '#/components/schemas/PlexConnection'
      required:
        - name
        - product
        - productVersion
        - platform
        - device
        - clientIdentifier
        - createdAt
        - lastSeenAt
        - provides
        - owned
        - connection
    JellyfinLibrary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          example: Movies
        enabled:
          type: boolean
          example: false
      required:
        - id
        - name
        - enabled
    JellyfinSettings:
      type: object
      properties:
        name:
          type: string
          example: 'Main Server'
          readOnly: true
        hostname:
          type: string
          example: 'http://my.jellyfin.host'
        externalHostname:
          type: string
          example: 'http://my.jellyfin.host'
        jellyfinForgotPasswordUrl:
          type: string
          example: 'http://my.jellyfin.host/web/index.html#!/forgotpassword.html'
        adminUser:
          type: string
          example: 'admin'
        adminPass:
          type: string
          example: 'mypassword'
        libraries:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/JellyfinLibrary'
        serverID:
          type: string
          readOnly: true
    MetadataSettings:
      type: object
      properties:
        settings:
          type: object
          properties:
            tv:
              type: string
              enum: [tvdb, tmdb]
              example: 'tvdb'
            anime:
              type: string
              enum: [tvdb, tmdb]
              example: 'tvdb'
    TautulliSettings:
      type: object
      properties:
        hostname:
          type: string
          nullable: true
          example: 'tautulli.example.com'
        port:
          type: number
          nullable: true
          example: 8181
        useSsl:
          type: boolean
          nullable: true
        apiKey:
          type: string
          nullable: true
        externalUrl:
          type: string
          nullable: true
    TraktSettings:
      type: object
      properties:
        provider:
          type: string
          enum: [direct, jellyfin]
          description: Direct Trakt application credentials or the Better Trakt Jellyfin bridge
          example: direct
        clientId:
          type: string
          example: 'your-trakt-client-id'
        clientSecret:
          type: string
          description: Masked on GET responses when configured
          example: '********'
        configured:
          type: boolean
          example: true
        actionsEnabled:
          type: boolean
          description: Whether Trakt is enabled as a media-actions provider (watched/rate fan-out)
          example: true
        linkedAccountCount:
          type: integer
          description: Number of Foreseerr users with linked Trakt accounts
          example: 0
        confirmDisconnectLinkedAccounts:
          type: boolean
          description: Required on POST when changing credentials while users are linked
          example: false
        confirmProviderSwitch:
          type: boolean
          description: Required when switching from Direct Trakt to Better Trakt
          example: false
    AniListSettings:
      type: object
      properties:
        clientId:
          type: string
          example: 'your-anilist-client-id'
        clientSecret:
          type: string
          description: Masked on GET responses when configured
          example: '********'
        configured:
          type: boolean
          example: true
        actionsEnabled:
          type: boolean
          description: Whether AniList is enabled as a media-actions provider
          example: true
        redirectUrl:
          type: string
          example: 'https://anilist.co/api/v2/oauth/pin'
        linkedAccountCount:
          type: integer
          example: 0
        confirmDisconnectLinkedAccounts:
          type: boolean
          example: false
        clearCredentials:
          type: boolean
          example: false
    MediaActionProviderResult:
      type: object
      properties:
        provider:
          type: string
          enum: [trakt, jellyfin, anilist, simkl]
        ok:
          type: boolean
        watched:
          type: boolean
        rating:
          type: number
          nullable: true
          description: Provider-native score (Trakt 1–10)
        ratingStars:
          type: number
          nullable: true
          description: UI half-stars (0.5–5)
        error:
          type: string
    MediaActionStatus:
      type: object
      required:
        [tmdbId, mediaType, watched, rating, ratingStars, providers, actions]
      properties:
        tmdbId:
          type: number
        mediaType:
          type: string
          enum: [movie, tv]
        watched:
          type: boolean
        rating:
          type: number
          nullable: true
        ratingStars:
          type: number
          nullable: true
        outcome:
          type: string
          enum: [success, partial, failure]
          description: Present on write responses. Reads omit this field.
        providers:
          type: array
          items:
            $ref: '#/components/schemas/MediaActionProviderResult'
        actions:
          $ref: '#/components/schemas/MediaActionItemAvailability'
    MediaActionOperationAvailability:
      type: object
      required: [available]
      properties:
        available:
          type: boolean
        reason:
          type: string
          enum: [no_provider, not_mapped, provider_error, unsupported]
          description: Present when this action cannot be performed for this title.
    MediaActionItemAvailability:
      type: object
      required: [watched, rating]
      properties:
        watched:
          $ref: '#/components/schemas/MediaActionOperationAvailability'
        rating:
          $ref: '#/components/schemas/MediaActionOperationAvailability'
    MediaActionOperationCapabilities:
      type: object
      required: [readWatched, writeWatched, readRating, writeRating]
      properties:
        readWatched:
          type: boolean
        writeWatched:
          type: boolean
        readRating:
          type: boolean
        writeRating:
          type: boolean
    MediaActionProviderCapability:
      type: object
      required: [id, linked, capabilities]
      properties:
        id:
          type: string
          enum: [trakt, jellyfin, anilist, simkl]
        linked:
          type: boolean
        capabilities:
          $ref: '#/components/schemas/MediaActionOperationCapabilities'
    MediaActionSurfaceCapabilities:
      type: object
      required: [watched, rating]
      properties:
        watched:
          type: boolean
        rating:
          type: boolean
    MediaActionCapabilitiesResponse:
      type: object
      required: [movie, tv, episode, providers]
      properties:
        movie:
          $ref: '#/components/schemas/MediaActionSurfaceCapabilities'
        tv:
          $ref: '#/components/schemas/MediaActionSurfaceCapabilities'
        episode:
          $ref: '#/components/schemas/MediaActionSurfaceCapabilities'
        providers:
          type: array
          items:
            $ref: '#/components/schemas/MediaActionProviderCapability'
    EpisodeWatchStatus:
      type: object
      required: [available, watchedEpisodeNumbers]
      properties:
        available:
          type: boolean
          description: Whether any linked provider can read or write episode watched status for the current user
        watchedEpisodeNumbers:
          type: array
          items:
            type: integer
            minimum: 0
    EpisodeWatchWriteResult:
      type: object
      required: [outcome, watched, providers]
      properties:
        outcome:
          type: string
          enum: [success, partial, failure]
        watched:
          type: boolean
        providers:
          type: array
          items:
            $ref: '#/components/schemas/MediaActionProviderResult'
    RatingBadgeSettings:
      type: object
      properties:
        showTmdb:
          type: boolean
          example: true
        showImdb:
          type: boolean
          example: true
        showRt:
          type: boolean
          example: true
        showRtUser:
          type: boolean
          example: true
        showMetacritic:
          type: boolean
          example: true
        showTraktCommunity:
          type: boolean
          example: true
        posterTmdb:
          type: boolean
          description: Show TMDB on idle (unfocused) posters
          example: true
        posterImdb:
          type: boolean
          example: true
        posterRt:
          type: boolean
          example: true
        posterRtUser:
          type: boolean
          example: false
        posterMetacritic:
          type: boolean
          example: false
        posterTraktCommunity:
          type: boolean
          example: false
    MdbListSettings:
      type: object
      properties:
        apiKey:
          type: string
          description: Masked on GET responses when configured
          example: '********'
        configured:
          type: boolean
          example: true
        showTmdb:
          type: boolean
          example: true
        showImdb:
          type: boolean
          example: true
        showRt:
          type: boolean
          example: true
        showRtUser:
          type: boolean
          example: true
        showMetacritic:
          type: boolean
          example: true
        showTraktCommunity:
          type: boolean
          example: true
        posterTmdb:
          type: boolean
          example: true
        posterImdb:
          type: boolean
          example: true
        posterRt:
          type: boolean
          example: true
        posterRtUser:
          type: boolean
          example: false
        posterMetacritic:
          type: boolean
          example: false
        posterTraktCommunity:
          type: boolean
          example: false
        clearApiKey:
          type: boolean
          description: When true on POST, removes the stored API key instead of preserving the masked placeholder.
          example: false
    RatingResponse:
      type: object
      properties:
        provider:
          type: string
          enum: [mdblist, legacy]
        rt:
          type: object
          properties:
            title:
              type: string
            year:
              type: number
            url:
              type: string
            criticsScore:
              type: number
            criticsRating:
              type: string
              enum: ['Rotten', 'Fresh', 'Certified Fresh']
            audienceScore:
              type: number
            audienceRating:
              type: string
              enum: ['Spilled', 'Upright']
        imdb:
          type: object
          properties:
            title:
              type: string
            url:
              type: string
            criticsScore:
              type: number
            criticsScoreCount:
              type: number
        metacritic:
          type: object
          properties:
            score:
              type: number
              example: 86
        trakt:
          type: object
          properties:
            rating:
              type: number
              example: 8.8
            votes:
              type: number
    RadarrSettings:
      type: object
      properties:
        id:
          type: number
          example: 0
          readOnly: true
        name:
          type: string
          example: 'Radarr Main'
        hostname:
          type: string
          example: '127.0.0.1'
        port:
          type: number
          example: 7878
        apiKey:
          type: string
          example: 'exampleapikey'
        useSsl:
          type: boolean
          example: false
        baseUrl:
          type: string
        activeProfileId:
          type: number
          example: 1
        activeProfileName:
          type: string
          example: 720p/1080p
        activeDirectory:
          type: string
          example: '/movies'
        is4k:
          type: boolean
          example: false
        minimumAvailability:
          type: string
          example: 'In Cinema'
        isDefault:
          type: boolean
          example: false
        externalUrl:
          type: string
          example: http://radarr.example.com
        syncEnabled:
          type: boolean
          example: false
        preventSearch:
          type: boolean
          example: false
        enableInstantRequests:
          type: boolean
          description: Whether requests submit immediately using this server's defaults.
          example: true
      required:
        - name
        - hostname
        - port
        - apiKey
        - useSsl
        - activeProfileId
        - activeProfileName
        - activeDirectory
        - is4k
        - minimumAvailability
        - isDefault
    SonarrSettings:
      type: object
      properties:
        id:
          type: number
          example: 0
          readOnly: true
        name:
          type: string
          example: 'Sonarr Main'
        hostname:
          type: string
          example: '127.0.0.1'
        port:
          type: number
          example: 8989
        apiKey:
          type: string
          example: 'exampleapikey'
        useSsl:
          type: boolean
          example: false
        baseUrl:
          type: string
        activeProfileId:
          type: number
          example: 1
        activeProfileName:
          type: string
          example: 720p/1080p
        activeDirectory:
          type: string
          example: '/tv/'
        activeLanguageProfileId:
          type: number
          example: 1
        activeAnimeProfileId:
          type: number
          nullable: true
        activeAnimeLanguageProfileId:
          type: number
          nullable: true
        activeAnimeProfileName:
          type: string
          example: 720p/1080p
          nullable: true
        activeAnimeDirectory:
          type: string
          nullable: true
        is4k:
          type: boolean
          example: false
        enableSeasonFolders:
          type: boolean
          example: false
        isDefault:
          type: boolean
          example: false
        externalUrl:
          type: string
          example: http://radarr.example.com
        syncEnabled:
          type: boolean
          example: false
        preventSearch:
          type: boolean
          example: false
        enableInstantRequests:
          type: boolean
          description: Whether one-click season requests are enabled for this server.
          example: true
      required:
        - name
        - hostname
        - port
        - apiKey
        - useSsl
        - activeProfileId
        - activeProfileName
        - activeDirectory
        - is4k
        - enableSeasonFolders
        - isDefault
    ServarrTag:
      type: object
      properties:
        id:
          type: number
          example: 1
        label:
          type: string
          example: A Label
    ServarrInterventionSettings:
      type: object
      required: [automaticCleanupEnabled, cleanupGraceHours]
      properties:
        automaticCleanupEnabled:
          type: boolean
          default: false
        cleanupGraceHours:
          type: integer
          minimum: 1
          maximum: 720
          default: 24
    ServarrIntervention:
      type: object
      description: Safe intervention representation. Arr paths, download IDs, and queue IDs are never returned.
      required:
        [
          id,
          serviceType,
          serviceId,
          serviceName,
          is4k,
          mediaId,
          tmdbId,
          mediaType,
          releaseTitle,
          warningMessages,
          manualImportCapable,
          state,
          firstSeenAt,
          cleanupDeadlineAt,
        ]
      properties:
        id: { type: integer }
        serviceType: { type: string, enum: [radarr, sonarr] }
        serviceId: { type: integer }
        serviceName: { type: string }
        is4k: { type: boolean }
        mediaId: { type: integer }
        tmdbId: { type: integer }
        mediaType: { type: string, enum: [movie, tv] }
        releaseTitle: { type: string }
        warningMessages:
          type: array
          items: { type: string }
        manualImportCapable: { type: boolean }
        state: { type: string, enum: [active, rejecting, importing, resolved] }
        resolution:
          type: string
          nullable: true
          enum:
            [
              recovered,
              disappeared,
              manual_blocklist,
              automatic_blocklist,
              manual_import,
            ]
        cleanupError: { type: string, nullable: true }
        firstSeenAt: { type: string, format: date-time }
        cleanupDeadlineAt: { type: string, format: date-time }
        resolvedAt: { type: string, format: date-time, nullable: true }
        actor:
          type: object
          nullable: true
          properties:
            id: { type: integer }
            displayName: { type: string }
    PublicSettings:
      type: object
      required:
        - initialized
        - plexClientIdentifier
      properties:
        initialized:
          type: boolean
          example: false
        plexClientIdentifier:
          type: string
          format: uuid
          description: Instance Plex OAuth client identifier
          example: 6919275e-142a-48d8-be6b-93594cbd4626
        traktConfigured:
          type: boolean
          description: Whether admin Trakt API credentials are configured
          example: false
        anilistConfigured:
          type: boolean
          description: Whether admin AniList API credentials are configured
          example: false
        mediaActionsTraktEnabled:
          type: boolean
          description: Whether Trakt is enabled for watched/unwatched/rate fan-out
          example: true
        mediaActionsJellyfinEnabled:
          type: boolean
          description: Whether Jellyfin is enabled as a media-actions watched provider
          example: true
        mediaActionsAnilistEnabled:
          type: boolean
          description: Whether AniList is enabled for watched/unwatched/rate fan-out
          example: true
        mdblistConfigured:
          type: boolean
          description: Whether an MDBList API key is configured
          example: false
        movieInstantRequestEnabled:
          type: boolean
          example: true
        movie4kInstantRequestEnabled:
          type: boolean
          example: true
        seriesInstantRequestEnabled:
          type: boolean
          example: true
        series4kInstantRequestEnabled:
          type: boolean
          example: true
        ratingBadges:
          $ref: '#/components/schemas/RatingBadgeSettings'
    MovieResult:
      type: object
      required:
        - id
        - mediaType
        - title
      properties:
        id:
          type: number
          example: 1234
        mediaType:
          type: string
        popularity:
          type: number
          example: 10
        posterPath:
          type: string
        backdropPath:
          type: string
        voteCount:
          type: number
        voteAverage:
          type: number
        genreIds:
          type: array
          items:
            type: number
        overview:
          type: string
          example: 'Overview of the movie'
        originalLanguage:
          type: string
          example: 'en'
        title:
          type: string
          example: Movie Title
        originalTitle:
          type: string
          example: Original Movie Title
        releaseDate:
          type: string
        adult:
          type: boolean
          example: false
        video:
          type: boolean
          example: false
        mediaInfo:
          $ref: '#/components/schemas/MediaInfo'
        ratings:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RatingResponse'
    TvResult:
      type: object
      properties:
        id:
          type: number
          example: 1234
        mediaType:
          type: string
        popularity:
          type: number
          example: 10
        posterPath:
          type: string
        backdropPath:
          type: string
        voteCount:
          type: number
        voteAverage:
          type: number
        genreIds:
          type: array
          items:
            type: number
        overview:
          type: string
          example: 'Overview of the movie'
        originalLanguage:
          type: string
          example: 'en'
        name:
          type: string
          example: TV Show Name
        originalName:
          type: string
          example: Original TV Show Name
        originCountry:
          type: array
          items:
            type: string
        firstAirDate:
          type: string
        mediaInfo:
          $ref: '#/components/schemas/MediaInfo'
        ratings:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RatingResponse'
    PersonResult:
      type: object
      properties:
        id:
          type: number
          example: 12345
        profilePath:
          type: string
        adult:
          type: boolean
          example: false
        mediaType:
          type: string
          default: 'person'
        knownFor:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/MovieResult'
              - $ref: '#/components/schemas/TvResult'
    Genre:
      type: object
      properties:
        id:
          type: number
          example: 1
        name:
          type: string
          example: Adventure
    Company:
      type: object
      properties:
        id:
          type: number
          example: 1
        logo_path:
          type: string
          nullable: true
        name:
          type: string
    ProductionCompany:
      type: object
      properties:
        id:
          type: number
          example: 1
        logoPath:
          type: string
          nullable: true
        originCountry:
          type: string
        name:
          type: string
    Network:
      type: object
      properties:
        id:
          type: number
          example: 1
        logoPath:
          type: string
          nullable: true
        originCountry:
          type: string
        name:
          type: string
    RelatedVideo:
      type: object
      properties:
        url:
          type: string
          example: https://www.youtube.com/watch?v=9qhL2_UxXM0/
        key:
          type: string
          example: 9qhL2_UxXM0
        name:
          type: string
          example: Trailer for some movie (1978)
        size:
          type: number
          example: 1080
        type:
          type: string
          example: Trailer
          enum:
            - Clip
            - Teaser
            - Trailer
            - Featurette
            - Opening Credits
            - Behind the Scenes
            - Bloopers
        site:
          type: string
          enum:
            - 'YouTube'
    MovieDetails:
      type: object
      properties:
        id:
          type: number
          example: 123
          readOnly: true
        imdbId:
          type: string
          example: 'tt123'
        adult:
          type: boolean
        backdropPath:
          type: string
        posterPath:
          type: string
        budget:
          type: number
          example: 1000000
        genres:
          type: array
          items:
            $ref: '#/components/schemas/Genre'
        homepage:
          type: string
        relatedVideos:
          type: array
          items:
            $ref: '#/components/schemas/RelatedVideo'
        originalLanguage:
          type: string
        originalTitle:
          type: string
        overview:
          type: string
        popularity:
          type: number
        productionCompanies:
          type: array
          items:
            $ref: '#/components/schemas/ProductionCompany'
        productionCountries:
          type: array
          items:
            type: object
            properties:
              iso_3166_1:
                type: string
              name:
                type: string
        releaseDate:
          type: string
        releases:
          type: object
          properties:
            results:
              type: array
              items:
                type: object
                properties:
                  iso_3166_1:
                    type: string
                    example: 'US'
                  rating:
                    type: string
                    nullable: true
                  release_dates:
                    type: array
                    items:
                      type: object
                      properties:
                        certification:
                          type: string
                          example: 'PG-13'
                        iso_639_1:
                          type: string
                          nullable: true
                        note:
                          type: string
                          nullable: true
                          example: 'Blu ray'
                        release_date:
                          type: string
                          example: '2017-07-12T00:00:00.000Z'
                        type:
                          type: number
                          example: 1
        revenue:
          type: number
          nullable: true
        runtime:
          type: number
        spokenLanguages:
          type: array
          items:
            $ref: '#/components/schemas/SpokenLanguage'
        status:
          type: string
        tagline:
          type: string
        title:
          type: string
        video:
          type: boolean
        voteAverage:
          type: number
        voteCount:
          type: number
        credits:
          type: object
          properties:
            cast:
              type: array
              items:
                $ref: '#/components/schemas/Cast'
            crew:
              type: array
              items:
                $ref: '#/components/schemas/Crew'
        collection:
          type: object
          properties:
            id:
              type: number
              example: 1
            name:
              type: string
              example: A collection
            posterPath:
              type: string
            backdropPath:
              type: string
        externalIds:
          $ref: '#/components/schemas/ExternalIds'
        mediaInfo:
          $ref: '#/components/schemas/MediaInfo'
        ratings:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RatingResponse'
        watchProviders:
          type: array
          items:
            $ref: '#/components/schemas/WatchProviders'
    Episode:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        airDate:
          type: string
          nullable: true
        episodeNumber:
          type: number
        overview:
          type: string
        productionCode:
          type: string
        seasonNumber:
          type: number
        showId:
          type: number
        stillPath:
          type: string
          nullable: true
        voteAverage:
          type: number
        voteCount:
          type: number
    Season:
      type: object
      properties:
        id:
          type: number
        airDate:
          type: string
          nullable: true
        episodeCount:
          type: number
        name:
          type: string
        overview:
          type: string
        posterPath:
          type: string
        seasonNumber:
          type: number
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/Episode'
    TvDetails:
      type: object
      properties:
        id:
          type: number
          example: 123
        backdropPath:
          type: string
        posterPath:
          type: string
        contentRatings:
          type: object
          properties:
            results:
              type: array
              items:
                type: object
                properties:
                  iso_3166_1:
                    type: string
                    example: 'US'
                  rating:
                    type: string
                    example: 'TV-14'
        createdBy:
          type: array
          items:
            type: object
            properties:
              id:
                type: number
              name:
                type: string
              gender:
                type: number
              profilePath:
                type: string
                nullable: true
        episodeRunTime:
          type: array
          items:
            type: number
        firstAirDate:
          type: string
        genres:
          type: array
          items:
            $ref: '#/components/schemas/Genre'
        homepage:
          type: string
        inProduction:
          type: boolean
        languages:
          type: array
          items:
            type: string
        lastAirDate:
          type: string
        lastEpisodeToAir:
          $ref: '#/components/schemas/Episode'
        name:
          type: string
        nextEpisodeToAir:
          $ref: '#/components/schemas/Episode'
        networks:
          type: array
          items:
            $ref: '#/components/schemas/ProductionCompany'
        numberOfEpisodes:
          type: number
        numberOfSeason:
          type: number
        originCountry:
          type: array
          items:
            type: string
        originalLanguage:
          type: string
        originalName:
          type: string
        overview:
          type: string
        popularity:
          type: number
        productionCompanies:
          type: array
          items:
            $ref: '#/components/schemas/ProductionCompany'
        productionCountries:
          type: array
          items:
            type: object
            properties:
              iso_3166_1:
                type: string
              name:
                type: string
        spokenLanguages:
          type: array
          items:
            $ref: '#/components/schemas/SpokenLanguage'
        seasons:
          type: array
          items:
            $ref: '#/components/schemas/Season'
        status:
          type: string
        tagline:
          type: string
        type:
          type: string
        voteAverage:
          type: number
        voteCount:
          type: number
        credits:
          type: object
          properties:
            cast:
              type: array
              items:
                $ref: '#/components/schemas/Cast'
            crew:
              type: array
              items:
                $ref: '#/components/schemas/Crew'
        externalIds:
          $ref: '#/components/schemas/ExternalIds'
        keywords:
          type: array
          items:
            $ref: '#/components/schemas/Keyword'
        mediaInfo:
          $ref: '#/components/schemas/MediaInfo'
        ratings:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RatingResponse'
        watchProviders:
          type: array
          items:
            $ref: '#/components/schemas/WatchProviders'
        episodeRequestsEnabled:
          type: boolean
          description: Whether TVDB-backed episode requests are available for this series.
    EpisodeRequest:
      type: object
      properties:
        id:
          type: number
          readOnly: true
        tvdbId:
          type: number
        seasonNumber:
          type: number
        episodeNumber:
          type: number
        title:
          type: string
          nullable: true
        airDate:
          type: string
          nullable: true
        status:
          type: number
        searchTriggeredAt:
          type: string
          nullable: true
          readOnly: true
    MediaRequest:
      type: object
      properties:
        id:
          type: number
          example: 123
          readOnly: true
        status:
          type: number
          example: 0
          description: Status of the request. 1 = PENDING APPROVAL, 2 = APPROVED, 3 = DECLINED
          readOnly: true
        media:
          $ref: '#/components/schemas/MediaInfo'
        createdAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        updatedAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        requestedBy:
          $ref: '#/components/schemas/User'
        modifiedBy:
          anyOf:
            - $ref: '#/components/schemas/User'
            - type: string
              nullable: true
        is4k:
          type: boolean
          example: false
        serverId:
          type: number
        profileId:
          type: number
        rootFolder:
          type: string
        ignoreQuota:
          type: boolean
          example: false
          description: If true, this request will not count against the user's quota. Requires MANAGE_REQUESTS permission.
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/EpisodeRequest'
        episodeSelectionType:
          type: string
          enum: [single, range, after, watchAhead]
          nullable: true
        episodeStartTvdbId:
          type: number
          nullable: true
        episodeEndTvdbId:
          type: number
          nullable: true
        watchAheadCount:
          type: integer
          nullable: true
          minimum: 1
          maximum: 50
        tvQuotaUnits:
          type: number
          readOnly: true
      required:
        - id
        - status
    MediaInfo:
      type: object
      properties:
        id:
          type: number
          readOnly: true
        tmdbId:
          type: number
          readOnly: true
        tvdbId:
          type: number
          readOnly: true
          nullable: true
        status:
          type: number
          example: 0
          description: Availability of the media. 1 = `UNKNOWN`, 2 = `PENDING`, 3 = `PROCESSING`, 4 = `PARTIALLY_AVAILABLE`, 5 = `AVAILABLE`, 6 = `DELETED`
        requests:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/MediaRequest'
        createdAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        updatedAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
    Cast:
      type: object
      properties:
        id:
          type: number
          example: 123
        castId:
          type: number
          example: 1
        character:
          type: string
          example: Some Character Name
        creditId:
          type: string
        gender:
          type: number
        name:
          type: string
          example: Some Persons Name
        order:
          type: number
        profilePath:
          type: string
          nullable: true
    Crew:
      type: object
      properties:
        id:
          type: number
          example: 123
        creditId:
          type: string
        gender:
          type: number
        name:
          type: string
          example: Some Persons Name
        job:
          type: string
        department:
          type: string
        profilePath:
          type: string
          nullable: true
    ExternalIds:
      type: object
      properties:
        facebookId:
          type: string
          nullable: true
        freebaseId:
          type: string
          nullable: true
        freebaseMid:
          type: string
          nullable: true
        imdbId:
          type: string
          nullable: true
        instagramId:
          type: string
          nullable: true
        tvdbId:
          type: number
          nullable: true
        tvrageId:
          type: number
          nullable: true
        twitterId:
          type: string
          nullable: true
    ServiceProfile:
      type: object
      properties:
        id:
          type: number
          example: 1
        name:
          type: string
          example: 720p/1080p
    PageInfo:
      type: object
      properties:
        page:
          type: number
          example: 1
        pages:
          type: number
          example: 10
        results:
          type: number
          example: 100
    LibraryTitle:
      type: object
      required: [mediaType, jellyfinItemId, title]
      properties:
        mediaId:
          type: number
        tmdbId:
          type: number
        mediaType:
          type: string
          enum: [movie, tv]
        jellyfinItemId:
          type: string
        playItemId:
          type: string
          description: Item id Play should send (resolved episode for series rows)
        jellyfinSeriesId:
          type: string
          description: Series id for opening the Library series panel
        title:
          type: string
        subtitle:
          type: string
        overview:
          type: string
        mediaUrl:
          type: string
        status:
          type: number
        progressPercent:
          type: number
        startPositionTicks:
          type: number
        year:
          type: number
        genres:
          type: array
          items:
            type: string
        watched:
          type: boolean
        inProgress:
          type: boolean
        addedAt:
          type: string
          format: date-time
        lastPlayedAt:
          type: string
          format: date-time
        posterUrl:
          type: string
        backdropUrl:
          type: string
        runtimeMinutes:
          type: number
        inspectorItemId:
          type: string
          description: Movie id, or parent series id for episode rows
        unplayedItemCount:
          type: number
          description: Unplayed episodes remaining on series rows
        availableEpisodeCount:
          type: number
          description: Episodes currently present in the library on series rows
    LibraryBrowseResponse:
      type: object
      required: [pageInfo, results]
      properties:
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
        results:
          type: array
          items:
            $ref: '#/components/schemas/LibraryTitle'
        code:
          type: string
          enum: [not_linked, server_unreachable, unsupported_media_server]
    LibraryFacetsResponse:
      type: object
      required: [genres]
      properties:
        genres:
          type: array
          items:
            type: string
        yearMin:
          type: number
        yearMax:
          type: number
        code:
          type: string
          enum: [not_linked, server_unreachable, unsupported_media_server]
    LibraryItemInspectorResponse:
      type: object
      required: [jellyfinItemId, mediaType, title]
      properties:
        jellyfinItemId:
          type: string
        jellyfinSeriesId:
          type: string
        mediaType:
          type: string
          enum: [movie, tv]
        title:
          type: string
        subtitle:
          type: string
        overview:
          type: string
        year:
          type: number
        runtimeMinutes:
          type: number
        genres:
          type: array
          items:
            type: string
        posterUrl:
          type: string
        backdropUrl:
          type: string
        progressPercent:
          type: number
        watched:
          type: boolean
        inProgress:
          type: boolean
        startPositionTicks:
          type: number
        playItemId:
          type: string
        playUrl:
          type: string
        mediaUrl:
          type: string
        mediaId:
          type: number
        tmdbId:
          type: number
        status:
          type: number
        seasons:
          type: array
          items:
            $ref: '#/components/schemas/LibrarySeriesSeason'
        code:
          type: string
          enum:
            [
              not_linked,
              server_unreachable,
              unsupported_media_server,
              not_found,
            ]
    LibraryShelf:
      type: object
      required: [id, title, items]
      properties:
        id:
          type: string
          enum: [continue, recent, recent-episodes, forgotten]
        title:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/LibraryTitle'
    LibraryWatchNowResponse:
      type: object
      required: [shelves]
      properties:
        shelves:
          type: array
          items:
            $ref: '#/components/schemas/LibraryShelf'
        code:
          type: string
          enum: [not_linked, server_unreachable, unsupported_media_server]
    LibraryAvailableResponse:
      type: object
      required: [pageInfo, results]
      properties:
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
        results:
          type: array
          items:
            $ref: '#/components/schemas/LibraryTitle'
        code:
          type: string
          enum: [not_linked, server_unreachable, unsupported_media_server]
    LibrarySeriesSeason:
      type: object
      required: [jellyfinSeasonId, name]
      properties:
        jellyfinSeasonId:
          type: string
        name:
          type: string
        indexNumber:
          type: number
        episodeCount:
          type: number
    LibrarySeriesDetailResponse:
      type: object
      required: [jellyfinSeriesId, title, seasons]
      properties:
        jellyfinSeriesId:
          type: string
        tmdbId:
          type: number
        title:
          type: string
        playItemId:
          type: string
        subtitle:
          type: string
        seasons:
          type: array
          items:
            $ref: '#/components/schemas/LibrarySeriesSeason'
        code:
          type: string
          enum:
            [
              not_linked,
              server_unreachable,
              unsupported_media_server,
              not_found,
            ]
    LibraryEpisode:
      type: object
      required: [jellyfinItemId, name]
      properties:
        jellyfinItemId:
          type: string
        name:
          type: string
        indexNumber:
          type: number
        parentIndexNumber:
          type: number
        subtitle:
          type: string
        overview:
          type: string
        progressPercent:
          type: number
        watched:
          type: boolean
    LibrarySeasonEpisodesResponse:
      type: object
      required: [jellyfinSeriesId, jellyfinSeasonId, episodes]
      properties:
        jellyfinSeriesId:
          type: string
        jellyfinSeasonId:
          type: string
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/LibraryEpisode'
        code:
          type: string
          enum:
            [
              not_linked,
              server_unreachable,
              unsupported_media_server,
              not_found,
            ]
    DiscordSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
        options:
          type: object
          properties:
            botUsername:
              type: string
            botAvatarUrl:
              type: string
            webhookUrl:
              type: string
            webhookRoleId:
              type: string
            enableMentions:
              type: boolean
    SlackSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
        options:
          type: object
          properties:
            webhookUrl:
              type: string
    WebPushSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
    WebhookSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
        options:
          type: object
          properties:
            webhookUrl:
              type: string
            authHeader:
              type: string
            jsonPayload:
              type: string
            supportVariables:
              type: boolean
              example: false
    TelegramSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
        options:
          type: object
          properties:
            botUsername:
              type: string
            botAPI:
              type: string
            chatId:
              type: string
            messageThreadId:
              type: string
            sendSilently:
              type: boolean
    PushbulletSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
        options:
          type: object
          properties:
            accessToken:
              type: string
            channelTag:
              type: string
              nullable: true
    PushoverSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
        options:
          type: object
          properties:
            accessToken:
              type: string
            userToken:
              type: string
            sound:
              type: string
    GotifySettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
        options:
          type: object
          properties:
            url:
              type: string
            token:
              type: string
    NtfySettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
        options:
          type: object
          properties:
            url:
              type: string
            topic:
              type: string
            authMethodUsernamePassword:
              type: boolean
            username:
              type: string
            password:
              type: string
            authMethodToken:
              type: boolean
            token:
              type: string
            priority:
              type: number
            locale:
              type: string
    NotificationEmailSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
        options:
          type: object
          properties:
            emailFrom:
              type: string
              example: no-reply@example.com
            senderName:
              type: string
              example: Foreseerr
            smtpHost:
              type: string
              example: 127.0.0.1
            smtpPort:
              type: number
              example: 465
            secure:
              type: boolean
              example: false
            ignoreTls:
              type: boolean
              example: false
            requireTls:
              type: boolean
              example: false
            authUser:
              type: string
              nullable: true
            authPass:
              type: string
              nullable: true
            allowSelfSigned:
              type: boolean
              example: false
    Job:
      type: object
      properties:
        id:
          type: string
          example: job-name
        type:
          type: string
          enum: [process, command]
        interval:
          type: string
          enum: [short, long, fixed]
        name:
          type: string
          example: A Job Name
        nextExecutionTime:
          type: string
          example: '2020-09-02T05:02:23.000Z'
        running:
          type: boolean
          example: false
    PersonDetails:
      type: object
      properties:
        id:
          type: number
          example: 1
        name:
          type: string
        deathday:
          type: string
        knownForDepartment:
          type: string
        alsoKnownAs:
          type: array
          items:
            type: string
        gender:
          type: string
        biography:
          type: string
        popularity:
          type: string
        placeOfBirth:
          type: string
        profilePath:
          type: string
        adult:
          type: boolean
        imdbId:
          type: string
        homepage:
          type: string
    CreditCast:
      type: object
      properties:
        id:
          type: number
          example: 1
        originalLanguage:
          type: string
        episodeCount:
          type: number
        overview:
          type: string
        originCountry:
          type: array
          items:
            type: string
        originalName:
          type: string
        voteCount:
          type: number
        name:
          type: string
        mediaType:
          type: string
        popularity:
          type: number
        creditId:
          type: string
        backdropPath:
          type: string
        firstAirDate:
          type: string
        voteAverage:
          type: number
        genreIds:
          type: array
          items:
            type: number
        posterPath:
          type: string
        originalTitle:
          type: string
        video:
          type: boolean
        title:
          type: string
        adult:
          type: boolean
        releaseDate:
          type: string
        character:
          type: string
        mediaInfo:
          $ref: '#/components/schemas/MediaInfo'
    CreditCrew:
      type: object
      properties:
        id:
          type: number
          example: 1
        originalLanguage:
          type: string
        episodeCount:
          type: number
        overview:
          type: string
        originCountry:
          type: array
          items:
            type: string
        originalName:
          type: string
        voteCount:
          type: number
        name:
          type: string
        mediaType:
          type: string
        popularity:
          type: number
        creditId:
          type: string
        backdropPath:
          type: string
        firstAirDate:
          type: string
        voteAverage:
          type: number
        genreIds:
          type: array
          items:
            type: number
        posterPath:
          type: string
        originalTitle:
          type: string
        video:
          type: boolean
        title:
          type: string
        adult:
          type: boolean
        releaseDate:
          type: string
        department:
          type: string
        job:
          type: string
        mediaInfo:
          $ref: '#/components/schemas/MediaInfo'
    Keyword:
      type: object
      properties:
        id:
          type: number
          example: 1
        name:
          type: string
          example: 'anime'
    SpokenLanguage:
      type: object
      properties:
        englishName:
          type: string
          example: 'English'
          nullable: true
        iso_639_1:
          type: string
          example: 'en'
        name:
          type: string
          example: 'English'
    Collection:
      type: object
      properties:
        id:
          type: number
          example: 123
        name:
          type: string
          example: A Movie Collection
        overview:
          type: string
          example: Overview of collection
        posterPath:
          type: string
        backdropPath:
          type: string
        parts:
          type: array
          items:
            $ref: '#/components/schemas/MovieResult'
    SonarrSeries:
      type: object
      properties:
        title:
          type: string
          example: COVID-25
        sortTitle:
          type: string
          example: covid 25
        seasonCount:
          type: number
          example: 1
        status:
          type: string
          example: upcoming
        overview:
          type: string
          example: The thread is picked up again by Marianne Schmidt which ...
        network:
          type: string
          example: CBS
        airTime:
          type: string
          example: 02:15
        images:
          type: array
          items:
            type: object
            properties:
              coverType:
                type: string
                example: banner
              url:
                type: string
                example: /sonarr/MediaCoverProxy/6467f05d9872726ad08cbf920e5fee4bf69198682260acab8eab5d3c2c958e92/5c8f116c6aa5c.jpg
        remotePoster:
          type: string
          example: https://artworks.thetvdb.com/banners/posters/5c8f116129983.jpg
        seasons:
          type: array
          items:
            type: object
            properties:
              seasonNumber:
                type: number
                example: 1
              monitored:
                type: boolean
                example: true
        year:
          type: number
          example: 2015
        path:
          type: string
        profileId:
          type: number
        languageProfileId:
          type: number
        seasonFolder:
          type: boolean
        monitored:
          type: boolean
        useSceneNumbering:
          type: boolean
        runtime:
          type: number
        tvdbId:
          type: number
          example: 12345
        tvRageId:
          type: number
        tvMazeId:
          type: number
        firstAired:
          type: string
        lastInfoSync:
          type: string
          nullable: true
        seriesType:
          type: string
        cleanTitle:
          type: string
        imdbId:
          type: string
        titleSlug:
          type: string
        certification:
          type: string
        genres:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        added:
          type: string
        ratings:
          type: array
          items:
            type: object
            properties:
              votes:
                type: number
              value:
                type: number
        qualityProfileId:
          type: number
        id:
          type: number
          nullable: true
        rootFolderPath:
          type: string
          nullable: true
        addOptions:
          type: array
          items:
            type: object
            properties:
              ignoreEpisodesWithFiles:
                type: boolean
                nullable: true
              ignoreEpisodesWithoutFiles:
                type: boolean
                nullable: true
              searchForMissingEpisodes:
                type: boolean
                nullable: true
    UserSettingsNotifications:
      type: object
      properties:
        notificationTypes:
          $ref: '#/components/schemas/NotificationAgentTypes'
        emailEnabled:
          type: boolean
        pgpKey:
          type: string
          nullable: true
        discordEnabled:
          type: boolean
        discordEnabledTypes:
          type: number
          nullable: true
        discordIds:
          type: array
          items:
            type: string
          nullable: true
        pushbulletAccessToken:
          type: string
          nullable: true
        pushoverApplicationToken:
          type: string
          nullable: true
        pushoverUserKey:
          type: string
          nullable: true
        pushoverSound:
          type: string
          nullable: true
        telegramEnabled:
          type: boolean
        telegramBotUsername:
          type: string
          nullable: true
        telegramChatId:
          type: string
          nullable: true
        telegramMessageThreadId:
          type: string
          nullable: true
        telegramSendSilently:
          type: boolean
          nullable: true
    NotificationAgentTypes:
      type: object
      properties:
        discord:
          type: number
        email:
          type: number
        pushbullet:
          type: number
        pushover:
          type: number
        slack:
          type: number
        telegram:
          type: number
        webhook:
          type: number
        webpush:
          type: number
    WatchProviders:
      type: array
      items:
        type: object
        properties:
          iso_3166_1:
            type: string
          link:
            type: string
          buy:
            type: array
            items:
              $ref: '#/components/schemas/WatchProviderDetails'
          flatrate:
            items:
              $ref: '#/components/schemas/WatchProviderDetails'
    WatchProviderDetails:
      type: object
      properties:
        displayPriority:
          type: number
        logoPath:
          type: string
        id:
          type: number
        name:
          type: string
    Issue:
      type: object
      properties:
        id:
          type: number
          example: 1
        issueType:
          type: number
          example: 1
        media:
          $ref: '#/components/schemas/MediaInfo'
        createdBy:
          $ref: '#/components/schemas/User'
        modifiedBy:
          $ref: '#/components/schemas/User'
        comments:
          type: array
          items:
            $ref: '#/components/schemas/IssueComment'
    IssueComment:
      type: object
      properties:
        id:
          type: number
          example: 1
        user:
          $ref: '#/components/schemas/User'
        message:
          type: string
          example: A comment
    DiscoverSlider:
      type: object
      properties:
        id:
          type: number
          example: 1
        type:
          type: number
          example: 1
        title:
          type: string
          nullable: true
        isBuiltIn:
          type: boolean
        enabled:
          type: boolean
        data:
          type: string
          example: '1234'
          nullable: true
      required:
        - type
        - enabled
        - title
        - data
    WatchProviderRegion:
      type: object
      properties:
        iso_3166_1:
          type: string
        english_name:
          type: string
        native_name:
          type: string
    OverrideRule:
      type: object
      properties:
        id:
          type: string
    Certification:
      type: object
      properties:
        certification:
          type: string
          example: 'PG-13'
        meaning:
          type: string
          example: 'Some material may be inappropriate for children under 13.'
          nullable: true
        order:
          type: number
          example: 3
          nullable: true
      required:
        - certification

    CertificationResponse:
      type: object
      properties:
        certifications:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Certification'
      example:
        certifications:
          US:
            - certification: 'G'
              meaning: 'All ages admitted'
              order: 1
            - certification: 'PG'
              meaning: 'Some material may not be suitable for children under 10.'
              order: 2
  parameters:
    DiscoverImdbRatingGte:
      in: query
      name: imdbRatingGte
      schema:
        type: number
        example: 7
      description: Minimum IMDb rating (1–10), applied post-fetch via MDBList
    DiscoverImdbRatingLte:
      in: query
      name: imdbRatingLte
      schema:
        type: number
        example: 10
      description: Maximum IMDb rating (1–10), applied post-fetch via MDBList
    DiscoverImdbVotesGte:
      in: query
      name: imdbVotesGte
      schema:
        type: number
        example: 1000
      description: Minimum IMDb vote count, applied post-fetch via MDBList
    DiscoverImdbVotesLte:
      in: query
      name: imdbVotesLte
      schema:
        type: number
        example: 100000
      description: Maximum IMDb vote count, applied post-fetch via MDBList
    DiscoverRtCriticsGte:
      in: query
      name: rtCriticsGte
      schema:
        type: number
        example: 60
      description: Minimum Rotten Tomatoes critics score (0–100), post-fetch via MDBList
    DiscoverRtCriticsLte:
      in: query
      name: rtCriticsLte
      schema:
        type: number
        example: 100
      description: Maximum Rotten Tomatoes critics score (0–100), post-fetch via MDBList
    DiscoverRtAudienceGte:
      in: query
      name: rtAudienceGte
      schema:
        type: number
        example: 60
      description: Minimum Rotten Tomatoes audience score (0–100), post-fetch via MDBList
    DiscoverRtAudienceLte:
      in: query
      name: rtAudienceLte
      schema:
        type: number
        example: 100
      description: Maximum Rotten Tomatoes audience score (0–100), post-fetch via MDBList
    DiscoverMetacriticGte:
      in: query
      name: metacriticGte
      schema:
        type: number
        example: 60
      description: Minimum Metacritic score (0–100), post-fetch via MDBList
    DiscoverMetacriticLte:
      in: query
      name: metacriticLte
      schema:
        type: number
        example: 100
      description: Maximum Metacritic score (0–100), post-fetch via MDBList
    DiscoverTraktRatingGte:
      in: query
      name: traktRatingGte
      schema:
        type: number
        example: 7
      description: Minimum Trakt rating (0–10), post-fetch via MDBList
    DiscoverTraktRatingLte:
      in: query
      name: traktRatingLte
      schema:
        type: number
        example: 10
      description: Maximum Trakt rating (0–10), post-fetch via MDBList
    DiscoverIncludeNoRating:
      in: query
      name: includeNoRating
      schema:
        type: boolean
        default: true
      description: When false, exclude titles missing required external ratings
    DiscoverGenre:
      in: query
      name: genre
      schema:
        type: string
        example: '18'
      description: Comma-separated TMDB genre IDs for post-fetch filtering
    DiscoverLanguage:
      in: query
      name: language
      schema:
        type: string
        example: en
      description: Original language ISO code for post-fetch filtering
    DiscoverPrimaryReleaseDateGte:
      in: query
      name: primaryReleaseDateGte
      schema:
        type: string
        example: 2020-01-01
      description: Minimum release date for post-fetch movie filtering
    DiscoverPrimaryReleaseDateLte:
      in: query
      name: primaryReleaseDateLte
      schema:
        type: string
        example: 2024-12-31
      description: Maximum release date for post-fetch movie filtering
    DiscoverFirstAirDateGte:
      in: query
      name: firstAirDateGte
      schema:
        type: string
        example: 2020-01-01
      description: Minimum first air date for post-fetch TV filtering
    DiscoverFirstAirDateLte:
      in: query
      name: firstAirDateLte
      schema:
        type: string
        example: 2024-12-31
      description: Maximum first air date for post-fetch TV filtering
    DiscoverVoteAverageGte:
      in: query
      name: voteAverageGte
      schema:
        type: number
        example: 7
      description: Minimum TMDB vote average for post-fetch filtering
    DiscoverVoteAverageLte:
      in: query
      name: voteAverageLte
      schema:
        type: number
        example: 10
      description: Maximum TMDB vote average for post-fetch filtering
    DiscoverVoteCountGte:
      in: query
      name: voteCountGte
      schema:
        type: number
        example: 100
      description: Minimum TMDB vote count for post-fetch filtering
    DiscoverVoteCountLte:
      in: query
      name: voteCountLte
      schema:
        type: number
        example: 10000
      description: Maximum TMDB vote count for post-fetch filtering
    DiscoverRuntimeGte:
      in: query
      name: withRuntimeGte
      schema:
        type: number
        example: 90
      description: Minimum runtime in minutes, applied post-fetch via TMDB
    DiscoverRuntimeLte:
      in: query
      name: withRuntimeLte
      schema:
        type: number
        example: 180
      description: Maximum runtime in minutes, applied post-fetch via TMDB
    DiscoverSeriesStatus:
      in: query
      name: status
      schema:
        type: string
        example: 3|4
      description: Series statuses (0 Returning, 1 Planned, 2 In Production, 3 Ended, 4 Canceled, 5 Pilot), applied post-fetch via TMDB
    DiscoverIgnoreWatched:
      in: query
      name: ignoreWatched
      schema:
        type: boolean
      description: >
        Hide titles the user has marked watched on Trakt. When omitted, the
        user's Discover filter defaults (ignoreWatched) are used.
    DiscoverIgnoreDefaults:
      in: query
      name: ignoreDiscoverDefaults
      schema:
        type: boolean
      description: Ignore persisted Discover filter defaults for this request.
    DiscoverIgnoreCollected:
      in: query
      name: ignoreCollected
      schema:
        type: boolean
      description: Hide titles already collected in the configured media server.
    DiscoverIgnoreWatchlisted:
      in: query
      name: ignoreWatchlisted
      schema:
        type: boolean
      description: Hide titles already present in the user's watchlist.
    DiscoverHideUnmapped:
      in: query
      name: hideUnmapped
      schema:
        type: boolean
      description: >
        Hide titles from third-party Discover sources that could not be mapped
        to TMDB. When omitted, the user's Discover filter defaults (hideUnmapped)
        are used.
  securitySchemes:
    cookieAuth:
      type: apiKey
      name: connect.sid
      in: cookie
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key

paths:
  /desktop/auth-tickets:
    post:
      summary: Issue a challenge-bound desktop authentication ticket
      tags: [auth]
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [challenge, protocolVersion]
              properties:
                challenge:
                  type: string
                  pattern: '^[a-f0-9]{64}$'
                protocolVersion:
                  type: integer
                  enum: [1]
      responses:
        '201':
          description: Single-use ticket issued
          headers:
            Cache-Control:
              schema: { type: string, enum: [no-store] }
          content:
            application/json:
              schema:
                type: object
                required: [ticket, expiresIn]
                properties:
                  ticket:
                    type: string
                    description: Sensitive single-use value; never log or cache.
                  expiresIn:
                    type: integer
        '401': { description: Authentication required }
        '403': { description: Browser cookie session required }
        '409': { description: Jellyfin account is not linked or unsupported }
        '429': { description: Rate limited }
  /desktop/auth-tickets/redeem:
    post:
      summary: Redeem a challenge-bound desktop authentication ticket
      tags: [auth]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ticket, verifier, protocolVersion]
              properties:
                ticket:
                  type: string
                  writeOnly: true
                  pattern: '^[A-Za-z0-9_-]{43}$'
                verifier:
                  type: string
                  writeOnly: true
                  pattern: '^[A-Za-z0-9_-]{43}$'
                protocolVersion:
                  type: integer
                  enum: [1]
      responses:
        '200':
          description: Native Jellyfin session bootstrap
          headers:
            Cache-Control:
              schema: { type: string, enum: [no-store] }
          content:
            application/json:
              schema:
                type: object
                required:
                  [
                    serverUrl,
                    serverId,
                    userId,
                    deviceId,
                    accessToken,
                    bootstrapGeneration,
                  ]
                properties:
                  serverUrl: { type: string, format: uri }
                  serverId: { type: string }
                  userId: { type: string }
                  deviceId: { type: string }
                  accessToken:
                    type: string
                    description: Sensitive native-only credential; response is no-store.
                  bootstrapGeneration: { type: string }
        '401':
          {
            description: 'Ticket, verifier, issuer session, or linked token invalid',
          }
        '409': { description: Ticket used or Jellyfin account not linked }
        '429': { description: Rate limited }
        '503': { description: Jellyfin server unavailable }
  /calendar:
    get:
      summary: Get release calendar entries
      tags: [calendar]
      parameters:
        - in: query
          name: start
          required: true
          description: Inclusive range start. YYYY-MM-DD keys are UTC midnight.
          schema:
            anyOf:
              - { type: string, format: date }
              - { type: string, format: date-time }
            example: '2026-08-01'
        - in: query
          name: end
          required: true
          description: Exclusive range end. YYYY-MM-DD keys are UTC midnight.
          schema:
            anyOf:
              - { type: string, format: date }
              - { type: string, format: date-time }
            example: '2026-09-12'
        - in: query
          name: scope
          schema: { type: string, enum: [mine, all], default: mine }
        - in: query
          name: mediaType
          schema: { type: string, enum: [movie, tv] }
        - in: query
          name: source
          schema: { type: string, enum: [sonarr, radarr] }
        - in: query
          name: serverId
          description: Administrator only.
          schema: { type: integer }
        - in: query
          name: is4k
          schema: { type: boolean }
        - in: query
          name: includeEpisodes
          schema: { type: boolean, default: true }
        - in: query
          name: includeUnmonitored
          description: Administrator only.
          schema: { type: boolean, default: false }
      responses:
        '200':
          description: Range-bounded normalized calendar results.
          content:
            application/json:
              schema:
                type: object
                required: [results]
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      required:
                        [id, mediaType, source, title, startsAt, dateType]
                      properties:
                        id: { type: integer }
                        mediaType: { type: string, enum: [movie, tv] }
                        source: { type: string, enum: [sonarr, radarr] }
                        title: { type: string }
                        subtitle: { type: string, nullable: true }
                        startsAt: { type: string, format: date-time }
                        allDay: { type: boolean }
                        dateType:
                          {
                            type: string,
                            enum: [air, digital, physical, theatrical],
                          }
                        requestedByCurrentUser: { type: boolean }
                        available: { type: boolean }
                        watchUrl: { type: string, format: uri, nullable: true }
                        jellyfinItemId: { type: string, nullable: true }
                  partialSources:
                    type: array
                    items: { type: object }
        '400': { description: Invalid range or filter. }
        '401': { description: Unauthorized. }
        '403': { description: Administrator-only filter requested. }
  /status:
    get:
      summary: Get Foreseerr status
      description: Returns the current Foreseerr status in a JSON object. updateAvailable and commitsBehind are omitted when checkUpdateAvailable is false.
      security: []
      tags:
        - public
      parameters:
        - in: query
          name: checkUpdateAvailable
          description: If false, updateAvailable and commitsBehind will be omitted from the response. Defaults to the versionCheck setting.
          required: false
          example: false
          schema:
            type: boolean
      responses:
        '200':
          description: Returned status
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: 1.0.0
                  commitTag:
                    type: string
                  updateAvailable:
                    type: boolean
                  commitsBehind:
                    type: number
                  restartRequired:
                    type: boolean
  /status/appdata:
    get:
      summary: Get application data volume status
      description: For Docker installs, returns whether or not the volume mount was configured properly. Always returns true for non-Docker installs.
      security: []
      tags:
        - public
      responses:
        '200':
          description: Application data volume status and path
          content:
            application/json:
              schema:
                type: object
                properties:
                  appData:
                    type: boolean
                    example: true
                  appDataPath:
                    type: string
                    example: /app/config
                  appDataPermissions:
                    type: boolean
                    example: true
  /settings/main:
    get:
      summary: Get main settings
      description: Retrieves all main settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MainSettings'
    post:
      summary: Update main settings
      description: Updates main settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MainSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MainSettings'
  /settings/servarr-interventions:
    get:
      summary: Get Servarr intervention cleanup settings
      description: Requires `ADMIN`.
      tags: [settings]
      responses:
        '200':
          description: Current cleanup policy
          content:
            application/json:
              schema:
                { $ref: '#/components/schemas/ServarrInterventionSettings' }
        '401': { description: Unauthorized }
        '403': { description: Insufficient permission }
    post:
      summary: Update Servarr intervention cleanup settings
      description: The grace period applies only to warnings detected after this change. Requires `ADMIN`.
      tags: [settings]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ServarrInterventionSettings' }
      responses:
        '200': { description: Updated cleanup policy }
        '400':
          { description: Invalid boolean or grace period outside 1–720 hours }
        '401': { description: Unauthorized }
        '403': { description: Insufficient permission }
  /settings/network:
    get:
      summary: Get network settings
      description: Retrieves all network settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MainSettings'
    post:
      summary: Update network settings
      description: Updates network settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetworkSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkSettings'
  /settings/main/regenerate:
    post:
      summary: Get main settings with newly-generated API key
      description: Returns main settings in a JSON object, using the new API key.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MainSettings'
  /settings/jellyfin:
    get:
      summary: Get Jellyfin settings
      description: Retrieves current Jellyfin settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JellyfinSettings'
    post:
      summary: Update Jellyfin settings
      description: Updates Jellyfin settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JellyfinSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JellyfinSettings'
  /settings/jellyfin/library:
    get:
      summary: Get Jellyfin libraries
      description: Returns a list of Jellyfin libraries in a JSON array.
      tags:
        - settings
      parameters:
        - in: query
          name: sync
          description: Syncs the current libraries with the current Jellyfin server
          schema:
            type: string
            nullable: true
        - in: query
          name: enable
          explode: false
          allowReserved: true
          description: Comma separated list of libraries to enable. Any libraries not passed will be disabled!
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: 'Jellyfin libraries returned'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JellyfinLibrary'
  /settings/jellyfin/users:
    get:
      summary: Get Jellyfin Users
      description: Returns a list of Jellyfin Users in a JSON array.
      tags:
        - settings
        - users
      responses:
        '200':
          description: Jellyfin users returned
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    username:
                      type: string
                    id:
                      type: string
                    thumb:
                      type: string
                    email:
                      type: string
  /settings/jellyfin/sync:
    get:
      summary: Get status of full Jellyfin library sync
      description: Returns sync progress in a JSON array.
      tags:
        - settings
      responses:
        '200':
          description: Status of Jellyfin sync
          content:
            application/json:
              schema:
                type: object
                properties:
                  running:
                    type: boolean
                    example: false
                  progress:
                    type: number
                    example: 0
                  total:
                    type: number
                    example: 100
                  currentLibrary:
                    $ref: '#/components/schemas/JellyfinLibrary'
                  libraries:
                    type: array
                    items:
                      $ref: '#/components/schemas/JellyfinLibrary'
    post:
      summary: Start full Jellyfin library sync
      description: Runs a full Jellyfin library sync and returns the progress in a JSON array.
      tags:
        - settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cancel:
                  type: boolean
                  example: false
                start:
                  type: boolean
                  example: false
      responses:
        '200':
          description: Status of Jellyfin sync
          content:
            application/json:
              schema:
                type: object
                properties:
                  running:
                    type: boolean
                    example: false
                  progress:
                    type: number
                    example: 0
                  total:
                    type: number
                    example: 100
                  currentLibrary:
                    $ref: '#/components/schemas/JellyfinLibrary'
                  libraries:
                    type: array
                    items:
                      $ref: '#/components/schemas/JellyfinLibrary'
  /settings/plex:
    get:
      summary: Get Plex settings
      description: Retrieves current Plex settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlexSettings'
    post:
      summary: Update Plex settings
      description: Updates Plex settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlexSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlexSettings'
  /settings/plex/library:
    get:
      summary: Get Plex libraries
      description: Returns a list of Plex libraries in a JSON array.
      tags:
        - settings
      parameters:
        - in: query
          name: sync
          description: Syncs the current libraries with the current Plex server
          schema:
            type: string
            nullable: true
        - in: query
          name: enable
          explode: false
          allowReserved: true
          description: Comma separated list of libraries to enable. Any libraries not passed will be disabled!
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: 'Plex libraries returned'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlexLibrary'
  /settings/plex/sync:
    get:
      summary: Get status of full Plex library scan
      description: Returns scan progress in a JSON array.
      tags:
        - settings
      responses:
        '200':
          description: Status of Plex scan
          content:
            application/json:
              schema:
                type: object
                properties:
                  running:
                    type: boolean
                    example: false
                  progress:
                    type: number
                    example: 0
                  total:
                    type: number
                    example: 100
                  currentLibrary:
                    $ref: '#/components/schemas/PlexLibrary'
                  libraries:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlexLibrary'
    post:
      summary: Start full Plex library scan
      description: Runs a full Plex library scan and returns the progress in a JSON array.
      tags:
        - settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cancel:
                  type: boolean
                  example: false
                start:
                  type: boolean
                  example: false
      responses:
        '200':
          description: Status of Plex scan
          content:
            application/json:
              schema:
                type: object
                properties:
                  running:
                    type: boolean
                    example: false
                  progress:
                    type: number
                    example: 0
                  total:
                    type: number
                    example: 100
                  currentLibrary:
                    $ref: '#/components/schemas/PlexLibrary'
                  libraries:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlexLibrary'
  /settings/plex/devices/servers:
    get:
      summary: Gets the user's available Plex servers
      description: Returns a list of available Plex servers and their connectivity state
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlexDevice'
  /settings/plex/users:
    get:
      summary: Get Plex users
      description: |
        Returns a list of Plex users in a JSON array.

        Requires the `MANAGE_USERS` permission.
      tags:
        - settings
        - users
      responses:
        '200':
          description: Plex users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    title:
                      type: string
                    username:
                      type: string
                    email:
                      type: string
                    thumb:
                      type: string
  /settings/metadatas:
    get:
      summary: Get Metadata settings
      description: Retrieves current Metadata settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataSettings'
    put:
      summary: Update Metadata settings
      description: Updates Metadata settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataSettings'
  /settings/metadatas/test:
    post:
      summary: Test Provider configuration
      description: Tests if the TVDB configuration is valid. Returns a list of available languages on success.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tmdb:
                  type: boolean
                  example: true
                tvdb:
                  type: boolean
                  example: true
      responses:
        '200':
          description: Succesfully connected to TVDB
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Successfully connected to TVDB'
  /settings/tautulli:
    get:
      summary: Get Tautulli settings
      description: Retrieves current Tautulli settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TautulliSettings'
    post:
      summary: Update Tautulli settings
      description: Updates Tautulli settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TautulliSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TautulliSettings'
  /settings/trakt:
    get:
      summary: Get Trakt settings
      description: Retrieves current Trakt application credentials (secret masked).
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraktSettings'
    post:
      summary: Update Trakt settings
      description: Updates Trakt application Client ID and Client Secret.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraktSettings'
      responses:
        '200':
          description: Values were successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraktSettings'
  /settings/integrations/status:
    get:
      summary: Check integration health
      description: Checks whether configured Trakt, MDBList, and AniList integrations are currently reachable.
      tags:
        - settings
      responses:
        '200':
          description: Integration health returned
  /settings/integrations/status/refresh:
    post:
      summary: Refresh integration health
      description: Clears cached integration health and runs non-mutating checks immediately.
      tags:
        - settings
      responses:
        '200':
          description: Integration health refreshed
  /settings/trakt/actions:
    post:
      summary: Update Trakt media actions
      description: Enables or disables watched and rating actions independently of the active Trakt connection method.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - actionsEnabled
              properties:
                actionsEnabled:
                  type: boolean
      responses:
        '200':
          description: Trakt media actions updated
  /settings/anilist:
    get:
      summary: Get AniList settings
      description: Retrieves current AniList application credentials (secret masked).
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AniListSettings'
    post:
      summary: Update AniList settings
      description: Updates AniList application Client ID and Client Secret. The developer app Redirect URL must be https://anilist.co/api/v2/oauth/pin.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AniListSettings'
      responses:
        '200':
          description: Values were successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AniListSettings'
  /settings/anilist/actions:
    post:
      summary: Enable or disable AniList media actions
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - actionsEnabled
              properties:
                actionsEnabled:
                  type: boolean
      responses:
        '200':
          description: AniList media actions updated
  /settings/mdblist:
    get:
      summary: Get MDBList settings
      description: Retrieves MDBList API key (masked) and rating badge visibility toggles.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MdbListSettings'
    post:
      summary: Update MDBList settings
      description: Updates MDBList API key and which rating badges to display.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MdbListSettings'
      responses:
        '200':
          description: Values were successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MdbListSettings'
  /settings/radarr:
    get:
      summary: Get Radarr settings
      description: Returns all Radarr settings in a JSON array.
      tags:
        - settings
      responses:
        '200':
          description: 'Values were returned'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RadarrSettings'
    post:
      summary: Create Radarr instance
      description: Creates a new Radarr instance from the request body.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RadarrSettings'
      responses:
        '201':
          description: 'New Radarr instance created'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarrSettings'
  /settings/radarr/test:
    post:
      summary: Test Radarr configuration
      description: Tests if the Radarr configuration is valid. Returns profiles and root folders on success.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hostname:
                  type: string
                  example: '127.0.0.1'
                port:
                  type: number
                  example: 7878
                apiKey:
                  type: string
                  example: yourapikey
                useSsl:
                  type: boolean
                  example: false
                baseUrl:
                  type: string
              required:
                - hostname
                - port
                - apiKey
                - useSsl
      responses:
        '200':
          description: Succesfully connected to Radarr instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceProfile'
  /settings/radarr/{radarrId}:
    put:
      summary: Update Radarr instance
      description: Updates an existing Radarr instance with the provided values.
      tags:
        - settings
      parameters:
        - in: path
          name: radarrId
          required: true
          schema:
            type: integer
          description: Radarr instance ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RadarrSettings'
      responses:
        '200':
          description: 'Radarr instance updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarrSettings'
    delete:
      summary: Delete Radarr instance
      description: Deletes an existing Radarr instance based on the radarrId parameter.
      tags:
        - settings
      parameters:
        - in: path
          name: radarrId
          required: true
          schema:
            type: integer
          description: Radarr instance ID
      responses:
        '200':
          description: 'Radarr instance updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarrSettings'
  /settings/radarr/{radarrId}/profiles:
    get:
      summary: Get available Radarr profiles
      description: Returns a list of profiles available on the Radarr server instance in a JSON array.
      tags:
        - settings
      parameters:
        - in: path
          name: radarrId
          required: true
          schema:
            type: integer
          description: Radarr instance ID
      responses:
        '200':
          description: Returned list of profiles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceProfile'
  /settings/sonarr:
    get:
      summary: Get Sonarr settings
      description: Returns all Sonarr settings in a JSON array.
      tags:
        - settings
      responses:
        '200':
          description: 'Values were returned'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SonarrSettings'
    post:
      summary: Create Sonarr instance
      description: Creates a new Sonarr instance from the request body.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SonarrSettings'
      responses:
        '201':
          description: 'New Sonarr instance created'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SonarrSettings'
  /settings/sonarr/test:
    post:
      summary: Test Sonarr configuration
      description: Tests if the Sonarr configuration is valid. Returns profiles and root folders on success.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hostname:
                  type: string
                  example: '127.0.0.1'
                port:
                  type: number
                  example: 8989
                apiKey:
                  type: string
                  example: yourapikey
                useSsl:
                  type: boolean
                  example: false
                baseUrl:
                  type: string
              required:
                - hostname
                - port
                - apiKey
                - useSsl
      responses:
        '200':
          description: Succesfully connected to Sonarr instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceProfile'
  /settings/sonarr/{sonarrId}:
    put:
      summary: Update Sonarr instance
      description: Updates an existing Sonarr instance with the provided values.
      tags:
        - settings
      parameters:
        - in: path
          name: sonarrId
          required: true
          schema:
            type: integer
          description: Sonarr instance ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SonarrSettings'
      responses:
        '200':
          description: 'Sonarr instance updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SonarrSettings'
    delete:
      summary: Delete Sonarr instance
      description: Deletes an existing Sonarr instance based on the sonarrId parameter.
      tags:
        - settings
      parameters:
        - in: path
          name: sonarrId
          required: true
          schema:
            type: integer
          description: Sonarr instance ID
      responses:
        '200':
          description: 'Sonarr instance updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SonarrSettings'
  /settings/public:
    get:
      summary: Get public settings
      security: []
      description: Returns settings that are not protected or sensitive. Mainly used to determine if the application has been configured for the first time.
      tags:
        - settings
      responses:
        '200':
          description: Public settings returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSettings'
  /settings/initialize:
    post:
      summary: Initialize application
      description: Sets the app as initialized, allowing the user to navigate to pages other than the setup page.
      tags:
        - settings
      responses:
        '200':
          description: Public settings returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSettings'
  /settings/jobs:
    get:
      summary: Get scheduled jobs
      description: Returns list of all scheduled jobs and details about their next execution time in a JSON array.
      tags:
        - settings
      responses:
        '200':
          description: Scheduled jobs returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
  /settings/jobs/{jobId}/run:
    post:
      summary: Invoke a specific job
      description: Invokes a specific job to run. Will return the new job status in JSON format.
      tags:
        - settings
      parameters:
        - in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Invoked job returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
  /settings/jobs/{jobId}/cancel:
    post:
      summary: Cancel a specific job
      description: Cancels a specific job. Will return the new job status in JSON format.
      tags:
        - settings
      parameters:
        - in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Canceled job returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
  /settings/jobs/{jobId}/schedule:
    post:
      summary: Modify job schedule
      description: Re-registers the job with the schedule specified. Will return the job in JSON format.
      tags:
        - settings
      parameters:
        - in: path
          name: jobId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                schedule:
                  type: string
                  example: '0 */5 * * * *'
      responses:
        '200':
          description: Rescheduled job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
  /settings/mapping/health:
    get:
      summary: Get mapping health
      description: |
        Returns the state of the media id mapping layer: open gaps and their
        causes, per-source budgets and circuit-breaker state, daily request
        volume, registered packs, and live resolvers.
      tags:
        - settings
      responses:
        '200':
          description: Mapping health returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingHealth'
  /settings/mapping/gaps:
    get:
      summary: List mapping gaps
      description: Unresolved discover items, most-seen first.
      tags:
        - settings
      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum: [open, resolved, ignored]
            default: open
        - in: query
          name: discoverSource
          schema:
            type: string
        - in: query
          name: take
          schema:
            type: number
            default: 50
        - in: query
          name: skip
          schema:
            type: number
            default: 0
      responses:
        '200':
          description: Mapping gaps returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MappingGap'
                  total:
                    type: number
  /settings/mapping/gaps/suggest:
    post:
      summary: Suggest matches for open gaps
      description: |
        Runs the quarantined title/year/episode-count heuristic over the busiest
        open gaps and stores each guess on its gap for review. Suggestions are
        never used by the resolver chain and never written to the mapping graph.
      tags:
        - settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: number
                  default: 50
      responses:
        '200':
          description: Sweep finished
          content:
            application/json:
              schema:
                type: object
                properties:
                  examined:
                    type: number
                  suggested:
                    type: number
  /settings/mapping/gaps/{gapId}/resolve:
    post:
      summary: Resolve a mapping gap
      description: |
        Stores an admin correction as an override, or marks the gap ignored. An
        empty `toExternalId` records a genuine absence and stops the resolver
        chain re-asking on every render.
      tags:
        - settings
      parameters:
        - in: path
          name: gapId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ignore:
                  type: boolean
                toNamespace:
                  $ref: '#/components/schemas/MappingNamespace'
                toExternalId:
                  type: string
                toSeason:
                  type: number
                  nullable: true
                note:
                  type: string
      responses:
        '200':
          description: Gap resolved
        '400':
          description: Unknown namespace
        '404':
          description: Gap not found
  /settings/mapping/overrides:
    get:
      summary: List mapping overrides
      tags:
        - settings
      responses:
        '200':
          description: Overrides returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MappingOverride'
    post:
      summary: Create a mapping override
      description: Creates a correction directly, without a queued gap.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MappingOverride'
      responses:
        '200':
          description: Override saved
        '400':
          description: Unknown namespace or missing source id
  /settings/mapping/overrides/import:
    post:
      summary: Import mapping overrides
      description: Replaces or merges overrides from an exported JSON payload.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                overrides:
                  type: array
                  items:
                    $ref: '#/components/schemas/MappingOverride'
      responses:
        '200':
          description: Import finished
          content:
            application/json:
              schema:
                type: object
                properties:
                  imported:
                    type: number
                  skipped:
                    type: number
  /settings/mapping/overrides/{overrideId}:
    delete:
      summary: Delete a mapping override
      tags:
        - settings
      parameters:
        - in: path
          name: overrideId
          required: true
          schema:
            type: number
      responses:
        '204':
          description: Override deleted
  /settings/mapping/sources:
    get:
      summary: List mapping sources
      description: Registered packs and live resolvers, with the manifest entries available to add.
      tags:
        - settings
      responses:
        '200':
          description: Sources returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MappingSource'
                  available:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        format:
                          type: string
                        mirrors:
                          type: array
                          items:
                            type: string
                        licence:
                          type: string
                        legalNote:
                          type: string
  /settings/mapping/sources/{sourceKey}:
    post:
      summary: Update a mapping source
      description: Enable or disable a source and tune its priority, trust and budget.
      tags:
        - settings
      parameters:
        - in: path
          name: sourceKey
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                priority:
                  type: number
                trust:
                  type: number
                rps:
                  type: number
                burst:
                  type: number
                concurrency:
                  type: number
                dailyQuota:
                  type: number
                  nullable: true
      responses:
        '200':
          description: Source updated
  /settings/mapping/sources/{sourceKey}/refresh:
    post:
      summary: Refresh a mapping pack
      description: Fetches the pack now, validating before it replaces the working copy.
      tags:
        - settings
      parameters:
        - in: path
          name: sourceKey
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Refresh finished
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    type: string
                  status:
                    type: string
                    enum: [downloaded, notModified, lastGood, skipped, failed]
                  records:
                    type: number
                  clusters:
                    type: number
                  error:
                    type: string
        '404':
          description: Unknown pack
  /settings/mapping/sources/{sourceKey}/reset-circuit:
    post:
      summary: Reset a source circuit breaker
      tags:
        - settings
      parameters:
        - in: path
          name: sourceKey
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Circuit breaker reset
  /settings/cache:
    get:
      summary: Get a list of active caches
      description: Retrieves a list of all active caches and their current stats.
      tags:
        - settings
      responses:
        '200':
          description: Caches returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  imageCache:
                    type: object
                    properties:
                      tmdb:
                        type: object
                        properties:
                          size:
                            type: number
                            example: 123456
                          imageCount:
                            type: number
                            example: 123
                      tvdb:
                        type: object
                        properties:
                          size:
                            type: number
                            example: 123456
                          imageCount:
                            type: number
                            example: 123
                      avatar:
                        type: object
                        properties:
                          size:
                            type: number
                            example: 123456
                          imageCount:
                            type: number
                            example: 123
                      anilist:
                        type: object
                        properties:
                          size:
                            type: number
                            example: 123456
                          imageCount:
                            type: number
                            example: 123
                      simkl:
                        type: object
                        properties:
                          size:
                            type: number
                            example: 123456
                          imageCount:
                            type: number
                            example: 123
                  images:
                    type: object
                    properties:
                      usedBytes:
                        type: number
                      entries:
                        type: number
                      highWaterBytes:
                        type: number
                      trimTargetBytes:
                        type: number
                      idleDays:
                        type: number
                        example: 7
                  dnsCache:
                    type: object
                    properties:
                      stats:
                        type: object
                        properties:
                          size:
                            type: number
                            example: 1
                          maxSize:
                            type: number
                            example: 500
                          hits:
                            type: number
                            example: 19
                          misses:
                            type: number
                            example: 1
                          failures:
                            type: number
                            example: 0
                          ipv4Fallbacks:
                            type: number
                            example: 0
                          hitRate:
                            type: number
                            example: 0.95
                      entries:
                        type: array
                        additionalProperties:
                          type: object
                          properties:
                            addresses:
                              type: object
                              properties:
                                ipv4:
                                  type: number
                                  example: 1
                                ipv6:
                                  type: number
                                  example: 1
                            activeAddress:
                              type: string
                              example: 127.0.0.1
                            family:
                              type: number
                              example: 4
                            age:
                              type: number
                              example: 10
                            ttl:
                              type: number
                              example: 10
                            networkErrors:
                              type: number
                              example: 0
                            hits:
                              type: number
                              example: 1
                            misses:
                              type: number
                              example: 1
                  apiCaches:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: cache-id
                        name:
                          type: string
                          example: cache name
                        stats:
                          type: object
                          properties:
                            hits:
                              type: number
                            misses:
                              type: number
                            keys:
                              type: number
                            ksize:
                              type: number
                            vsize:
                              type: number
  /settings/cache/{cacheId}/flush:
    post:
      summary: Flush a specific cache
      description: Flushes all data from the cache ID provided
      tags:
        - settings
      parameters:
        - in: path
          name: cacheId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 'Flushed cache'
  /settings/cache/dns/{dnsEntry}/flush:
    post:
      summary: Flush a specific DNS cache entry
      description: Flushes a specific DNS cache entry
      tags:
        - settings
      parameters:
        - in: path
          name: dnsEntry
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 'Flushed dns cache'
  /settings/logs:
    get:
      summary: Returns logs
      description: Returns list of all log items and details
      tags:
        - settings
      parameters:
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 25
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
        - in: query
          name: filter
          schema:
            type: string
            nullable: true
            enum: [debug, info, warn, error]
            default: debug
        - in: query
          name: search
          schema:
            type: string
            nullable: true
            example: plex
      responses:
        '200':
          description: Server log returned
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    label:
                      type: string
                      example: server
                    level:
                      type: string
                      example: info
                    message:
                      type: string
                      example: Server ready on port 5055
                    timestamp:
                      type: string
                      example: '2020-12-15T16:20:00.069Z'
  /settings/notifications/email:
    get:
      summary: Get email notification settings
      description: Returns current email notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned email settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationEmailSettings'
    post:
      summary: Update email notification settings
      description: Updates email notification settings with provided values
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationEmailSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationEmailSettings'
  /settings/notifications/email/test:
    post:
      summary: Test email settings
      description: Sends a test notification to the email agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationEmailSettings'
      responses:
        '204':
          description: Test notification attempted
  /settings/notifications/discord:
    get:
      summary: Get Discord notification settings
      description: Returns current Discord notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned Discord settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordSettings'
    post:
      summary: Update Discord notification settings
      description: Updates Discord notification settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscordSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordSettings'
  /settings/notifications/discord/test:
    post:
      summary: Test Discord settings
      description: Sends a test notification to the Discord agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscordSettings'
      responses:
        '204':
          description: Test notification attempted
  /settings/notifications/pushbullet:
    get:
      summary: Get Pushbullet notification settings
      description: Returns current Pushbullet notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned Pushbullet settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushbulletSettings'
    post:
      summary: Update Pushbullet notification settings
      description: Update Pushbullet notification settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushbulletSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushbulletSettings'
  /settings/notifications/pushbullet/test:
    post:
      summary: Test Pushbullet settings
      description: Sends a test notification to the Pushbullet agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushbulletSettings'
      responses:
        '204':
          description: Test notification attempted
  /settings/notifications/pushover:
    get:
      summary: Get Pushover notification settings
      description: Returns current Pushover notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned Pushover settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushoverSettings'
    post:
      summary: Update Pushover notification settings
      description: Update Pushover notification settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushoverSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushoverSettings'
  /settings/notifications/pushover/test:
    post:
      summary: Test Pushover settings
      description: Sends a test notification to the Pushover agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushoverSettings'
      responses:
        '204':
          description: Test notification attempted
  /settings/notifications/pushover/sounds:
    get:
      summary: Get Pushover sounds
      description: Returns valid Pushover sound options in a JSON array.
      tags:
        - settings
      parameters:
        - in: query
          name: token
          required: true
          schema:
            type: string
            nullable: false
      responses:
        '200':
          description: Returned Pushover settings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    description:
                      type: string
  /settings/notifications/gotify:
    get:
      summary: Get Gotify notification settings
      description: Returns current Gotify notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned Gotify settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GotifySettings'
    post:
      summary: Update Gotify notification settings
      description: Update Gotify notification settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GotifySettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GotifySettings'
  /settings/notifications/gotify/test:
    post:
      summary: Test Gotify settings
      description: Sends a test notification to the Gotify agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GotifySettings'
      responses:
        '204':
          description: Test notification attempted
  /settings/notifications/ntfy:
    get:
      summary: Get ntfy.sh notification settings
      description: Returns current ntfy.sh notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned ntfy.sh settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfySettings'
    post:
      summary: Update ntfy.sh notification settings
      description: Update ntfy.sh notification settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NtfySettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NtfySettings'
  /settings/notifications/ntfy/test:
    post:
      summary: Test ntfy.sh settings
      description: Sends a test notification to the ntfy.sh agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NtfySettings'
      responses:
        '204':
          description: Test notification attempted
  /settings/notifications/slack:
    get:
      summary: Get Slack notification settings
      description: Returns current Slack notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned slack settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackSettings'
    post:
      summary: Update Slack notification settings
      description: Updates Slack notification settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackSettings'
  /settings/notifications/slack/test:
    post:
      summary: Test Slack settings
      description: Sends a test notification to the Slack agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackSettings'
      responses:
        '204':
          description: Test notification attempted
  /settings/notifications/telegram:
    get:
      summary: Get Telegram notification settings
      description: Returns current Telegram notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned Telegram settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelegramSettings'
    post:
      summary: Update Telegram notification settings
      description: Update Telegram notification settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelegramSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelegramSettings'
  /settings/notifications/telegram/test:
    post:
      summary: Test Telegram settings
      description: Sends a test notification to the Telegram agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelegramSettings'
      responses:
        '204':
          description: Test notification attempted
  /settings/notifications/webpush:
    get:
      summary: Get Web Push notification settings
      description: Returns current Web Push notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned web push settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebPushSettings'
    post:
      summary: Update Web Push notification settings
      description: Updates Web Push notification settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebPushSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebPushSettings'
  /settings/notifications/webpush/test:
    post:
      summary: Test Web Push settings
      description: Sends a test notification to the Web Push agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebPushSettings'
      responses:
        '204':
          description: Test notification attempted
  /settings/notifications/webhook:
    get:
      summary: Get webhook notification settings
      description: Returns current webhook notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned webhook settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSettings'
    post:
      summary: Update webhook notification settings
      description: Updates webhook notification settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSettings'
  /settings/notifications/webhook/test:
    post:
      summary: Test webhook settings
      description: Sends a test notification to the webhook agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSettings'
      responses:
        '204':
          description: Test notification attempted
  /settings/discover:
    get:
      summary: Get all discover sliders
      description: Returns all discovery sliders. Built-in and custom made.
      tags:
        - settings
      responses:
        '200':
          description: Returned all discovery sliders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DiscoverSlider'
    post:
      summary: Batch update all sliders.
      description: |
        Batch update all sliders at once. Should also be used for creation. Will only update sliders provided
        and will not delete any sliders not present in the request. If a slider is missing a required field,
        it will be ignored. Requires the `ADMIN` permission.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/DiscoverSlider'
      responses:
        '200':
          description: Returned all newly updated discovery sliders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DiscoverSlider'
  /settings/discover/{sliderId}:
    put:
      summary: Update a single slider
      description: |
        Updates a single slider and return the newly updated slider. Requires the `ADMIN` permission.
      tags:
        - settings
      parameters:
        - in: path
          name: sliderId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: 'Slider Title'
                type:
                  type: number
                  example: 1
                data:
                  type: string
                  example: '1'
      responses:
        '200':
          description: Returns newly added discovery slider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverSlider'
    delete:
      summary: Delete slider by ID
      description: Deletes the slider with the provided sliderId. Requires the `ADMIN` permission.
      tags:
        - settings
      parameters:
        - in: path
          name: sliderId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Slider successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverSlider'
  /settings/discover/add:
    post:
      summary: Add a new slider
      description: |
        Add a single slider and return the newly created slider. Requires the `ADMIN` permission.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: 'New Slider'
                type:
                  type: number
                  example: 1
                data:
                  type: string
                  example: '1'
      responses:
        '200':
          description: Returns newly added discovery slider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverSlider'
  /settings/discover/reset:
    get:
      summary: Reset all discover sliders
      description: Resets all discovery sliders to the default values. Requires the `ADMIN` permission.
      tags:
        - settings
      responses:
        '204':
          description: All sliders reset to defaults
  /settings/about:
    get:
      summary: Get server stats
      description: Returns current server stats in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned about settings
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: '1.0.0'
                  totalRequests:
                    type: number
                    example: 100
                  totalMediaItems:
                    type: number
                    example: 100
                  tz:
                    type: string
                    nullable: true
                    example: Asia/Tokyo
                  appDataPath:
                    type: string
                    example: /app/config
  /auth/me:
    get:
      summary: Get logged-in user
      description: Returns the currently logged-in user.
      tags:
        - auth
        - users
      responses:
        '200':
          description: Object containing the logged-in user in JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /auth/plex:
    post:
      summary: Sign in using a Plex token
      description: Takes an `authToken` (Plex token) to log the user in. Generates a session cookie for use in further requests. If the user does not exist, and there are no other users, then a user will be created with full admin privileges. If a user logs in with access to the main Plex server, they will also have an account created, but without any permissions.
      security: []
      tags:
        - auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                authToken:
                  type: string
              required:
                - authToken
  /auth/jellyfin:
    post:
      summary: Sign in using a Jellyfin username and password
      description: Takes the user's username and password to log the user in. Generates a session cookie for use in further requests. If the user does not exist, and there are no other users, then a user will be created with full admin privileges. If a user logs in with access to the Jellyfin server, they will also have an account created, but without any permissions.
      security: []
      tags:
        - auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
                hostname:
                  type: string
                email:
                  type: string
                serverType:
                  type: number
              required:
                - username
                - password
  /auth/jellyfin/quickconnect/initiate:
    post:
      summary: Initiate Jellyfin Quick Connect
      description: Initiates a Quick Connect session and returns a code for the user to authorize on their Jellyfin server.
      security: []
      tags:
        - auth
      responses:
        '200':
          description: Quick Connect session initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: '123456'
                  secret:
                    type: string
                    example: 'abc123def456'
        '500':
          description: Failed to initiate Quick Connect
  /auth/jellyfin/quickconnect/check:
    get:
      summary: Check Quick Connect authorization status
      description: Checks if the Quick Connect code has been authorized by the user.
      security: []
      tags:
        - auth
      parameters:
        - in: query
          name: secret
          required: true
          schema:
            type: string
          description: The secret returned from the initiate endpoint
      responses:
        '200':
          description: Authorization status returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticated:
                    type: boolean
                    example: false
        '404':
          description: Quick Connect session not found or expired
  /auth/jellyfin/quickconnect/authenticate:
    post:
      summary: Authenticate with Quick Connect
      description: Completes the Quick Connect authentication flow and creates a user session.
      security: []
      tags:
        - auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secret:
                  type: string
              required:
                - secret
      responses:
        '200':
          description: Successfully authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          description: Quick Connect not authorized or access denied
        '500':
          description: Authentication failed
  /auth/local:
    post:
      summary: Sign in using a local account
      description: Takes an `email` and a `password` to log the user in. Generates a session cookie for use in further requests.
      security: []
      tags:
        - auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                password:
                  type: string
              required:
                - email
                - password
  /auth/logout:
    post:
      summary: Sign out and clear session cookie
      description: Completely clear the session cookie and associated values, effectively signing the user out.
      tags:
        - auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'ok'
  /auth/reset-password:
    post:
      summary: Send a reset password email
      description: Sends a reset password email to the email if the user exists
      security: []
      tags:
        - users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'ok'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
              required:
                - email
  /auth/reset-password/{guid}:
    post:
      summary: Reset the password for a user
      description: Resets the password for a user if the given guid is connected to a user
      security: []
      tags:
        - users
      parameters:
        - in: path
          name: guid
          required: true
          schema:
            type: string
            example: '9afef5a7-ec89-4d5f-9397-261e96970b50'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'ok'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
              required:
                - password
  /user:
    get:
      summary: Get all users
      description: Returns all users in a JSON object.
      tags:
        - users
      parameters:
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 20
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
        - in: query
          name: sort
          schema:
            type: string
            enum: [created, updated, requests, displayname, usertype, role]
            default: created
        - in: query
          name: sortDirection
          description: |
            Sort direction. When omitted, the server chooses the direction per sort
            field (e.g. displayname defaults to asc, requests/updated to desc).
          schema:
            type: string
            enum: [asc, desc]
        - in: query
          name: q
          required: false
          schema:
            type: string
        - in: query
          name: includeIds
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of all users
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
    post:
      summary: Create new user
      description: |
        Creates a new user. Requires the `MANAGE_USERS` permission.
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: 'hey@itsme.com'
                username:
                  type: string
                permissions:
                  type: number
      responses:
        '201':
          description: The created user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      summary: Update batch of users
      description: |
        Update users with given IDs with provided values in request `body.settings`. You cannot update users' Plex tokens through this request.

        Requires the `MANAGE_USERS` permission.
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: integer
                permissions:
                  type: integer
      responses:
        '200':
          description: Successfully updated user details
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /user/import-from-plex:
    post:
      summary: Import all users from Plex
      description: |
        Fetches and imports users from the Plex server. If a list of Plex IDs is provided in the request body, only the specified users will be imported. Otherwise, all users will be imported.

        Requires the `MANAGE_USERS` permission.
      tags:
        - users
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                plexIds:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: A list of the newly created users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /user/import-from-jellyfin:
    post:
      summary: Import all users from Jellyfin
      description: |
        Fetches and imports users from the Jellyfin server.

        Requires the `MANAGE_USERS` permission.
      tags:
        - users
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                jellyfinUserIds:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: A list of the newly created users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /user/registerPushSubscription:
    post:
      summary: Register a web push /user/registerPushSubscription
      description: Registers a web push subscription for the logged-in user
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                endpoint:
                  type: string
                auth:
                  type: string
                p256dh:
                  type: string
                userAgent:
                  type: string
              required:
                - endpoint
                - auth
                - p256dh
      responses:
        '204':
          description: Successfully registered push subscription
  /user/{userId}/pushSubscriptions:
    get:
      summary: Get all web push notification settings for a user
      description: |
        Returns all web push notification settings for a user in a JSON object.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: User web push notification settings in JSON
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    type: string
                  p256dh:
                    type: string
                  auth:
                    type: string
                  userAgent:
                    type: string
  /user/{userId}/pushSubscription/{endpoint}:
    get:
      summary: Get web push notification settings for a user
      description: |
        Returns web push notification settings for a user in a JSON object.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
        - in: path
          name: endpoint
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User web push notification settings in JSON
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    type: string
                  p256dh:
                    type: string
                  auth:
                    type: string
                  userAgent:
                    type: string
    delete:
      summary: Delete user push subscription by key
      description: Deletes the user push subscription with the provided key.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
        - in: path
          name: endpoint
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Successfully removed user push subscription
  /user/{userId}:
    get:
      summary: Get user by ID
      description: |
        Retrieves user details in a JSON object. Requires the `MANAGE_USERS` permission.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Users details in JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      summary: Update a user by user ID
      description: |
        Update a user with the provided values. You cannot update a user's Plex token through this request.

        Requires the `MANAGE_USERS` permission.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Successfully updated user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    delete:
      summary: Delete user by ID
      description: Deletes the user with the provided userId. Requires the `MANAGE_USERS` permission.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: User successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /user/jellyfin/{jellyfinUserId}:
    get:
      summary: Get user by Jellyfin user ID
      description: |
        Retrieves user details by Jellyfin user ID in a JSON object. Returns filtered data based on the caller's permissions.
      tags:
        - users
      parameters:
        - in: path
          name: jellyfinUserId
          required: true
          schema:
            type: string
          description: The Jellyfin user ID (32-character hexadecimal string)
      responses:
        '200':
          description: User details in JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
  /user/{userId}/requests:
    get:
      summary: Get requests for a specific user
      description: |
        Retrieves a user's requests in a JSON object.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 20
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
      responses:
        '200':
          description: User's requests returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MediaRequest'
  /user/{userId}/quota:
    get:
      summary: Get quotas for a specific user
      description: |
        Returns quota details for a user in a JSON object. Requires `MANAGE_USERS` permission if viewing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: User quota details in JSON
          content:
            application/json:
              schema:
                type: object
                properties:
                  movie:
                    type: object
                    properties:
                      days:
                        type: number
                        example: 7
                      limit:
                        type: number
                        example: 10
                      used:
                        type: number
                        example: 6
                      remaining:
                        type: number
                        example: 4
                      restricted:
                        type: boolean
                        example: false
                  tv:
                    type: object
                    properties:
                      days:
                        type: number
                        example: 7
                      limit:
                        type: number
                        example: 10
                      used:
                        type: number
                        example: 6
                      remaining:
                        type: number
                        example: 4
                      restricted:
                        type: boolean
                        example: false
  /blocklist:
    get:
      summary: Returns blocklisted items
      description: Returns list of all blocklisted media
      tags:
        - blocklist
      parameters:
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 25
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
        - in: query
          name: search
          schema:
            type: string
            nullable: true
            example: dune
        - in: query
          name: filter
          schema:
            type: string
            enum: [all, manual, blocklistedTags]
            default: manual
      responses:
        '200':
          description: Blocklisted items returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        user:
                          $ref: '#/components/schemas/User'
                        createdAt:
                          type: string
                          example: 2024-04-21T01:55:44.000Z
                        id:
                          type: number
                          example: 1
                        mediaType:
                          type: string
                          example: movie
                        title:
                          type: string
                          example: Dune
                        tmdbId:
                          type: number
                          example: 438631
    post:
      summary: Add media to blocklist
      tags:
        - blocklist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Blocklist'
      responses:
        '201':
          description: Item succesfully blocklisted
        '412':
          description: Item has already been blocklisted
  /blocklist/{tmdbId}:
    get:
      summary: Get media from blocklist
      tags:
        - blocklist
      parameters:
        - in: path
          name: tmdbId
          description: tmdbId ID
          required: true
          example: '1'
          schema:
            type: string
        - in: query
          name: mediaType
          required: true
          schema:
            type: string
            enum:
              - movie
              - tv
      responses:
        '200':
          description: Blocklist details in JSON
    delete:
      summary: Remove media from blocklist
      tags:
        - blocklist
      parameters:
        - in: path
          name: tmdbId
          description: tmdbId ID
          required: true
          example: '1'
          schema:
            type: string
        - in: query
          name: mediaType
          required: true
          schema:
            type: string
            enum:
              - movie
              - tv
      responses:
        '204':
          description: Succesfully removed media item
  /blacklist:
    get:
      summary: Returns blocklisted items
      description: |
        **DEPRECATED**: Use `/blocklist` instead. This endpoint will be deprecated soon.
      deprecated: true
      tags:
        - blocklist
      parameters:
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 25
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
        - in: query
          name: search
          schema:
            type: string
            nullable: true
            example: dune
        - in: query
          name: filter
          schema:
            type: string
            enum: [all, manual, blocklistedTags]
            default: manual
      responses:
        '200':
          description: Blocklisted items returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        user:
                          $ref: '#/components/schemas/User'
                        createdAt:
                          type: string
                          example: 2024-04-21T01:55:44.000Z
                        id:
                          type: number
                          example: 1
                        mediaType:
                          type: string
                          example: movie
                        title:
                          type: string
                          example: Dune
                        tmdbId:
                          type: number
                          example: 438631
    post:
      summary: Add media to blocklist
      description: |
        **DEPRECATED**: Use `/blocklist` instead. This endpoint will be deprecated soon.
      deprecated: true
      tags:
        - blocklist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Blocklist'
      responses:
        '201':
          description: Item succesfully blocklisted
        '412':
          description: Item has already been blocklisted
  /blacklist/{tmdbId}:
    get:
      summary: Get media from blocklist
      description: |
        **DEPRECATED**: Use `/blocklist/{tmdbId}` instead. This endpoint will be deprecated soon.
      deprecated: true
      tags:
        - blocklist
      parameters:
        - in: path
          name: tmdbId
          description: tmdbId ID
          required: true
          example: '1'
          schema:
            type: string
        - in: query
          name: mediaType
          required: true
          schema:
            type: string
            enum:
              - movie
              - tv
      responses:
        '200':
          description: Blocklist details in JSON
    delete:
      summary: Remove media from blocklist
      description: |
        **DEPRECATED**: Use `/blocklist/{tmdbId}` instead. This endpoint will be deprecated soon.
      deprecated: true
      tags:
        - blocklist
      parameters:
        - in: path
          name: tmdbId
          description: tmdbId ID
          required: true
          example: '1'
          schema:
            type: string
        - in: query
          name: mediaType
          required: true
          schema:
            type: string
            enum:
              - movie
              - tv
      responses:
        '204':
          description: Succesfully removed media item
  /blocklist/collection/{collectionId}:
    post:
      summary: Add collection to blocklist
      description: Adds all movies in a collection to the blocklist
      tags:
        - blocklist
      parameters:
        - in: path
          name: collectionId
          description: Collection ID
          required: true
          example: '1424991'
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Successfully added collection to blocklist
        '500':
          description: Error adding collection to blocklist
    delete:
      summary: Remove collection from blocklist
      description: Removes all movies in a collection from the blocklist
      tags:
        - blocklist
      parameters:
        - in: path
          name: collectionId
          description: Collection ID
          required: true
          example: '1424991'
          schema:
            type: string
      responses:
        '204':
          description: Successfully removed collection from blocklist
        '500':
          description: Error removing collection from blocklist
  /watchlist:
    post:
      summary: Add media to watchlist
      tags:
        - watchlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Watchlist'
      responses:
        '200':
          description: Watchlist data returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
  /watchlist/{tmdbId}:
    delete:
      summary: Delete watchlist item
      description: Removes a watchlist item.
      tags:
        - watchlist
      parameters:
        - in: path
          name: tmdbId
          description: tmdbId ID
          required: true
          example: '1'
          schema:
            type: string
        - in: query
          name: mediaType
          required: true
          schema:
            type: string
            enum:
              - movie
              - tv
      responses:
        '204':
          description: Succesfully removed watchlist item
  /user/{userId}/watchlist:
    get:
      summary: Get the Plex watchlist for a specific user
      description: |
        Retrieves a user's Plex Watchlist in a JSON object.
      tags:
        - users
        - watchlist
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
      responses:
        '200':
          description: Watchlist data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                  totalPages:
                    type: number
                  totalResults:
                    type: number
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        tmdbId:
                          type: number
                          example: 1
                        ratingKey:
                          type: string
                        type:
                          type: string
                        title:
                          type: string
  /user/{userId}/settings/main:
    get:
      summary: Get general settings for a user
      description: Returns general settings for a specific user. Requires `MANAGE_USERS` permission if viewing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: User general settings returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSettings'
    post:
      summary: Update general settings for a user
      description: Updates and returns general settings for a specific user. Requires `MANAGE_USERS` permission if editing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSettings'
      responses:
        '200':
          description: Updated user general settings returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSettings'
  /user/{userId}/settings/discover:
    get:
      summary: Get Discover filter defaults for a user
      description: Returns persisted Discover browse filter defaults for a specific user. Requires `MANAGE_USERS` permission if viewing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Discover filter defaults returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverFilterDefaults'
        '401':
          description: Unauthorized
    post:
      summary: Update Discover filter defaults for a user
      description: Replaces Discover browse filter defaults for a specific user. Requires `MANAGE_USERS` permission if editing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoverFilterDefaults'
      responses:
        '200':
          description: Updated Discover filter defaults returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverFilterDefaults'
        '400':
          description: Invalid discover filter defaults
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /user/{userId}/settings/password:
    get:
      summary: Get password page informatiom
      description: Returns important data for the password page to function correctly. Requires `MANAGE_USERS` permission if viewing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: User password page information returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  hasPassword:
                    type: boolean
                    example: true
    post:
      summary: Update password for a user
      description: Updates a user's password. Requires `MANAGE_USERS` permission if editing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                currentPassword:
                  type: string
                  nullable: true
                newPassword:
                  type: string
              required:
                - newPassword
      responses:
        '204':
          description: User password updated
  /user/{userId}/settings/linked-accounts/plex:
    post:
      summary: Link the provided Plex account to the current user
      description: Logs in to Plex with the provided auth token, then links the associated Plex account with the user's account. Users can only link external accounts to their own account.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                authToken:
                  type: string
              required:
                - authToken
      responses:
        '204':
          description: Linking account succeeded
        '403':
          description: Invalid credentials
        '422':
          description: Account already linked to a user
    delete:
      summary: Remove the linked Plex account for a user
      description: Removes the linked Plex account for a specific user. Requires `MANAGE_USERS` permission if editing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '204':
          description: Unlinking account succeeded
        '400':
          description: Unlink request invalid
        '404':
          description: User does not exist
  /user/{userId}/settings/linked-accounts/jellyfin:
    post:
      summary: Link the provided Jellyfin account to the current user
      description: Logs in to Jellyfin with the provided credentials, then links the associated Jellyfin account with the user's account. Users can only link external accounts to their own account.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: 'Mr User'
                password:
                  type: string
                  example: 'supersecret'
      responses:
        '204':
          description: Linking account succeeded
        '403':
          description: Invalid credentials
        '422':
          description: Account already linked to a user
    delete:
      summary: Remove the linked Jellyfin account for a user
      description: Removes the linked Jellyfin account for a specific user. Requires `MANAGE_USERS` permission if editing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '204':
          description: Unlinking account succeeded
        '400':
          description: Unlink request invalid
        '404':
          description: User does not exist
  /user/{userId}/settings/linked-accounts/jellyfin/quickconnect:
    post:
      summary: Link Jellyfin/Emby account with Quick Connect
      description: Links a Jellyfin/Emby account to the user's profile using Quick Connect authentication
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secret:
                  type: string
              required:
                - secret
      responses:
        '400':
          description: Invalid Quick Connect secret
        '204':
          description: Account successfully linked
        '401':
          description: Unauthorized
        '422':
          description: Account already linked
        '500':
          description: Server error
  /user/{userId}/settings/linked-accounts/trakt:
    get:
      summary: Get Trakt link status for a user
      description: Returns whether the user has linked a Trakt account and the Trakt username if available. Users can only view their own status unless they have `MANAGE_USERS`.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
        - in: query
          name: includePluginStatus
          required: false
          schema:
            type: boolean
          description: When true, Better Trakt plugin readiness is included as `pluginState`.
      responses:
        '200':
          description: Trakt link status returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  provider:
                    type: string
                    enum: [direct, jellyfin]
                  connected:
                    type: boolean
                  needsJellyfinSessionRefresh:
                    type: boolean
                  pluginState:
                    type: string
                    enum:
                      - ready
                      - needs_session_refresh
                      - needs_trakt_link
                      - needs_access
                      - unavailable
                      - needs_jellyfin
                  username:
                    type: string
                    nullable: true
                  actionsEnabled:
                    type: boolean
                    description: When false, watched and rating actions are not sent to Trakt. Missing or true means enabled.
        '401':
          description: Unauthorized
    patch:
      summary: Update Trakt watch-sync preference for a user
      description: Enables or disables watched and rating fan-out to Trakt for this user without unlinking the account. Users can only update their own preference unless they have `MANAGE_USERS`.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - actionsEnabled
              properties:
                actionsEnabled:
                  type: boolean
      responses:
        '200':
          description: Trakt link status returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  provider:
                    type: string
                    enum: [direct, jellyfin]
                  connected:
                    type: boolean
                  username:
                    type: string
                    nullable: true
                  actionsEnabled:
                    type: boolean
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    delete:
      summary: Unlink Trakt account for a user
      description: Removes Trakt OAuth tokens for a specific user. Requires `MANAGE_USERS` permission if editing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '204':
          description: Trakt account unlinked
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /user/{userId}/settings/linked-accounts/trakt/device/code:
    post:
      summary: Start Trakt device authorization
      description: Requests a Trakt device code for linking the caller's Trakt account. Users can only link their own account. Requires Trakt to be configured by an administrator.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Device code issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  device_code:
                    type: string
                  user_code:
                    type: string
                  verification_url:
                    type: string
                  expires_in:
                    type: number
                  interval:
                    type: number
        '400':
          description: Trakt is not configured
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /user/{userId}/settings/linked-accounts/trakt/device/token:
    post:
      summary: Poll Trakt device authorization
      description: Polls Trakt for completion of device authorization and stores tokens on success. Users can only link their own account.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - deviceCode
              properties:
                deviceCode:
                  type: string
      responses:
        '200':
          description: Trakt account linked
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: authorized
                  username:
                    type: string
        '202':
          description: Authorization still pending
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: pending
                  retryAfterSeconds:
                    type: number
                    example: 10
        '400':
          description: Invalid request or Trakt not configured
        '401':
          description: Unauthorized
        '409':
          description: Authorization denied or device code already used
        '410':
          description: Device code expired
        '500':
          description: Server error
  /user/{userId}/settings/linked-accounts/anilist:
    get:
      summary: Get AniList link status for a user
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: AniList link status returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  connected:
                    type: boolean
                  expired:
                    type: boolean
                  username:
                    type: string
                    nullable: true
                  authorizeUrl:
                    type: string
                    nullable: true
                  actionsEnabled:
                    type: boolean
                    description: When false, watched and rating actions are not sent to AniList. Missing or true means enabled.
        '401':
          description: Unauthorized
    patch:
      summary: Update AniList watch-sync preference for a user
      description: Enables or disables watched and rating fan-out to AniList for this user without unlinking the account. Users can only update their own preference unless they have `MANAGE_USERS`.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - actionsEnabled
              properties:
                actionsEnabled:
                  type: boolean
      responses:
        '200':
          description: AniList link status returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  connected:
                    type: boolean
                  expired:
                    type: boolean
                  username:
                    type: string
                    nullable: true
                  authorizeUrl:
                    type: string
                    nullable: true
                  actionsEnabled:
                    type: boolean
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      summary: Link AniList with a PIN authorization code
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - code
              properties:
                code:
                  type: string
      responses:
        '200':
          description: AniList account linked
        '400':
          description: Invalid request or AniList not configured
        '401':
          description: Unauthorized
        '409':
          description: AniList account already linked
        '500':
          description: Server error
    delete:
      summary: Unlink AniList account for a user
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '204':
          description: AniList account unlinked
        '401':
          description: Unauthorized
  /user/{userId}/settings/notifications:
    get:
      summary: Get notification settings for a user
      description: Returns notification settings for a specific user. Requires `MANAGE_USERS` permission if viewing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: User notification settings returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSettingsNotifications'
    post:
      summary: Update notification settings for a user
      description: Updates and returns notification settings for a specific user. Requires `MANAGE_USERS` permission if editing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSettingsNotifications'
      responses:
        '200':
          description: Updated user notification settings returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSettingsNotifications'
  /user/{userId}/settings/permissions:
    get:
      summary: Get permission settings for a user
      description: Returns permission settings for a specific user. Requires `MANAGE_USERS` permission if viewing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: User permission settings returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  permissions:
                    type: number
                    example: 2
    post:
      summary: Update permission settings for a user
      description: Updates and returns permission settings for a specific user. Requires `MANAGE_USERS` permission if editing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                permissions:
                  type: number
              required:
                - permissions
      responses:
        '200':
          description: Updated user general settings returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  permissions:
                    type: number
                    example: 2
  /user/{userId}/watch_data:
    get:
      summary: Get watch data
      description: |
        Returns play count, play duration, and recently watched media.

        Requires the `ADMIN` permission to fetch results for other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Users
          content:
            application/json:
              schema:
                type: object
                properties:
                  recentlyWatched:
                    type: array
                    items:
                      $ref: '#/components/schemas/MediaInfo'
                  playCount:
                    type: number
  /search:
    get:
      summary: Search for movies, TV shows, or people
      description: Returns a list of movies, TV shows, or people a JSON object.
      tags:
        - search
      parameters:
        - in: query
          name: query
          required: true
          schema:
            type: string
            example: 'Mulan'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      anyOf:
                        - $ref: '#/components/schemas/MovieResult'
                        - $ref: '#/components/schemas/TvResult'
                        - $ref: '#/components/schemas/PersonResult'
  /search/keyword:
    get:
      summary: Search for keywords
      description: Returns a list of TMDB keywords matching the search query
      tags:
        - search
      parameters:
        - in: query
          name: query
          required: true
          schema:
            type: string
            example: 'christmas'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Keyword'
  /search/company:
    get:
      summary: Search for companies
      description: Returns a list of TMDB companies matching the search query. (Will not return origin country)
      tags:
        - search
      parameters:
        - in: query
          name: query
          required: true
          schema:
            type: string
            example: 'Disney'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Company'
  /discover/movies:
    get:
      summary: Discover movies
      description: Returns a list of movies in a JSON object.
      tags:
        - search
      parameters:
        - $ref: '#/components/parameters/DiscoverIgnoreWatched'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreCollected'
        - $ref: '#/components/parameters/DiscoverIgnoreWatchlisted'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
        - in: query
          name: genre
          schema:
            type: string
            example: 18
        - in: query
          name: studio
          schema:
            type: number
            example: 1
        - in: query
          name: keywords
          schema:
            type: string
            example: 1,2
        - in: query
          name: excludeKeywords
          schema:
            type: string
            example: 3,4
          description: Comma-separated list of keyword IDs to exclude from results
        - in: query
          name: sortBy
          schema:
            type: string
            example: popularity.desc
        - in: query
          name: primaryReleaseDateGte
          schema:
            type: string
            example: 2022-01-01
        - in: query
          name: primaryReleaseDateLte
          schema:
            type: string
            example: 2023-01-01
        - in: query
          name: withRuntimeGte
          schema:
            type: number
            example: 60
        - in: query
          name: withRuntimeLte
          schema:
            type: number
            example: 120
        - in: query
          name: voteAverageGte
          schema:
            type: number
            example: 7
        - in: query
          name: voteAverageLte
          schema:
            type: number
            example: 10
        - in: query
          name: voteCountGte
          schema:
            type: number
            example: 7
        - in: query
          name: voteCountLte
          schema:
            type: number
            example: 10
        - $ref: '#/components/parameters/DiscoverImdbRatingGte'
        - $ref: '#/components/parameters/DiscoverImdbRatingLte'
        - $ref: '#/components/parameters/DiscoverImdbVotesGte'
        - $ref: '#/components/parameters/DiscoverImdbVotesLte'
        - $ref: '#/components/parameters/DiscoverRtCriticsGte'
        - $ref: '#/components/parameters/DiscoverRtCriticsLte'
        - $ref: '#/components/parameters/DiscoverRtAudienceGte'
        - $ref: '#/components/parameters/DiscoverRtAudienceLte'
        - $ref: '#/components/parameters/DiscoverMetacriticGte'
        - $ref: '#/components/parameters/DiscoverMetacriticLte'
        - $ref: '#/components/parameters/DiscoverTraktRatingGte'
        - $ref: '#/components/parameters/DiscoverTraktRatingLte'
        - $ref: '#/components/parameters/DiscoverIncludeNoRating'
        - in: query
          name: watchRegion
          schema:
            type: string
            example: US
        - in: query
          name: watchProviders
          schema:
            type: string
            example: 8|9
        - in: query
          name: certification
          schema:
            type: string
            example: PG-13
          description: Exact certification to filter by (used when certificationMode is 'exact')
        - in: query
          name: certificationGte
          schema:
            type: string
            example: G
          description: Minimum certification to filter by (used when certificationMode is 'range')
        - in: query
          name: certificationLte
          schema:
            type: string
            example: PG-13
          description: Maximum certification to filter by (used when certificationMode is 'range')
        - in: query
          name: certificationCountry
          schema:
            type: string
            example: US
          description: Country code for the certification system (e.g., US, GB, CA)
        - in: query
          name: certificationMode
          schema:
            type: string
            enum: [exact, range]
            example: exact
          description: Determines whether to use exact certification matching or a certification range (internal use only, not sent to TMDB API)
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /discover/movies/genre/{genreId}:
    get:
      summary: Discover movies by genre
      description: Returns a list of movies based on the provided genre ID in a JSON object.
      tags:
        - search
      parameters:
        - in: path
          name: genreId
          required: true
          schema:
            type: string
            example: '1'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  genre:
                    $ref: '#/components/schemas/Genre'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /discover/movies/language/{language}:
    get:
      summary: Discover movies by original language
      description: Returns a list of movies based on the provided ISO 639-1 language code in a JSON object.
      tags:
        - search
      parameters:
        - in: path
          name: language
          required: true
          schema:
            type: string
            example: en
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  language:
                    $ref: '#/components/schemas/SpokenLanguage'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /discover/movies/studio/{studioId}:
    get:
      summary: Discover movies by studio
      description: Returns a list of movies based on the provided studio ID in a JSON object.
      tags:
        - search
      parameters:
        - in: path
          name: studioId
          required: true
          schema:
            type: string
            example: '1'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  studio:
                    $ref: '#/components/schemas/ProductionCompany'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /discover/movies/upcoming:
    get:
      summary: Upcoming movies
      description: Returns a list of movies in a JSON object.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /discover/tv:
    get:
      summary: Discover TV shows
      description: Returns a list of TV shows in a JSON object.
      tags:
        - search
      parameters:
        - $ref: '#/components/parameters/DiscoverIgnoreWatched'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreCollected'
        - $ref: '#/components/parameters/DiscoverIgnoreWatchlisted'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
        - in: query
          name: genre
          schema:
            type: string
            example: 18
        - in: query
          name: network
          schema:
            type: number
            example: 1
        - in: query
          name: keywords
          schema:
            type: string
            example: 1,2
        - in: query
          name: excludeKeywords
          schema:
            type: string
            example: 3,4
          description: Comma-separated list of keyword IDs to exclude from results
        - in: query
          name: sortBy
          schema:
            type: string
            example: popularity.desc
        - in: query
          name: firstAirDateGte
          schema:
            type: string
            example: 2022-01-01
        - in: query
          name: firstAirDateLte
          schema:
            type: string
            example: 2023-01-01
        - in: query
          name: withRuntimeGte
          schema:
            type: number
            example: 60
        - in: query
          name: withRuntimeLte
          schema:
            type: number
            example: 120
        - in: query
          name: voteAverageGte
          schema:
            type: number
            example: 7
        - in: query
          name: voteAverageLte
          schema:
            type: number
            example: 10
        - in: query
          name: voteCountGte
          schema:
            type: number
            example: 7
        - in: query
          name: voteCountLte
          schema:
            type: number
            example: 10
        - $ref: '#/components/parameters/DiscoverImdbRatingGte'
        - $ref: '#/components/parameters/DiscoverImdbRatingLte'
        - $ref: '#/components/parameters/DiscoverImdbVotesGte'
        - $ref: '#/components/parameters/DiscoverImdbVotesLte'
        - $ref: '#/components/parameters/DiscoverRtCriticsGte'
        - $ref: '#/components/parameters/DiscoverRtCriticsLte'
        - $ref: '#/components/parameters/DiscoverRtAudienceGte'
        - $ref: '#/components/parameters/DiscoverRtAudienceLte'
        - $ref: '#/components/parameters/DiscoverMetacriticGte'
        - $ref: '#/components/parameters/DiscoverMetacriticLte'
        - $ref: '#/components/parameters/DiscoverTraktRatingGte'
        - $ref: '#/components/parameters/DiscoverTraktRatingLte'
        - $ref: '#/components/parameters/DiscoverIncludeNoRating'
        - in: query
          name: watchRegion
          schema:
            type: string
            example: US
        - in: query
          name: watchProviders
          schema:
            type: string
            example: 8|9
        - in: query
          name: status
          schema:
            type: string
            example: 3|4
        - in: query
          name: certification
          schema:
            type: string
            example: TV-14
          description: Exact certification to filter by (used when certificationMode is 'exact')
        - in: query
          name: certificationGte
          schema:
            type: string
            example: TV-PG
          description: Minimum certification to filter by (used when certificationMode is 'range')
        - in: query
          name: certificationLte
          schema:
            type: string
            example: TV-MA
          description: Maximum certification to filter by (used when certificationMode is 'range')
        - in: query
          name: certificationCountry
          schema:
            type: string
            example: US
          description: Country code for the certification system (e.g., US, GB, CA)
        - in: query
          name: certificationMode
          schema:
            type: string
            enum: [exact, range]
            example: exact
          description: Determines whether to use exact certification matching or a certification range (internal use only, not sent to TMDB API)
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TvResult'
  /discover/tv/language/{language}:
    get:
      summary: Discover TV shows by original language
      description: Returns a list of TV shows based on the provided ISO 639-1 language code in a JSON object.
      tags:
        - search
      parameters:
        - in: path
          name: language
          required: true
          schema:
            type: string
            example: en
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  language:
                    $ref: '#/components/schemas/SpokenLanguage'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TvResult'
  /discover/tv/genre/{genreId}:
    get:
      summary: Discover TV shows by genre
      description: Returns a list of TV shows based on the provided genre ID in a JSON object.
      tags:
        - search
      parameters:
        - in: path
          name: genreId
          required: true
          schema:
            type: string
            example: '1'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  genre:
                    $ref: '#/components/schemas/Genre'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TvResult'
  /discover/tv/network/{networkId}:
    get:
      summary: Discover TV shows by network
      description: Returns a list of TV shows based on the provided network ID in a JSON object.
      tags:
        - search
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: string
            example: '1'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  network:
                    $ref: '#/components/schemas/Network'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TvResult'
  /discover/tv/upcoming:
    get:
      summary: Discover Upcoming TV shows
      description: Returns a list of upcoming TV shows in a JSON object.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TvResult'
  /discover/trending:
    get:
      summary: Trending movies and TV
      description: Returns a list of movies and TV shows in a JSON object.
      tags:
        - search
      parameters:
        - $ref: '#/components/parameters/DiscoverIgnoreWatched'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreCollected'
        - $ref: '#/components/parameters/DiscoverIgnoreWatchlisted'
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
        - in: query
          name: mediaType
          schema:
            type: string
            enum:
              - all
              - movie
              - tv
            default: all
        - in: query
          name: timeWindow
          schema:
            type: string
            enum:
              - day
              - week
            default: day
        - $ref: '#/components/parameters/DiscoverGenre'
        - $ref: '#/components/parameters/DiscoverLanguage'
        - $ref: '#/components/parameters/DiscoverPrimaryReleaseDateGte'
        - $ref: '#/components/parameters/DiscoverPrimaryReleaseDateLte'
        - $ref: '#/components/parameters/DiscoverFirstAirDateGte'
        - $ref: '#/components/parameters/DiscoverFirstAirDateLte'
        - $ref: '#/components/parameters/DiscoverVoteAverageGte'
        - $ref: '#/components/parameters/DiscoverVoteAverageLte'
        - $ref: '#/components/parameters/DiscoverVoteCountGte'
        - $ref: '#/components/parameters/DiscoverVoteCountLte'
        - $ref: '#/components/parameters/DiscoverRuntimeGte'
        - $ref: '#/components/parameters/DiscoverRuntimeLte'
        - $ref: '#/components/parameters/DiscoverSeriesStatus'
        - $ref: '#/components/parameters/DiscoverImdbRatingGte'
        - $ref: '#/components/parameters/DiscoverImdbRatingLte'
        - $ref: '#/components/parameters/DiscoverImdbVotesGte'
        - $ref: '#/components/parameters/DiscoverImdbVotesLte'
        - $ref: '#/components/parameters/DiscoverRtCriticsGte'
        - $ref: '#/components/parameters/DiscoverRtCriticsLte'
        - $ref: '#/components/parameters/DiscoverRtAudienceGte'
        - $ref: '#/components/parameters/DiscoverRtAudienceLte'
        - $ref: '#/components/parameters/DiscoverMetacriticGte'
        - $ref: '#/components/parameters/DiscoverMetacriticLte'
        - $ref: '#/components/parameters/DiscoverTraktRatingGte'
        - $ref: '#/components/parameters/DiscoverTraktRatingLte'
        - $ref: '#/components/parameters/DiscoverIncludeNoRating'
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      anyOf:
                        - $ref: '#/components/schemas/MovieResult'
                        - $ref: '#/components/schemas/TvResult'
                        - $ref: '#/components/schemas/PersonResult'
  /discover/keyword/{keywordId}/movies:
    get:
      summary: Get movies from keyword
      description: Returns list of movies based on the provided keyword ID a JSON object.
      tags:
        - search
      parameters:
        - in: path
          name: keywordId
          required: true
          schema:
            type: number
            example: 207317
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: List of movies
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /discover/genreslider/movie:
    get:
      summary: Get genre slider data for movies
      description: Returns a list of genres with backdrops attached
      tags:
        - search
      parameters:
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Genre slider data returned
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      example: 1
                    backdrops:
                      type: array
                      items:
                        type: string
                    name:
                      type: string
                      example: Genre Name
  /discover/genreslider/tv:
    get:
      summary: Get genre slider data for TV series
      description: Returns a list of genres with backdrops attached
      tags:
        - search
      parameters:
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Genre slider data returned
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      example: 1
                    backdrops:
                      type: array
                      items:
                        type: string
                    name:
                      type: string
                      example: Genre Name
  /discover/trakt/recommendations:
    get:
      summary: Get personalized Trakt recommendations for the current user.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: type
          schema:
            type: string
            enum: [movie, tv, all, anime]
            default: all
        - in: query
          name: ignoreCollected
          schema:
            type: boolean
            default: false
        - in: query
          name: ignoreWatchlisted
          schema:
            type: boolean
            default: false
        - $ref: '#/components/parameters/DiscoverGenre'
        - $ref: '#/components/parameters/DiscoverLanguage'
        - $ref: '#/components/parameters/DiscoverPrimaryReleaseDateGte'
        - $ref: '#/components/parameters/DiscoverPrimaryReleaseDateLte'
        - $ref: '#/components/parameters/DiscoverFirstAirDateGte'
        - $ref: '#/components/parameters/DiscoverFirstAirDateLte'
        - $ref: '#/components/parameters/DiscoverVoteAverageGte'
        - $ref: '#/components/parameters/DiscoverVoteAverageLte'
        - $ref: '#/components/parameters/DiscoverVoteCountGte'
        - $ref: '#/components/parameters/DiscoverVoteCountLte'
        - $ref: '#/components/parameters/DiscoverImdbRatingGte'
        - $ref: '#/components/parameters/DiscoverImdbRatingLte'
        - $ref: '#/components/parameters/DiscoverImdbVotesGte'
        - $ref: '#/components/parameters/DiscoverImdbVotesLte'
        - $ref: '#/components/parameters/DiscoverRtCriticsGte'
        - $ref: '#/components/parameters/DiscoverRtCriticsLte'
        - $ref: '#/components/parameters/DiscoverRtAudienceGte'
        - $ref: '#/components/parameters/DiscoverRtAudienceLte'
        - $ref: '#/components/parameters/DiscoverMetacriticGte'
        - $ref: '#/components/parameters/DiscoverMetacriticLte'
        - $ref: '#/components/parameters/DiscoverTraktRatingGte'
        - $ref: '#/components/parameters/DiscoverTraktRatingLte'
        - $ref: '#/components/parameters/DiscoverIncludeNoRating'
        - $ref: '#/components/parameters/DiscoverIgnoreWatched'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
      responses:
        '200':
          description: Trakt recommendations returned
        '404':
          description: Trakt account not linked
  /discover/trakt/watchlist:
    get:
      summary: Get the authenticated user's Trakt watchlist.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: type
          schema:
            type: string
            enum: [movie, tv, all, anime]
            default: all
        - $ref: '#/components/parameters/DiscoverGenre'
        - $ref: '#/components/parameters/DiscoverLanguage'
        - $ref: '#/components/parameters/DiscoverPrimaryReleaseDateGte'
        - $ref: '#/components/parameters/DiscoverPrimaryReleaseDateLte'
        - $ref: '#/components/parameters/DiscoverFirstAirDateGte'
        - $ref: '#/components/parameters/DiscoverFirstAirDateLte'
        - $ref: '#/components/parameters/DiscoverVoteAverageGte'
        - $ref: '#/components/parameters/DiscoverVoteAverageLte'
        - $ref: '#/components/parameters/DiscoverVoteCountGte'
        - $ref: '#/components/parameters/DiscoverVoteCountLte'
        - $ref: '#/components/parameters/DiscoverImdbRatingGte'
        - $ref: '#/components/parameters/DiscoverImdbRatingLte'
        - $ref: '#/components/parameters/DiscoverImdbVotesGte'
        - $ref: '#/components/parameters/DiscoverImdbVotesLte'
        - $ref: '#/components/parameters/DiscoverRtCriticsGte'
        - $ref: '#/components/parameters/DiscoverRtCriticsLte'
        - $ref: '#/components/parameters/DiscoverRtAudienceGte'
        - $ref: '#/components/parameters/DiscoverRtAudienceLte'
        - $ref: '#/components/parameters/DiscoverMetacriticGte'
        - $ref: '#/components/parameters/DiscoverMetacriticLte'
        - $ref: '#/components/parameters/DiscoverTraktRatingGte'
        - $ref: '#/components/parameters/DiscoverTraktRatingLte'
        - $ref: '#/components/parameters/DiscoverIncludeNoRating'
        - $ref: '#/components/parameters/DiscoverIgnoreWatched'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
      responses:
        '200':
          description: Trakt watchlist returned. Exact totals are omitted; use hasMore for continuation.
          content:
            application/json:
              schema:
                type: object
                required: [page, hasMore, results]
                properties:
                  page:
                    type: number
                  hasMore:
                    type: boolean
                    description: Whether another page may exist after mixed-media merge/filters.
                  results:
                    type: array
                    items:
                      type: object
        '404':
          description: Trakt account not linked
  /discover/trakt/history:
    get:
      summary: Get the authenticated user's Trakt watch history.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: type
          schema:
            type: string
            enum: [movie, tv, all, anime]
            default: all
        - $ref: '#/components/parameters/DiscoverGenre'
        - $ref: '#/components/parameters/DiscoverLanguage'
        - $ref: '#/components/parameters/DiscoverPrimaryReleaseDateGte'
        - $ref: '#/components/parameters/DiscoverPrimaryReleaseDateLte'
        - $ref: '#/components/parameters/DiscoverFirstAirDateGte'
        - $ref: '#/components/parameters/DiscoverFirstAirDateLte'
        - $ref: '#/components/parameters/DiscoverVoteAverageGte'
        - $ref: '#/components/parameters/DiscoverVoteAverageLte'
        - $ref: '#/components/parameters/DiscoverVoteCountGte'
        - $ref: '#/components/parameters/DiscoverVoteCountLte'
        - $ref: '#/components/parameters/DiscoverImdbRatingGte'
        - $ref: '#/components/parameters/DiscoverImdbRatingLte'
        - $ref: '#/components/parameters/DiscoverImdbVotesGte'
        - $ref: '#/components/parameters/DiscoverImdbVotesLte'
        - $ref: '#/components/parameters/DiscoverRtCriticsGte'
        - $ref: '#/components/parameters/DiscoverRtCriticsLte'
        - $ref: '#/components/parameters/DiscoverRtAudienceGte'
        - $ref: '#/components/parameters/DiscoverRtAudienceLte'
        - $ref: '#/components/parameters/DiscoverMetacriticGte'
        - $ref: '#/components/parameters/DiscoverMetacriticLte'
        - $ref: '#/components/parameters/DiscoverTraktRatingGte'
        - $ref: '#/components/parameters/DiscoverTraktRatingLte'
        - $ref: '#/components/parameters/DiscoverIncludeNoRating'
        - $ref: '#/components/parameters/DiscoverIgnoreWatched'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
      responses:
        '200':
          description: Trakt history returned. Exact totals are omitted; use hasMore for continuation.
          content:
            application/json:
              schema:
                type: object
                required: [page, hasMore, results]
                properties:
                  page:
                    type: number
                  hasMore:
                    type: boolean
                    description: Whether another page may exist after mixed-media merge/filters.
                  results:
                    type: array
                    items:
                      type: object
        '404':
          description: Trakt account not linked
  /discover/trakt/lists:
    get:
      summary: List the authenticated user's Trakt lists.
      tags:
        - search
      responses:
        '200':
          description: Trakt lists returned
        '404':
          description: Trakt account not linked
  /discover/trakt/lists/search:
    get:
      summary: Search public Trakt lists
      tags:
        - search
      parameters:
        - in: query
          name: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Matching public Trakt lists
        '400':
          description: Trakt is not configured
  /discover/trakt/list:
    get:
      summary: Browse a Trakt list by public URL or shorthand reference.
      tags:
        - search
      parameters:
        - in: query
          name: url
          required: true
          schema:
            type: string
            example: https://trakt.tv/users/justin/lists/watched
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: type
          schema:
            type: string
            enum: [movie, tv, all, anime]
            default: all
        - in: query
          name: sort
          description: Sort a Trakt list by date added or release date, newest first.
          schema:
            type: string
            enum: [added, released]
        - $ref: '#/components/parameters/DiscoverGenre'
        - $ref: '#/components/parameters/DiscoverLanguage'
        - $ref: '#/components/parameters/DiscoverPrimaryReleaseDateGte'
        - $ref: '#/components/parameters/DiscoverPrimaryReleaseDateLte'
        - $ref: '#/components/parameters/DiscoverFirstAirDateGte'
        - $ref: '#/components/parameters/DiscoverFirstAirDateLte'
        - $ref: '#/components/parameters/DiscoverVoteAverageGte'
        - $ref: '#/components/parameters/DiscoverVoteAverageLte'
        - $ref: '#/components/parameters/DiscoverVoteCountGte'
        - $ref: '#/components/parameters/DiscoverVoteCountLte'
        - $ref: '#/components/parameters/DiscoverRuntimeGte'
        - $ref: '#/components/parameters/DiscoverRuntimeLte'
        - $ref: '#/components/parameters/DiscoverSeriesStatus'
        - $ref: '#/components/parameters/DiscoverImdbRatingGte'
        - $ref: '#/components/parameters/DiscoverImdbRatingLte'
        - $ref: '#/components/parameters/DiscoverImdbVotesGte'
        - $ref: '#/components/parameters/DiscoverImdbVotesLte'
        - $ref: '#/components/parameters/DiscoverRtCriticsGte'
        - $ref: '#/components/parameters/DiscoverRtCriticsLte'
        - $ref: '#/components/parameters/DiscoverRtAudienceGte'
        - $ref: '#/components/parameters/DiscoverRtAudienceLte'
        - $ref: '#/components/parameters/DiscoverMetacriticGte'
        - $ref: '#/components/parameters/DiscoverMetacriticLte'
        - $ref: '#/components/parameters/DiscoverTraktRatingGte'
        - $ref: '#/components/parameters/DiscoverTraktRatingLte'
        - $ref: '#/components/parameters/DiscoverIncludeNoRating'
        - $ref: '#/components/parameters/DiscoverIgnoreWatched'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
      responses:
        '200':
          description: Trakt list items returned
  /discover/anilist/trending:
    get:
      summary: Get AniList trending anime mapped to TMDB.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: AniList trending anime returned
  /discover/anilist/season:
    get:
      summary: Get AniList current-season anime mapped to TMDB.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: AniList seasonal anime returned
  /discover/anilist/popular:
    get:
      summary: Get AniList all-time popular anime mapped to TMDB.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: AniList popular anime returned
  /discover/anilist/top:
    get:
      summary: Get AniList top-rated anime mapped to TMDB.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: AniList top-rated anime returned
  /discover/anilist/next-season:
    get:
      summary: Get AniList next-season anime mapped to TMDB.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: AniList next-season anime returned
  /discover/anilist/watching:
    get:
      summary: Get the authenticated user's AniList currently watching list.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: AniList watching list returned
        '404':
          description: AniList account not linked
  /discover/anilist/planning:
    get:
      summary: Get the authenticated user's AniList planning list.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: AniList planning list returned
        '404':
          description: AniList account not linked
  /discover/anilist/completed:
    get:
      summary: Get the authenticated user's AniList completed list.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: AniList completed list returned
        '404':
          description: AniList account not linked
  /discover/anilist/lists:
    get:
      summary: List the authenticated user's AniList anime lists.
      tags:
        - search
      responses:
        '200':
          description: AniList lists returned
  /discover/anilist/list:
    get:
      summary: Get an AniList anime list by name.
      tags:
        - search
      parameters:
        - in: query
          name: name
          required: true
          schema:
            type: string
        - in: query
          name: page
          schema:
            type: number
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: AniList list items returned
  /discover/mdblist/lists/search:
    get:
      summary: Search public MDBList lists
      tags:
        - search
      parameters:
        - in: query
          name: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Matching public MDBList lists
        '400':
          description: MDBList is not configured
  /discover/mdblist/list:
    get:
      summary: Browse an MDBList public list by URL, username/slug, or list id.
      tags:
        - search
      parameters:
        - in: query
          name: url
          required: true
          schema:
            type: string
            example: https://mdblist.com/lists/linaspurinis/top-watched-movies-of-the-week
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: MDBList list items returned
        '400':
          description: MDBList is not configured or the list reference is invalid
        '404':
          description: MDBList list not found
  /discover/watchlist:
    get:
      summary: Get the Plex watchlist.
      tags:
        - search
      parameters:
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - $ref: '#/components/parameters/DiscoverHideUnmapped'
        - $ref: '#/components/parameters/DiscoverIgnoreDefaults'
      responses:
        '200':
          description: Watchlist data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                  totalPages:
                    type: number
                  totalResults:
                    type: number
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        tmdbId:
                          type: number
                          example: 1
                        ratingKey:
                          type: string
                        type:
                          type: string
                        title:
                          type: string
                        source:
                          type: string
                          enum: [trakt, anilist, simkl, mdblist, plex]
                        sourceUrl:
                          type: string
                        sourceId:
                          type: string
                        image:
                          type: string
                        mappingState:
                          $ref: '#/components/schemas/DiscoverMappingInfo'
  /request:
    get:
      summary: Get all requests
      description: |
        Returns all requests if the user has the `ADMIN` or `MANAGE_REQUESTS` permissions. Otherwise, only the logged-in user's requests are returned.

        If the `requestedBy` parameter is specified, only requests from that particular user ID will be returned.
      tags:
        - request
      parameters:
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 20
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
        - in: query
          name: filter
          schema:
            type: string
            nullable: true
            enum:
              [
                all,
                approved,
                available,
                pending,
                processing,
                unavailable,
                failed,
                deleted,
                completed,
              ]
        - in: query
          name: sort
          schema:
            type: string
            enum: [added, modified]
            default: added
        - in: query
          name: sortDirection
          schema:
            type: string
            enum: [asc, desc]
            nullable: true
            default: desc
        - in: query
          name: requestedBy
          schema:
            type: number
            nullable: true
            example: 1
        - in: query
          name: mediaType
          schema:
            type: string
            enum: [movie, tv, all]
            nullable: true
            default: all
      responses:
        '200':
          description: Requests returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MediaRequest'
    post:
      summary: Create new request
      description: |
        Creates a new request with the provided media ID and type. The `REQUEST` permission is required.

        If the user has the `ADMIN` or `AUTO_APPROVE` permissions, their request will be auomatically approved.
      tags:
        - request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mediaType:
                  type: string
                  enum: [movie, tv]
                  example: movie
                mediaId:
                  type: number
                  example: 123
                tvdbId:
                  type: number
                  example: 123
                seasons:
                  oneOf:
                    - type: array
                      items:
                        type: number
                        minimum: 0
                    - type: string
                      enum: [all]
                episodeSelection:
                  oneOf:
                    - type: object
                      additionalProperties: false
                      required: [type, episodeTvdbId]
                      properties:
                        type:
                          type: string
                          enum: [single]
                        episodeTvdbId:
                          type: integer
                          minimum: 1
                    - type: object
                      additionalProperties: false
                      required: [type, startEpisodeTvdbId, endEpisodeTvdbId]
                      properties:
                        type:
                          type: string
                          enum: [range]
                        startEpisodeTvdbId:
                          type: integer
                          minimum: 1
                        endEpisodeTvdbId:
                          type: integer
                          minimum: 1
                    - type: object
                      additionalProperties: false
                      required: [type, startEpisodeTvdbId]
                      properties:
                        type:
                          type: string
                          enum: [after]
                        startEpisodeTvdbId:
                          type: integer
                          minimum: 1
                    - type: object
                      additionalProperties: false
                      required: [type, count]
                      properties:
                        type:
                          type: string
                          enum: [watchAhead]
                        count:
                          type: integer
                          minimum: 1
                          maximum: 50
                is4k:
                  type: boolean
                  example: false
                serverId:
                  type: number
                profileId:
                  type: number
                rootFolder:
                  type: string
                languageProfileId:
                  type: number
                userId:
                  type: number
                  nullable: true
                ignoreQuota:
                  type: boolean
                  example: false
                  description: If true, this request will not count against the user's quota. Requires MANAGE_REQUESTS permission.
              required:
                - mediaType
                - mediaId
      responses:
        '201':
          description: Succesfully created the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaRequest'
  /request/count:
    get:
      summary: Gets request counts
      description: |
        Returns the number of requests by status including pending, approved, available, and completed requests.
      tags:
        - request
      responses:
        '200':
          description: Request counts returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: number
                  movie:
                    type: number
                  tv:
                    type: number
                  pending:
                    type: number
                  approved:
                    type: number
                  declined:
                    type: number
                  processing:
                    type: number
                  available:
                    type: number
                  completed:
                    type: number
  /request/{requestId}:
    get:
      summary: Get MediaRequest
      description: Returns a specific MediaRequest in a JSON object.
      tags:
        - request
      parameters:
        - in: path
          name: requestId
          description: Request ID
          required: true
          example: '1'
          schema:
            type: string
      responses:
        '200':
          description: Succesfully returns request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaRequest'
    put:
      summary: Update MediaRequest
      description: Updates a specific media request and returns the request in a JSON object. Requires the `MANAGE_REQUESTS` permission.
      tags:
        - request
      parameters:
        - in: path
          name: requestId
          description: Request ID
          required: true
          example: '1'
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mediaType:
                  type: string
                  enum: [movie, tv]
                seasons:
                  type: array
                  items:
                    type: number
                    minimum: 0
                episodeSelection:
                  oneOf:
                    - type: object
                      additionalProperties: false
                      required: [type, episodeTvdbId]
                      properties:
                        type:
                          type: string
                          enum: [single]
                        episodeTvdbId:
                          type: integer
                          minimum: 1
                    - type: object
                      additionalProperties: false
                      required: [type, startEpisodeTvdbId, endEpisodeTvdbId]
                      properties:
                        type:
                          type: string
                          enum: [range]
                        startEpisodeTvdbId:
                          type: integer
                          minimum: 1
                        endEpisodeTvdbId:
                          type: integer
                          minimum: 1
                    - type: object
                      additionalProperties: false
                      required: [type, startEpisodeTvdbId]
                      properties:
                        type:
                          type: string
                          enum: [after]
                        startEpisodeTvdbId:
                          type: integer
                          minimum: 1
                    - type: object
                      additionalProperties: false
                      required: [type, count]
                      properties:
                        type:
                          type: string
                          enum: [watchAhead]
                        count:
                          type: integer
                          minimum: 1
                          maximum: 50
                is4k:
                  type: boolean
                  example: false
                serverId:
                  type: number
                profileId:
                  type: number
                rootFolder:
                  type: string
                languageProfileId:
                  type: number
                userId:
                  type: number
                  nullable: true
              required:
                - mediaType
      responses:
        '200':
          description: Succesfully updated request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaRequest'
    delete:
      summary: Delete request
      description: Removes a request. If the user has the `MANAGE_REQUESTS` permission, any request can be removed. Otherwise, only pending requests can be removed.
      tags:
        - request
      parameters:
        - in: path
          name: requestId
          description: Request ID
          required: true
          example: '1'
          schema:
            type: string
      responses:
        '204':
          description: Succesfully removed request
  /request/{requestId}/retry:
    post:
      summary: Retry failed request
      description: |
        Retries a request by resending requests to Sonarr or Radarr.

        Requires the `MANAGE_REQUESTS` permission or `ADMIN`.
      tags:
        - request
      parameters:
        - in: path
          name: requestId
          description: Request ID
          required: true
          schema:
            type: string
            example: '1'
      responses:
        '200':
          description: Retry triggered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaRequest'
  /request/{requestId}/{status}:
    post:
      summary: Update a request's status
      description: |
        Updates a request's status to approved or declined. Also returns the request in a JSON object.

        Requires the `MANAGE_REQUESTS` permission or `ADMIN`.
      tags:
        - request
      parameters:
        - in: path
          name: requestId
          description: Request ID
          required: true
          schema:
            type: string
            example: '1'
        - in: path
          name: status
          description: New status
          required: true
          schema:
            type: string
            enum: [approve, decline]
      responses:
        '200':
          description: Request status changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaRequest'
  /movie/{movieId}:
    get:
      summary: Get movie details
      description: Returns full movie details in a JSON object.
      tags:
        - movies
      parameters:
        - in: path
          name: movieId
          required: true
          schema:
            type: number
            example: 337401
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Movie details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MovieDetails'
  /movie/{movieId}/recommendations:
    get:
      summary: Get recommended movies
      description: Returns list of recommended movies based on provided movie ID in a JSON object.
      tags:
        - movies
      parameters:
        - in: path
          name: movieId
          required: true
          schema:
            type: number
            example: 337401
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: List of movies
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /movie/{movieId}/similar:
    get:
      summary: Get similar movies
      description: Returns list of similar movies based on the provided movieId in a JSON object.
      tags:
        - movies
      parameters:
        - in: path
          name: movieId
          required: true
          schema:
            type: number
            example: 337401
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: List of movies
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MovieResult'
  /movie/{movieId}/ratings:
    get:
      summary: Get movie ratings
      description: Returns ratings based on the provided movieId in a JSON object.
      tags:
        - movies
      parameters:
        - in: path
          name: movieId
          required: true
          schema:
            type: number
            example: 337401
      responses:
        '200':
          description: Ratings returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                    example: Mulan
                  year:
                    type: number
                    example: 2020
                  url:
                    type: string
                    example: 'http://www.rottentomatoes.com/m/mulan_2020/'
                  criticsScore:
                    type: number
                    example: 85
                  criticsRating:
                    type: string
                    enum: ['Rotten', 'Fresh', 'Certified Fresh']
                  audienceScore:
                    type: number
                    example: 65
                  audienceRating:
                    type: string
                    enum: ['Spilled', 'Upright']
  /tv/{tvId}:
    get:
      summary: Get TV details
      description: Returns full TV details in a JSON object.
      tags:
        - tv
      parameters:
        - in: path
          name: tvId
          required: true
          schema:
            type: number
            example: 76479
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: TV details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TvDetails'
  /tv/{tvId}/episodes:
    get:
      summary: Get the canonical TVDB episode catalog
      description: Returns official TVDB episodes when TVDB episode requests are enabled for the series.
      tags:
        - tv
      parameters:
        - in: path
          name: tvId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: TVDB episode catalog returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  tvdbSeriesId:
                    type: number
                  episodes:
                    type: array
                    items:
                      $ref: '#/components/schemas/EpisodeRequest'
        '409':
          description: TVDB episode requests are not enabled
  /tv/{tvId}/season/{seasonNumber}:
    get:
      summary: Get season details and episode list
      description: Returns season details with a list of episodes in a JSON object.
      tags:
        - tv
      parameters:
        - in: path
          name: tvId
          required: true
          schema:
            type: number
            example: 76479
        - in: path
          name: seasonNumber
          required: true
          schema:
            type: number
            example: 123456
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: TV details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Season'
  /tv/{tvId}/recommendations:
    get:
      summary: Get recommended TV series
      description: Returns list of recommended TV series based on the provided tvId in a JSON object.
      tags:
        - tv
      parameters:
        - in: path
          name: tvId
          required: true
          schema:
            type: number
            example: 76479
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: List of TV series
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TvResult'
  /tv/{tvId}/similar:
    get:
      summary: Get similar TV series
      description: Returns list of similar TV series based on the provided tvId in a JSON object.
      tags:
        - tv
      parameters:
        - in: path
          name: tvId
          required: true
          schema:
            type: number
            example: 76479
        - in: query
          name: page
          schema:
            type: number
            example: 1
            default: 1
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: List of TV series
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 1
                  totalPages:
                    type: number
                    example: 20
                  totalResults:
                    type: number
                    example: 200
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TvResult'
  /tv/{tvId}/ratings:
    get:
      summary: Get TV ratings
      description: Returns ratings based on provided tvId in a JSON object.
      tags:
        - tv
      parameters:
        - in: path
          name: tvId
          required: true
          schema:
            type: number
            example: 76479
      responses:
        '200':
          description: Ratings returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                    example: The Boys
                  year:
                    type: number
                    example: 2019
                  url:
                    type: string
                    example: 'http://www.rottentomatoes.com/m/mulan_2020/'
                  criticsScore:
                    type: number
                    example: 85
                  criticsRating:
                    type: string
                    enum: ['Rotten', 'Fresh']
  /person/{personId}:
    get:
      summary: Get person details
      description: Returns person details based on provided personId in a JSON object.
      tags:
        - person
      parameters:
        - in: path
          name: personId
          required: true
          schema:
            type: number
            example: 287
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Returned person
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonDetails'
  /person/{personId}/combined_credits:
    get:
      summary: Get combined credits
      description: Returns the person's combined credits based on the provided personId in a JSON object.
      tags:
        - person
      parameters:
        - in: path
          name: personId
          required: true
          schema:
            type: number
            example: 287
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Returned combined credits
          content:
            application/json:
              schema:
                type: object
                properties:
                  cast:
                    type: array
                    items:
                      $ref: '#/components/schemas/CreditCast'
                  crew:
                    type: array
                    items:
                      $ref: '#/components/schemas/CreditCrew'
                  id:
                    type: number
  /media-actions/capabilities:
    get:
      summary: Per-user media action capabilities
      description: Returns which watched and rating operations are available for the authenticated user across providers.
      tags:
        - media
      responses:
        '200':
          description: Capability matrix for the current user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionCapabilitiesResponse'
        '401':
          description: Unauthorized
  /media-actions/status-batch:
    post:
      summary: Batch media action status
      description: Returns watched/rating status for many titles via enabled action providers (fan-out).
      tags:
        - media
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  maxItems: 100
                  items:
                    type: object
                    required:
                      - mediaType
                      - tmdbId
                    properties:
                      mediaType:
                        type: string
                        enum: [movie, tv]
                      tmdbId:
                        type: number
      responses:
        '200':
          description: Statuses returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MediaActionStatus'
  /media-actions/tv/{tmdbId}/seasons/{seasonNumber}/episodes/status:
    get:
      summary: Get episode watched status for a TV season
      description: Returns one batched set of watched episode numbers from linked providers (Trakt and/or Jellyfin) for the current user.
      tags:
        - media
      parameters:
        - in: path
          name: tmdbId
          required: true
          schema:
            type: integer
            minimum: 1
        - in: path
          name: seasonNumber
          required: true
          schema:
            type: integer
            minimum: 0
            maximum: 10000
      responses:
        '200':
          description: Episode watched status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchStatus'
  /media-actions/tv/{tmdbId}/seasons/{seasonNumber}/episodes/{episodeNumber}/watched:
    post:
      summary: Mark a TV episode watched
      tags:
        - media
      parameters:
        - in: path
          name: tmdbId
          required: true
          schema:
            type: integer
            minimum: 1
        - in: path
          name: seasonNumber
          required: true
          schema:
            type: integer
            minimum: 0
            maximum: 10000
        - in: path
          name: episodeNumber
          required: true
          schema:
            type: integer
            minimum: 0
            maximum: 10000
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jellyfinItemId:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Optional direct Jellyfin episode identity supplied by Library surfaces.
      responses:
        '200':
          description: Episode marked watched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchWriteResult'
        '207':
          description: Episode updated by only a subset of linked providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchWriteResult'
        '502':
          description: Episode watched actions are unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchWriteResult'
  /media-actions/tv/{tmdbId}/seasons/{seasonNumber}/episodes/{episodeNumber}/unwatched:
    post:
      summary: Mark a TV episode unwatched
      tags:
        - media
      parameters:
        - in: path
          name: tmdbId
          required: true
          schema:
            type: integer
            minimum: 1
        - in: path
          name: seasonNumber
          required: true
          schema:
            type: integer
            minimum: 0
            maximum: 10000
        - in: path
          name: episodeNumber
          required: true
          schema:
            type: integer
            minimum: 0
            maximum: 10000
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jellyfinItemId:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Optional direct Jellyfin episode identity supplied by Library surfaces.
      responses:
        '200':
          description: Episode marked unwatched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchWriteResult'
        '207':
          description: Episode updated by only a subset of linked providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchWriteResult'
        '502':
          description: Episode watched actions are unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchWriteResult'
  /media-actions/episodes/jellyfin/{jellyfinItemId}/watched:
    post:
      summary: Mark a Jellyfin library episode watched
      description: Uses the current user's linked Jellyfin session; no Jellyfin credentials are accepted by this endpoint.
      tags:
        - media
      parameters:
        - in: path
          name: jellyfinItemId
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
      responses:
        '200':
          description: Episode marked watched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchWriteResult'
        '502':
          description: Linked Jellyfin episode is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchWriteResult'
  /media-actions/episodes/jellyfin/{jellyfinItemId}/unwatched:
    post:
      summary: Mark a Jellyfin library episode unwatched
      description: Uses the current user's linked Jellyfin session; no Jellyfin credentials are accepted by this endpoint.
      tags:
        - media
      parameters:
        - in: path
          name: jellyfinItemId
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
      responses:
        '200':
          description: Episode marked unwatched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchWriteResult'
        '502':
          description: Linked Jellyfin episode is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeWatchWriteResult'
  /media-actions/{mediaType}/{tmdbId}/status:
    get:
      summary: Get media action status
      description: Returns watched/rating status aggregated from enabled action providers.
      tags:
        - media
      parameters:
        - in: path
          name: mediaType
          required: true
          schema:
            type: string
            enum: [movie, tv]
        - in: path
          name: tmdbId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionStatus'
  /media-actions/{mediaType}/{tmdbId}/watched:
    post:
      summary: Mark media watched
      description: Fans out mark-watched (and optional rating) to all enabled action providers.
      tags:
        - media
      parameters:
        - in: path
          name: mediaType
          required: true
          schema:
            type: string
            enum: [movie, tv]
        - in: path
          name: tmdbId
          required: true
          schema:
            type: number
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                watchedAt:
                  type: string
                  enum: [now, release]
                  default: now
                ratingStars:
                  type: number
                  minimum: 0.5
                  maximum: 5
      responses:
        '200':
          description: Marked watched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionStatus'
        '207':
          description: Partial success across providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionStatus'
        '502':
          description: Every enabled provider rejected the write
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionStatus'
  /media-actions/{mediaType}/{tmdbId}/unwatched:
    post:
      summary: Mark media unwatched
      description: Fans out unmark-watched to all enabled action providers.
      tags:
        - media
      parameters:
        - in: path
          name: mediaType
          required: true
          schema:
            type: string
            enum: [movie, tv]
        - in: path
          name: tmdbId
          required: true
          schema:
            type: number
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                removeRating:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Marked unwatched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionStatus'
        '207':
          description: Partial success across providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionStatus'
        '502':
          description: Every enabled provider rejected the write
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionStatus'
  /media-actions/{mediaType}/{tmdbId}/rate:
    post:
      summary: Rate media
      description: Fans out user score to all enabled action providers.
      tags:
        - media
      parameters:
        - in: path
          name: mediaType
          required: true
          schema:
            type: string
            enum: [movie, tv]
        - in: path
          name: tmdbId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ratingStars
              properties:
                ratingStars:
                  type: number
                  minimum: 0.5
                  maximum: 5
      responses:
        '200':
          description: Rated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionStatus'
        '207':
          description: Partial success across providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionStatus'
        '502':
          description: Every enabled provider rejected the write
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaActionStatus'
  /library/watch-now:
    get:
      summary: Get Watch Now library shelves
      description: >
        Returns Continue Watching, Recently Added, and Ready to Watch shelves
        for the authenticated user using their linked Jellyfin identity.
      tags:
        - library
      responses:
        '200':
          description: Watch Now shelves (may be empty with a code)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LibraryWatchNowResponse'
        '401':
          description: Unauthorized
  /library/available:
    get:
      summary: List available library titles
      description: >
        Paginated titles that are available or partially available in Foreseer
        and mapped to Jellyfin. Title search (`q`) uses the linked Jellyfin API.
      tags:
        - library
      parameters:
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 20
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
        - in: query
          name: mediaType
          schema:
            type: string
            enum: [movie, tv]
        - in: query
          name: q
          schema:
            type: string
      responses:
        '200':
          description: Available library page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LibraryAvailableResponse'
        '401':
          description: Unauthorized
  /library/search:
    get:
      summary: Search available library titles
      description: Search owned/available titles. Non-numeric `q` queries Jellyfin.
      tags:
        - library
      parameters:
        - in: query
          name: q
          required: true
          schema:
            type: string
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 20
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
        - in: query
          name: mediaType
          schema:
            type: string
            enum: [movie, tv]
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LibraryAvailableResponse'
        '401':
          description: Unauthorized
  /library/browse:
    get:
      summary: Browse the authenticated user's Jellyfin-visible catalog
      description: >
        Paginated Movie/Series catalog from the linked Jellyfin user view,
        enriched with Foreseer media mappings. Does not walk series seasons
        to resolve play targets.
      tags:
        - library
      parameters:
        - in: query
          name: q
          schema:
            type: string
        - in: query
          name: mediaType
          schema:
            type: string
            enum: [movie, tv]
        - in: query
          name: watched
          schema:
            type: string
            enum: [unwatched, inProgress, played]
        - in: query
          name: genre
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - in: query
          name: yearFrom
          schema:
            type: number
        - in: query
          name: yearTo
          schema:
            type: number
        - in: query
          name: sort
          schema:
            type: string
            enum: [dateAdded, title, premiereDate, lastPlayed]
        - in: query
          name: order
          schema:
            type: string
            enum: [asc, desc]
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 24
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
      responses:
        '200':
          description: Browse page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LibraryBrowseResponse'
        '401':
          description: Unauthorized
  /library/facets:
    get:
      summary: Get library browse facets
      description: Available genres and release-year bounds for the user's catalog.
      tags:
        - library
      parameters:
        - in: query
          name: mediaType
          schema:
            type: string
            enum: [movie, tv]
      responses:
        '200':
          description: Facets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LibraryFacetsResponse'
        '401':
          description: Unauthorized
  /library/items/{jellyfinItemId}:
    get:
      summary: Get library item inspector payload
      description: >
        Unified movie or series inspector. Episode ids resolve to the parent
        series. Series play targets use next-up/resume, then first episode for
        rewatch.
      tags:
        - library
      parameters:
        - in: path
          name: jellyfinItemId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Inspector payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LibraryItemInspectorResponse'
        '401':
          description: Unauthorized
  /library/items/{jellyfinItemId}/images/{imageType}:
    get:
      summary: Proxy a Jellyfin library image
      description: >
        Authenticated poster or backdrop proxy using the requesting user's
        Jellyfin token. The token is never exposed to the client.
      tags:
        - library
      parameters:
        - in: path
          name: jellyfinItemId
          required: true
          schema:
            type: string
        - in: path
          name: imageType
          required: true
          schema:
            type: string
            enum: [primary, backdrop]
      responses:
        '200':
          description: Image bytes
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '404':
          description: Image or item not found
  /library/series/{jellyfinSeriesId}:
    get:
      summary: Get Library series panel detail
      description: >
        Seasons and resolved Play-next target for an owned series, using the
        authenticated user's linked Jellyfin identity.
      tags:
        - library
      parameters:
        - in: path
          name: jellyfinSeriesId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Series panel payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LibrarySeriesDetailResponse'
        '401':
          description: Unauthorized
  /library/series/{jellyfinSeriesId}/seasons/{seasonId}/episodes:
    get:
      summary: List Library series season episodes
      description: Episodes for one season with watched/progress for the Library panel.
      tags:
        - library
      parameters:
        - in: path
          name: jellyfinSeriesId
          required: true
          schema:
            type: string
        - in: path
          name: seasonId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Season episodes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LibrarySeasonEpisodesResponse'
        '401':
          description: Unauthorized
  /media:
    get:
      summary: Get media
      description: Returns all media (can be filtered and limited) in a JSON object.
      tags:
        - media
      parameters:
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 20
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
        - in: query
          name: filter
          schema:
            type: string
            nullable: true
            enum:
              [
                all,
                available,
                partial,
                allavailable,
                processing,
                pending,
                deleted,
              ]
        - in: query
          name: sort
          schema:
            type: string
            enum: [added, modified, mediaAdded]
            default: added
      responses:
        '200':
          description: Returned media
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/MediaInfo'
  /media/{mediaId}:
    delete:
      summary: Delete media item
      description: Removes a media item. The `MANAGE_REQUESTS` permission is required to perform this action.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          description: Media ID
          required: true
          example: '1'
          schema:
            type: string
      responses:
        '204':
          description: Succesfully removed media item
  /media/{mediaId}/file:
    delete:
      summary: Delete media file
      description: Removes a media file from radarr/sonarr. The `ADMIN` permission is required to perform this action.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          description: Media ID
          required: true
          example: '1'
          schema:
            type: string
        - in: query
          name: is4k
          description: Whether to remove from 4K service instance (true) or regular service instance (false)
          required: false
          example: false
          schema:
            type: boolean
      responses:
        '204':
          description: Successfully removed media item
  /servarr/interventions:
    get:
      summary: List Servarr interventions
      description: Lists active warnings or only releases blocklisted by Foreseerr. Requires `MANAGE_REQUESTS`.
      tags: [service]
      parameters:
        - in: query
          name: mode
          schema: { type: string, enum: [active, history], default: active }
        - in: query
          name: take
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
        - in: query
          name: skip
          schema: { type: integer, minimum: 0, default: 0 }
        - in: query
          name: serviceType
          schema: { type: string, enum: [radarr, sonarr] }
        - in: query
          name: serviceId
          schema: { type: integer }
        - in: query
          name: mediaType
          schema: { type: string, enum: [movie, tv] }
      responses:
        '200':
          description: Paginated intervention records
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo: { $ref: '#/components/schemas/PageInfo' }
                  results:
                    type: array
                    items: { $ref: '#/components/schemas/ServarrIntervention' }
        '400': { description: Invalid query }
        '401': { description: Unauthorized }
        '403': { description: Insufficient permission }
  /servarr/interventions/count:
    get:
      summary: Count active and unseen Servarr interventions
      tags: [service]
      responses:
        '200':
          description: Counts for the current manager
          content:
            application/json:
              schema:
                type: object
                properties:
                  active: { type: integer }
                  unseen: { type: integer }
        '401': { description: Unauthorized }
        '403': { description: Insufficient permission }
  /servarr/interventions/seen:
    post:
      summary: Mark current Servarr interventions seen for this manager
      tags: [service]
      responses:
        '200': { description: Seen timestamp updated }
        '401': { description: Unauthorized }
        '403': { description: Insufficient permission }
  /servarr/interventions/{interventionId}/reject:
    post:
      summary: Reject and release-blocklist one warning
      description: Revalidates the exact mapped warning before deleting it from the client and blocklisting it in Arr. Requires `MANAGE_REQUESTS`.
      tags: [service]
      parameters:
        - in: path
          name: interventionId
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Warning rejected
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ServarrIntervention' }
        '400': { description: Invalid intervention ID }
        '401': { description: Unauthorized }
        '403': { description: Insufficient permission }
        '404': { description: Intervention not found }
        '409':
          description: 'Warning is no longer active, mapped, or is already being rejected'
        '502': { description: Arr or download-client rejection failed }
        '504': { description: Arr rejection timed out }
  /media/{mediaId}/servarr/context:
    get:
      summary: Get mapped Servarr management context
      description: Returns the mapped Radarr movie or Sonarr seasons and episodes. Requires `MANAGE_REQUESTS`.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          required: true
          schema:
            type: string
        - in: query
          name: is4k
          schema:
            type: boolean
      responses:
        '200':
          description: Servarr management context
        '401':
          description: Unauthorized
        '409':
          description: Media is not mapped to a configured Servarr instance
  /media/{mediaId}/servarr/releases:
    get:
      summary: Search mapped Servarr releases
      description: Searches a mapped Radarr movie or Sonarr episode/season. Requires `MANAGE_REQUESTS`.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          required: true
          schema:
            type: string
        - in: query
          name: is4k
          schema:
            type: boolean
        - in: query
          name: target
          schema:
            type: string
            enum: [episode, season]
        - in: query
          name: episodeId
          schema:
            type: integer
        - in: query
          name: seasonNumber
          schema:
            type: integer
      responses:
        '200':
          description: Release candidates with short-lived server-side tokens
        '401':
          description: Unauthorized
    post:
      summary: Grab a Servarr release
      description: 'Grabs a previously returned release token. Quality-rejected or alias-mismatched releases require `acknowledgeRejections: true`. Foreseer then tells Sonarr/Radarr to grab against the mapped series or movie (`seriesId`/`movieId`, and `shouldOverride` when needed) instead of posting only guid and indexer id. Requires `MANAGE_REQUESTS`.'
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                is4k:
                  type: boolean
                token:
                  type: string
                acknowledgeRejections:
                  type: boolean
      responses:
        '200':
          description: Release accepted by Servarr
        '401':
          description: Unauthorized
        '409':
          description: Invalid, expired, unavailable, or unacknowledged release token
  /media/{mediaId}/servarr/imports/sources:
    get:
      summary: List safe Servarr manual import sources
      description: Lists only completed queue downloads that Sonarr or Radarr has marked with an import warning, without exposing Arr filesystem paths. Requires `MANAGE_REQUESTS`.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          required: true
          schema:
            type: string
        - in: query
          name: is4k
          schema:
            type: boolean
      responses:
        '200':
          description: Opaque tokens for downloads currently requiring manual import; an empty list means no intervention is required.
        '401':
          description: Unauthorized
  /media/{mediaId}/servarr/imports/scan:
    post:
      summary: Scan a safe Servarr manual import source
      description: Asks the mapped Sonarr or Radarr instance to inspect a previously listed warning-state download. Returns 409 if Arr no longer requires manual import. Requires `MANAGE_REQUESTS`.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sourceToken]
              properties:
                is4k:
                  type: boolean
                sourceToken:
                  type: string
      responses:
        '200':
          description: Arr manual import candidates with opaque tokens
        '401':
          description: Unauthorized
        '409':
          description: Expired, invalid, or no-longer-actionable source token
  /media/{mediaId}/servarr/imports/reprocess:
    post:
      summary: Reprocess a Sonarr manual import candidate
      description: Re-evaluates a candidate using Sonarr after selecting the intended episodes. The source download must still be marked for manual import. Requires `MANAGE_REQUESTS`.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [candidateToken, episodeIds]
              properties:
                is4k:
                  type: boolean
                candidateToken:
                  type: string
                episodeIds:
                  type: array
                  items:
                    type: integer
      responses:
        '200':
          description: Reprocessed candidate with a replacement opaque token
        '401':
          description: Unauthorized
        '409':
          description: Expired, invalid, or no-longer-actionable candidate token
  /media/{mediaId}/servarr/imports:
    get:
      summary: List Servarr manual import candidates
      description: Lists candidates only from queue downloads Arr has marked for manual import. Requires `MANAGE_REQUESTS`.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          required: true
          schema:
            type: string
        - in: query
          name: is4k
          schema:
            type: boolean
      responses:
        '200':
          description: Manual import candidates with short-lived server-side tokens
        '401':
          description: Unauthorized
    post:
      summary: Submit mapped Servarr manual import
      description: Imports previously returned candidates. Requires `MANAGE_REQUESTS`.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [candidateTokens, importMode]
              properties:
                is4k:
                  type: boolean
                candidateTokens:
                  type: array
                  items:
                    type: string
                importMode:
                  type: string
                  enum: [move, copy]
                acknowledgeRejections:
                  type: boolean
                episodeMappings:
                  type: array
                  items:
                    type: object
                    required: [candidateToken, episodeIds]
                    properties:
                      candidateToken:
                        type: string
                      episodeIds:
                        type: array
                        items:
                          type: integer
                interventionId:
                  type: integer
                  description: Optional active intervention to resolve only after successful command completion.
      responses:
        '202':
          description: Manual import command accepted
        '401':
          description: Unauthorized
        '409':
          description: Invalid, expired, or unacknowledged import token
  /media/{mediaId}/servarr/commands/{token}:
    get:
      summary: Get Servarr manual import command status
      description: Returns the status of a previously submitted manual import command. Requires `MANAGE_REQUESTS`.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          required: true
          schema:
            type: string
        - in: path
          name: token
          required: true
          schema:
            type: string
        - in: query
          name: is4k
          schema:
            type: boolean
      responses:
        '200':
          description: Command status
        '401':
          description: Unauthorized
        '409':
          description: Invalid or expired command token
  /media/{mediaId}/{status}:
    post:
      summary: Update media status
      description: Updates a media item's status and returns the media in JSON format
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          description: Media ID
          required: true
          example: '1'
          schema:
            type: string
        - in: path
          name: status
          description: New status
          required: true
          example: available
          schema:
            type: string
            enum: [available, partial, processing, pending, unknown, deleted]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                is4k:
                  type: boolean
                  example: false
                  description: |
                    When true, updates the 4K status field (status4k).
                    When false or not provided, updates the regular status field (status).
                    This applies to all status values (available, partial, processing, pending, unknown).
      responses:
        '200':
          description: Returned media
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaInfo'
  /media/{mediaId}/watch_data:
    get:
      summary: Get watch data
      description: |
        Returns play count, play duration, and users who have watched the media.

        Requires the `ADMIN` permission.
      tags:
        - media
      parameters:
        - in: path
          name: mediaId
          description: Media ID
          required: true
          example: '1'
          schema:
            type: string
      responses:
        '200':
          description: Users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      playCount7Days:
                        type: number
                      playCount30Days:
                        type: number
                      playCount:
                        type: number
                      users:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
                  data4k:
                    type: object
                    properties:
                      playCount7Days:
                        type: number
                      playCount30Days:
                        type: number
                      playCount:
                        type: number
                      users:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
  /collection/{collectionId}:
    get:
      summary: Get collection details
      description: Returns full collection details in a JSON object.
      tags:
        - collection
      parameters:
        - in: path
          name: collectionId
          required: true
          schema:
            type: number
            example: 537982
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Collection details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
  /service/radarr:
    get:
      summary: Get non-sensitive Radarr server list
      description: Returns a list of Radarr server IDs and names in a JSON object.
      tags:
        - service
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RadarrSettings'
  /service/radarr/{radarrId}:
    get:
      summary: Get Radarr server quality profiles and root folders
      description: Returns a Radarr server's quality profile and root folder details in a JSON object.
      tags:
        - service
      parameters:
        - in: path
          name: radarrId
          required: true
          schema:
            type: number
            example: 0
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  server:
                    $ref: '#/components/schemas/RadarrSettings'
                  profiles:
                    $ref: '#/components/schemas/ServiceProfile'
  /service/sonarr:
    get:
      summary: Get non-sensitive Sonarr server list
      description: Returns a list of Sonarr server IDs and names in a JSON object.
      tags:
        - service
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SonarrSettings'
  /service/sonarr/{sonarrId}:
    get:
      summary: Get Sonarr server quality profiles and root folders
      description: Returns a Sonarr server's quality profile and root folder details in a JSON object.
      tags:
        - service
      parameters:
        - in: path
          name: sonarrId
          required: true
          schema:
            type: number
            example: 0
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  server:
                    $ref: '#/components/schemas/SonarrSettings'
                  profiles:
                    $ref: '#/components/schemas/ServiceProfile'
  /service/sonarr/lookup/{tmdbId}:
    get:
      summary: Get series from Sonarr
      description: Returns a list of series returned by searching for the name in Sonarr.
      tags:
        - service
      parameters:
        - in: path
          name: tmdbId
          required: true
          schema:
            type: number
            example: 0
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SonarrSeries'
  /regions:
    get:
      summary: Regions supported by TMDB
      description: Returns a list of regions in a JSON object.
      tags:
        - tmdb
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    iso_3166_1:
                      type: string
                      example: US
                    english_name:
                      type: string
                      example: United States of America
  /languages:
    get:
      summary: Languages supported by TMDB
      description: Returns a list of languages in a JSON object.
      tags:
        - tmdb
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    iso_639_1:
                      type: string
                      example: en
                    english_name:
                      type: string
                      example: English
                    name:
                      type: string
                      example: English
  /studio/{studioId}:
    get:
      summary: Get movie studio details
      description: Returns movie studio details in a JSON object.
      tags:
        - tmdb
      parameters:
        - in: path
          name: studioId
          required: true
          schema:
            type: number
            example: 2
      responses:
        '200':
          description: Movie studio details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductionCompany'
  /network/{networkId}:
    get:
      summary: Get TV network details
      description: Returns TV network details in a JSON object.
      tags:
        - tmdb
      parameters:
        - in: path
          name: networkId
          required: true
          schema:
            type: number
            example: 1
      responses:
        '200':
          description: TV network details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductionCompany'
  /genres/movie:
    get:
      summary: Get list of official TMDB movie genres
      description: Returns a list of genres in a JSON array.
      tags:
        - tmdb
      parameters:
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      example: 10751
                    name:
                      type: string
                      example: Family
  /genres/tv:
    get:
      summary: Get list of official TMDB movie genres
      description: Returns a list of genres in a JSON array.
      tags:
        - tmdb
      parameters:
        - in: query
          name: language
          schema:
            type: string
            example: en
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      example: 18
                    name:
                      type: string
                      example: Drama
  /backdrops:
    get:
      summary: Get backdrops of trending items
      description: Returns a list of backdrop image paths in a JSON array.
      security: []
      tags:
        - tmdb
      responses:
        '200':
          description: Results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /issue:
    get:
      summary: Get all issues
      description: |
        Returns a list of issues in JSON format.
      tags:
        - issue
      parameters:
        - in: query
          name: take
          schema:
            type: number
            nullable: true
            example: 20
        - in: query
          name: skip
          schema:
            type: number
            nullable: true
            example: 0
        - in: query
          name: sort
          schema:
            type: string
            enum: [added, modified]
            default: added
        - in: query
          name: filter
          schema:
            type: string
            enum: [all, open, resolved]
            default: open
        - in: query
          name: requestedBy
          schema:
            type: number
            nullable: true
            example: 1
      responses:
        '200':
          description: Issues returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Issue'
    post:
      summary: Create new issue
      description: |
        Creates a new issue
      tags:
        - issue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                issueType:
                  type: number
                message:
                  type: string
                mediaId:
                  type: number
                userId:
                  type: number
                  nullable: true
      responses:
        '201':
          description: Succesfully created the issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'

  /issue/count:
    get:
      summary: Gets issue counts
      description: |
        Returns the number of open and closed issues, as well as the number of issues of each type.
      tags:
        - issue
      responses:
        '200':
          description: Issue counts returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: number
                  video:
                    type: number
                  audio:
                    type: number
                  subtitles:
                    type: number
                  others:
                    type: number
                  open:
                    type: number
                  closed:
                    type: number
  /issue/{issueId}:
    get:
      summary: Get issue
      description: |
        Returns a single issue in JSON format.
      tags:
        - issue
      parameters:
        - in: path
          name: issueId
          required: true
          schema:
            type: number
            example: 1
      responses:
        '200':
          description: Issues returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
    delete:
      summary: Delete issue
      description: Removes an issue. If the user has the `MANAGE_ISSUES` permission, any issue can be removed. Otherwise, only a users own issues can be removed.
      tags:
        - issue
      parameters:
        - in: path
          name: issueId
          description: Issue ID
          required: true
          example: '1'
          schema:
            type: string
      responses:
        '204':
          description: Succesfully removed issue
  /issue/{issueId}/comment:
    post:
      summary: Create a comment
      description: |
        Creates a comment and returns associated issue in JSON format.
      tags:
        - issue
      parameters:
        - in: path
          name: issueId
          required: true
          schema:
            type: number
            example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
              required:
                - message
      responses:
        '200':
          description: Issue returned with new comment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
  /issueComment/{commentId}:
    get:
      summary: Get issue comment
      description: |
        Returns a single issue comment in JSON format.
      tags:
        - issue
      parameters:
        - in: path
          name: commentId
          required: true
          schema:
            type: string
            example: 1
      responses:
        '200':
          description: Comment returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueComment'
    put:
      summary: Update issue comment
      description: |
        Updates and returns a single issue comment in JSON format.
      tags:
        - issue
      parameters:
        - in: path
          name: commentId
          required: true
          schema:
            type: string
            example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
      responses:
        '200':
          description: Comment updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueComment'
    delete:
      summary: Delete issue comment
      description: |
        Deletes an issue comment. Only users with `MANAGE_ISSUES` or the user who created the comment can perform this action.
      tags:
        - issue
      parameters:
        - in: path
          name: commentId
          description: Issue Comment ID
          required: true
          example: '1'
          schema:
            type: string
      responses:
        '204':
          description: Succesfully removed issue comment
  /issue/{issueId}/{status}:
    post:
      summary: Update an issue's status
      description: |
        Updates an issue's status to approved or declined. Also returns the issue in a JSON object.

        Requires the `MANAGE_ISSUES` permission or `ADMIN`.
      tags:
        - issue
      parameters:
        - in: path
          name: issueId
          description: Issue ID
          required: true
          schema:
            type: string
            example: '1'
        - in: path
          name: status
          description: New status
          required: true
          schema:
            type: string
            enum: [open, resolved]
      responses:
        '200':
          description: Issue status changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
  /keyword/{keywordId}:
    get:
      summary: Get keyword
      description: |
        Returns a single keyword in JSON format.
      tags:
        - other
      parameters:
        - in: path
          name: keywordId
          required: true
          schema:
            type: number
            example: 1
      responses:
        '200':
          description: Keyword returned (null if not found)
          content:
            application/json:
              schema:
                nullable: true
                $ref: '#/components/schemas/Keyword'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Unable to retrieve keyword data.'
  /watchproviders/regions:
    get:
      summary: Get watch provider regions
      description: |
        Returns a list of all available watch provider regions.
      tags:
        - other
      responses:
        '200':
          description: Watch provider regions returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WatchProviderRegion'
  /watchproviders/movies:
    get:
      summary: Get watch provider movies
      description: |
        Returns a list of all available watch providers for movies.
      tags:
        - other
      parameters:
        - in: query
          name: watchRegion
          required: true
          schema:
            type: string
            example: US
      responses:
        '200':
          description: Watch providers for movies returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WatchProviderDetails'
  /watchproviders/tv:
    get:
      summary: Get watch provider series
      description: |
        Returns a list of all available watch providers for series.
      tags:
        - other
      parameters:
        - in: query
          name: watchRegion
          required: true
          schema:
            type: string
            example: US
      responses:
        '200':
          description: Watch providers for series returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WatchProviderDetails'
  /certifications/movie:
    get:
      summary: Get movie certifications
      description: Returns list of movie certifications from TMDB.
      tags:
        - other
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: Movie certifications returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificationResponse'
        '500':
          description: Unable to retrieve movie certifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    example: 500
                  message:
                    type: string
                    example: Unable to retrieve movie certifications.
  /certifications/tv:
    get:
      summary: Get TV certifications
      description: Returns list of TV show certifications from TMDB.
      tags:
        - other
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: TV certifications returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificationResponse'
        '500':
          description: Unable to retrieve TV certifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    example: 500
                  message:
                    type: string
                    example: Unable to retrieve TV certifications.
  /overrideRule:
    get:
      summary: Get override rules
      description: Returns a list of all override rules with their conditions and settings
      tags:
        - overriderule
      responses:
        '200':
          description: Override rules returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OverrideRule'
    post:
      summary: Create override rule
      description: Creates a new Override Rule from the request body.
      tags:
        - overriderule
      responses:
        '200':
          description: 'Values were successfully created'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OverrideRule'
  /settings/simkl:
    get:
      summary: Get Simkl settings
      tags: [settings]
      responses:
        '200': { description: Simkl settings returned }
    post:
      summary: Update Simkl settings
      tags: [settings]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                clientId: { type: string }
                actionsEnabled: { type: boolean }
                showCommunityRating: { type: boolean }
                posterCommunityRating: { type: boolean }
                confirmDisconnectLinkedAccounts: { type: boolean }
      responses:
        '200': { description: Simkl settings updated }
  /settings/simkl/actions:
    post:
      summary: Update Simkl media actions
      tags: [settings]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [actionsEnabled]
              properties:
                actionsEnabled: { type: boolean }
      responses:
        '200': { description: Simkl media actions updated }
  /user/{userId}/settings/linked-accounts/simkl:
    get:
      summary: Get Simkl link status for a user
      tags: [users]
      parameters:
        - in: path
          name: userId
          required: true
          schema: { type: number }
      responses:
        '200': { description: Simkl link status returned }
    patch:
      summary: Update Simkl action preference for a user
      tags: [users]
      parameters:
        - in: path
          name: userId
          required: true
          schema: { type: number }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [actionsEnabled]
              properties:
                actionsEnabled: { type: boolean }
      responses:
        '200': { description: Simkl link status returned }
    delete:
      summary: Unlink Simkl account for a user
      tags: [users]
      parameters:
        - in: path
          name: userId
          required: true
          schema: { type: number }
      responses:
        '204': { description: Simkl account unlinked }
  /user/{userId}/settings/linked-accounts/simkl/pin/code:
    post:
      summary: Start Simkl PIN authorization
      tags: [users]
      parameters:
        - in: path
          name: userId
          required: true
          schema: { type: number }
      responses:
        '200': { description: PIN code issued }
  /user/{userId}/settings/linked-accounts/simkl/pin/token:
    post:
      summary: Poll Simkl PIN authorization
      tags: [users]
      parameters:
        - in: path
          name: userId
          required: true
          schema: { type: number }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [deviceCode]
              properties:
                deviceCode: { type: string }
      responses:
        '200': { description: Simkl account linked }
        '202': { description: Authorization pending }
  /user/{userId}/settings/linked-accounts/simkl/sync:
    post:
      summary: Synchronize a linked Simkl account
      tags: [users]
      parameters:
        - in: path
          name: userId
          required: true
          schema: { type: number }
      responses:
        '200': { description: Simkl synchronization completed }
        '503': { description: Simkl cache is stale }
  /discover/simkl/library:
    get:
      summary: Get the authenticated user's Simkl library
      tags: [discover]
      parameters:
        - in: query
          name: status
          schema:
            {
              type: string,
              enum: [watching, plantowatch, hold, completed, dropped],
            }
        - in: query
          name: mediaType
          schema: { type: string, enum: [movie, tv, anime, all] }
        - in: query
          name: page
          schema: { type: number }
      responses:
        '200': { description: Simkl library returned }
  /discover/simkl/trending:
    get:
      summary: Get Simkl trending titles
      tags: [discover]
      parameters:
        - in: query
          name: mediaType
          schema: { type: string, enum: [movie, tv, anime, all] }
        - in: query
          name: period
          schema: { type: string, enum: [day, week, month] }
        - in: query
          name: page
          schema: { type: number }
      responses:
        '200': { description: Simkl trending titles returned }
  /overrideRule/{ruleId}:
    put:
      summary: Update override rule
      description: Updates an Override Rule from the request body.
      tags:
        - overriderule
      parameters:
        - in: path
          name: ruleId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OverrideRule'
    delete:
      summary: Delete override rule by ID
      description: Deletes the override rule with the provided ruleId.
      tags:
        - overriderule
      parameters:
        - in: path
          name: ruleId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Override rule successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OverrideRule'
security:
  - cookieAuth: []
  - apiKey: []