streamarr-api.yml

openapi: '3.0.2'
info:
  title: 'Streamarr API'
  version: '1.0.0'
  description: |
    This is the documentation for the Streamarr 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 Streamarr.
tags:
  - name: public
    description: Public API endpoints requiring no authentication.
  - name: settings
    description: Endpoints related to Streamarr'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: calendar
    description: Endpoints related to calendar events.
  - name: downloads
    description: Endpoints related to torrent download client management and operations.
servers:
  - url: '{server}/api/v1'
    variables:
      server:
        default: http://localhost:3000

components:
  schemas:
    CalendarEvent:
      type: object
      properties:
        id:
          type: integer
          description: Event ID
          readOnly: true
        type:
          type: string
          example: local
          description: Event type (e.g., local, sonarr, radarr)
        start:
          type: string
          format: date-time
          description: Event start date and time
        end:
          type: string
          format: date-time
          description: Event end date and time
        summary:
          type: string
          description: Event summary/title
        description:
          type: string
          description: Event description/details
        uid:
          type: string
          description: Unique event identifier
        categories:
          type: string
          description: Event categories
        status:
          type: string
          enum: [TENTATIVE, CONFIRMED, CANCELLED]
          description: Event status
        allDay:
          type: boolean
          description: Whether the event is an all-day event
          default: false
        sendNotification:
          type: boolean
          description: Whether to send notifications for this event
          default: false
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        createdBy:
          $ref: '#/components/schemas/User'
        updatedBy:
          $ref: '#/components/schemas/User'
    CalendarEventRequest:
      type: object
      required:
        - summary
        - description
        - start
        - categories
      properties:
        uid:
          type: string
          description: Unique event identifier (optional, will be auto-generated if not provided)
        summary:
          type: string
          description: Event summary/title
        description:
          type: string
          description: Event description/details
        start:
          type: string
          format: date-time
          description: Event start date and time
        end:
          type: string
          format: date-time
          description: Event end date and time
        categories:
          type: string
          description: Event categories
        status:
          type: string
          enum: [TENTATIVE, CONFIRMED, CANCELLED]
          description: Event status
          default: TENTATIVE
        allDay:
          type: boolean
          description: Whether the event is an all-day event
          default: false
        sendNotification:
          type: boolean
          description: Whether to send notifications for this event
          default: false
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
          readOnly: true
        email:
          type: string
          example: 'hey@itsme.com'
          readOnly: true
        username:
          type: string
        plexToken:
          type: string
          readOnly: true
        plexUsername:
          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
      required:
        - id
        - email
        - createdAt
        - updatedAt
    UserSettings:
      type: object
      properties:
        locale:
          type: string
        region:
          type: string
        originalLanguage:
          type: string
    MainSettings:
      type: object
      properties:
        apiKey:
          type: string
          readOnly: true
        appLanguage:
          type: string
          example: en
        applicationTitle:
          type: string
          example: Streamarr
        applicationUrl:
          type: string
          example: https://example.com
        trustProxy:
          type: boolean
          example: true
        csrfProtection:
          type: boolean
          example: false
        localLogin:
          type: boolean
          example: true
        newPlexLogin:
          type: boolean
          example: true
        defaultPermissions:
          type: number
          example: 32
        customLogo:
          type: string
          nullable: true
          description: URL path to custom uploaded logo file
          example: '/logos/logo_full.png'
        customLogoSmall:
          type: string
          nullable: true
          description: URL path to custom uploaded small logo file
          example: '/logos/logo_sm.png'
        enableTrialPeriod:
          type: boolean
          example: false
          description: Enable trial period for new users
        trialPeriodDays:
          type: integer
          minimum: 1
          maximum: 90
          example: 30
          description: Number of days for trial period (only applies when enableTrialPeriod is true)
    PlexLibrary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          example: Movies
        enabled:
          type: boolean
          example: false
      required:
        - id
        - name
        - enabled
    LibraryLink:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the library
          example: '1'
        name:
          type: string
          description: The display name of the library
          example: 'Movies'
        type:
          type: string
          enum: [movie, show]
          description: The type of media in the library
          example: 'movie'
        mediaCount:
          type: integer
          description: The total number of media items in the library
          example: 1250
        href:
          type: string
          description: The Plex web URL for accessing the library
          example: '/watch/web/index.html#!/media/123456789/com.plexapp.plugins.library?source=1'
        regExp:
          type: string
          description: Regular expression pattern for URL matching
          example: '(?=(\\/(.*)=\\1&pivot))'
        hasPlaylists:
          type: boolean
          description: Whether this library has items in at least one playlist
          example: true
      required:
        - id
        - name
        - type
        - mediaCount
        - href
        - regExp
        - hasPlaylists
    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'
        enablePlaylists:
          type: boolean
          description: Whether playlists menu item and pivot option are enabled
          example: false
        defaultPivot:
          type: string
          description: The default pivot view when a library is selected
          enum: [library, collections, categories]
          example: 'library'
      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
    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
    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
      required:
        - name
        - hostname
        - port
        - apiKey
        - useSsl
        - is4k
        - 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
      required:
        - name
        - hostname
        - port
        - apiKey
        - useSsl
        - is4k
        - isDefault
    ServarrTag:
      type: object
      properties:
        id:
          type: number
          example: 1
        label:
          type: string
          example: A Label
    ServiceSettings:
      type: object
      properties:
        enabled:
          type: boolean
          nullable: true
          example: false
        externalUrl:
          type: string
          nullable: true
    DownloadClientType:
      type: string
      enum:
        - qbittorrent
        - deluge
        - transmission
      example: qbittorrent
    DownloadClientSettings:
      type: object
      properties:
        id:
          type: number
          readOnly: true
          example: 0
        name:
          type: string
          example: 'My qBittorrent'
        client:
          $ref: '#/components/schemas/DownloadClientType'
        hostname:
          type: string
          example: '127.0.0.1'
        port:
          type: number
          example: 8080
        useSsl:
          type: boolean
          example: false
        urlBase:
          type: string
          readOnly: true
          description: Auto-generated URL base for proxy routing
          example: '/qbt'
        username:
          type: string
          nullable: true
          example: 'admin'
        password:
          type: string
          nullable: true
          writeOnly: true
        isDefault:
          type: boolean
          example: true
          description: Whether this is the default download client shown in the UI
      required:
        - name
        - client
        - hostname
    TorrentStatus:
      type: string
      enum:
        - downloading
        - seeding
        - paused
        - queued
        - checking
        - error
        - completed
        - stalled
        - moving
        - metadata
        - incomplete
        - unknown
      example: downloading
    TorrentAction:
      type: string
      enum:
        - pause
        - resume
        - remove
        - forceRecheck
        - queueUp
        - queueDown
        - topPriority
        - bottomPriority
      example: pause
    CategoryAction:
      type: string
      enum:
        - create
        - edit
        - delete
      example: create
    NormalizedTorrent:
      type: object
      properties:
        hash:
          type: string
          example: '5a8def1ffad4db26849d16f7c11c4854e1f2def8'
        name:
          type: string
          example: 'Ubuntu 22.04 LTS'
        status:
          $ref: '#/components/schemas/TorrentStatus'
        progress:
          type: number
          example: 75.5
          description: Progress percentage (0-100)
        size:
          type: number
          example: 3221225472
          description: Total size in bytes
        downloaded:
          type: number
          example: 2415919104
          description: Downloaded bytes
        uploaded:
          type: number
          example: 1073741824
          description: Uploaded bytes
        downloadSpeed:
          type: number
          example: 1048576
          description: Download speed in bytes/sec
        uploadSpeed:
          type: number
          example: 524288
          description: Upload speed in bytes/sec
        eta:
          type: number
          nullable: true
          example: 3600
          description: Estimated time remaining in seconds
        peers:
          type: number
          example: 45
        seeds:
          type: number
          example: 120
        ratio:
          type: number
          example: 1.5
        label:
          type: string
          nullable: true
          example: 'movies'
        category:
          type: string
          nullable: true
          example: 'movies'
        tags:
          type: array
          items:
            type: string
          example: ['movies', 'hd']
        dateAdded:
          type: string
          format: date-time
          example: '2024-01-25T10:00:00Z'
        dateCompleted:
          type: string
          format: date-time
          nullable: true
          example: '2024-01-25T12:30:00Z'
        savePath:
          type: string
          example: '/downloads/movies'
        clientId:
          type: number
          example: 0
          description: ID of the download client
        clientName:
          type: string
          example: 'My qBittorrent'
        priority:
          type: number
          description: Queue position/priority number. All clients show queue position. -1 if qBittorrent queueing is disabled.
          nullable: true
          example: 5
    TorrentStats:
      type: object
      properties:
        clientId:
          type: number
          example: 0
          description: Download client ID
        clientName:
          type: string
          example: 'qBittorrent'
          description: Download client name
        clientType:
          type: string
          enum: [qbittorrent, deluge, transmission]
          example: 'qbittorrent'
          description: Download client type
        connected:
          type: boolean
          example: true
          description: Whether the client is connected
        error:
          type: string
          nullable: true
          example: 'Connection refused'
          description: Error message if client failed to connect
        totalDownloadSpeed:
          type: number
          example: 5242880
          description: Total download speed in bytes/sec
        totalUploadSpeed:
          type: number
          example: 2621440
          description: Total upload speed in bytes/sec
        activeTorrents:
          type: number
          example: 5
          description: Number of active (downloading/seeding) torrents
        pausedTorrents:
          type: number
          example: 7
          description: Number of paused torrents
        totalTorrents:
          type: number
          example: 42
          description: Total number of torrents
        health:
          type: object
          nullable: true
          properties:
            status:
              type: string
              enum: [healthy, retrying, unhealthy]
              example: 'healthy'
              description: Health status of the client
            lastError:
              type: string
              nullable: true
              description: Last error message
            cooldownUntil:
              type: string
              format: date-time
              nullable: true
              description: ISO timestamp when cooldown expires
            isStale:
              type: boolean
              nullable: true
              description: Whether the client is in cooldown
    AddTorrentRequest:
      type: object
      properties:
        clientId:
          type: number
          example: 0
          description: Download client ID to use
        torrent:
          type: string
          nullable: true
          example: 'magnet:?xt=urn:btih:...'
          description: Magnet link or torrent URL
        file:
          type: string
          nullable: true
          description: Base64-encoded .torrent file content
        category:
          type: string
          nullable: true
          example: 'movies'
        savePath:
          type: string
          nullable: true
          example: '/downloads/movies'
        paused:
          type: boolean
          nullable: true
          description: Whether to add torrent in paused state
      required:
        - clientId
    CategoryActionRequest:
      type: object
      properties:
        clientId:
          type: number
          example: 0
          description: Download client ID (qBittorrent for categories, Deluge for labels, Transmission not supported)
        action:
          type: string
          enum: [create, edit, delete]
          example: create
          description: Action to perform on the category
        category:
          type: string
          example: 'movies'
          description: Category/label name
        savePath:
          type: string
          nullable: true
          example: '/downloads/movies'
          description: Save path for create/edit actions
      required:
        - clientId
        - action
        - category
    TagActionRequest:
      type: object
      properties:
        clientId:
          type: number
          example: 0
          description: Download client ID (qBittorrent for full tag support, Transmission for per-torrent labels, Deluge not supported)
        action:
          type: string
          enum: [create, delete, add, remove]
          example: add
          description: Action to perform on tags
        tags:
          type: array
          items:
            type: string
          example: ['movies', 'hd']
          description: Tag names to create/delete/add/remove
        hashes:
          type: array
          items:
            type: string
          nullable: true
          description: Torrent hashes (required for add and remove actions)
      required:
        - clientId
        - action
        - tags
    TestConnectionResponse:
      type: object
      properties:
        connected:
          type: boolean
          example: true
        version:
          type: string
          nullable: true
          example: 'v4.5.2'
        error:
          type: string
          nullable: true
          example: 'Connection refused'
    TorrentFile:
      type: object
      properties:
        name:
          type: string
          description: File name (including relative path)
        size:
          type: number
          description: File size in bytes
        progress:
          type: number
          description: File progress (percentage/100)
        priority:
          type: number
          description: File priority (0=skip, 1=normal, 6=high, 7=maximum)
        is_seed:
          type: boolean
          description: True if file is seeding/complete
        piece_range:
          type: array
          items:
            type: number
          description: Starting and ending piece indices
        availability:
          type: number
          description: Percentage of file pieces currently available
        index:
          type: number
          description: File index
    DownloadsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/NormalizedTorrent'
        stats:
          type: array
          items:
            $ref: '#/components/schemas/TorrentStats'
        pageInfo:
          type: object
          properties:
            pages:
              type: number
              example: 3
              description: Total number of pages
            page:
              type: number
              example: 1
              description: Current page number
            results:
              type: number
              example: 125
              description: Total number of results
            pageSize:
              type: number
              example: 50
              description: Number of items per page
    PublicSettings:
      type: object
      properties:
        initialized:
          type: boolean
          example: false
        customLogo:
          type: string
          nullable: true
          description: URL path to custom uploaded logo file
          example: '/logos/logo_full.png'
        customLogoSmall:
          type: string
          nullable: true
          description: URL path to custom uploaded small logo file
          example: '/logos/logo_sm.png'
    Invites:
      type: object
      properties:
        id:
          type: number
          example: 123
          readOnly: true
        status:
          type: number
          example: 0
          description: Status of the invite.
          readOnly: true
        createdAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        updatedAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        invitedBy:
          $ref: '#/components/schemas/User'
        updatedBy:
          anyOf:
            - $ref: '#/components/schemas/User'
            - type: string
              nullable: true
        profileId:
          type: number
      required:
        - id
        - status
    Notification:
      type: object
      properties:
        id:
          type: number
          example: 1
          readOnly: true
        type:
          type: string
          example: 'local_message'
        severity:
          type: string
          example: 'info'
        notifyUser:
          oneOf:
            - $ref: '#/components/schemas/User'
            - type: array
              items:
                $ref: '#/components/schemas/User'
        subject:
          type: string
          example: 'You have a new friend!'
        message:
          type: string
          example: 'Your invite code has been redeemed by {user}'
        actionUrl:
          type: string
          nullable: true
          example: '/settings/users'
        actionUrlTitle:
          type: string
          nullable: true
          example: 'View Users'
        isRead:
          type: boolean
          example: false
        createdAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
    NotificationRequest:
      type: object
      required:
        - type
        - severity
        - subject
        - notifyUser
      properties:
        type:
          type: number
          example: 512
          description: Notification type enum value (e.g., LOCAL_MESSAGE = 512)
        severity:
          type: string
          enum: [success, info, warning, error, primary, secondary, accent]
          example: 'info'
        subject:
          type: string
          example: 'Important Announcement'
          maxLength: 40
        message:
          type: string
          example: 'This is a test notification message'
          maxLength: 150
        actionUrl:
          type: string
          nullable: true
          description: URL to link to when the notification is clicked
        actionUrlTitle:
          type: string
          nullable: true
          description: Title for the action URL link
        notifyUser:
          oneOf:
            - type: number
              description: Single user ID
            - type: array
              items:
                type: number
              description: Array of user IDs
          description: User ID(s) to notify
        updatedAt:
          type: string
          example: '2020-09-12T10:00:27.000Z'
          readOnly: true
        createdBy:
          anyOf:
            - $ref: '#/components/schemas/User'
            - type: string
              nullable: true
        updatedBy:
          anyOf:
            - $ref: '#/components/schemas/User'
            - 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
    WebPushSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
    InAppNotificationSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
    RestartStatus:
      type: object
      properties:
        required:
          type: boolean
          description: Whether a restart is required
          example: true
        services:
          type: array
          items:
            type: string
          description: List of services that have changed and require a restart
          example: ['Lidarr', 'Tautulli']
    RestartResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: 'Restarting server...'
    PythonServiceStatus:
      type: object
      properties:
        status:
          type: string
          enum:
            - healthy
            - unhealthy
            - unknown
          description: Current health status of the Python service
          example: healthy
        lastChecked:
          type: string
          nullable: true
          description: ISO timestamp of last health check
          example: '2026-02-17T12:00:00.000Z'
        lastHealthy:
          type: string
          nullable: true
          description: ISO timestamp of last successful health check
          example: '2026-02-17T12:00:00.000Z'
        consecutiveFailures:
          type: number
          description: Number of consecutive failed health checks
          example: 0
    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: Streamarr
            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
    NotificationLocalSettings:
      type: object
      properties:
        enabled:
          type: boolean
          example: false
        types:
          type: number
          example: 2
    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
    SpokenLanguage:
      type: object
      properties:
        englishName:
          type: string
          example: 'English'
          nullable: true
        iso_639_1:
          type: string
          example: 'en'
        name:
          type: string
          example: 'English'
        remotePoster:
          type: string
          example: https://artworks.thetvdb.com/banners/posters/5c8f116129983.jpg
    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
    QRCode:
      type: object
      properties:
        qrCode:
          type: string
          example: '/image/qrcode/invite-1.png'
    UserSettingsNotifications:
      type: object
      properties:
        notificationTypes:
          $ref: '#/components/schemas/NotificationAgentTypes'
        emailEnabled:
          type: boolean
        pgpKey:
          type: string
          nullable: true
        inAppEnabled:
          type: boolean
    NotificationAgentTypes:
      type: object
      properties:
        email:
          type: number
        webpush:
          type: number
        inApp:
          type: number
    SignupCompleteResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
      required:
        - success
        - message
    SignupPlexAuthResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
        message:
          type: string
      required:
        - user
        - message
    InviteValidationResponse:
      type: object
      properties:
        valid:
          type: boolean
        message:
          type: string
      required:
        - valid
        - message
    WelcomeContent:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        type:
          type: string
          enum: [user, admin]
        order:
          type: integer
        enabled:
          type: boolean
        title:
          type: string
        description:
          type: string
          nullable: true
        imageUrl:
          type: string
          nullable: true
        videoUrl:
          type: string
          nullable: true
        videoAutoplay:
          type: boolean
          default: false
        customHtml:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    WelcomeContentRequest:
      type: object
      required:
        - title
      properties:
        type:
          type: string
          enum: [user, admin]
        order:
          type: integer
        enabled:
          type: boolean
        title:
          type: string
        description:
          type: string
        imageUrl:
          type: string
        videoUrl:
          type: string
        videoAutoplay:
          type: boolean
        customHtml:
          type: string
    TutorialStep:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        order:
          type: integer
        enabled:
          type: boolean
        mode:
          type: string
          enum: [spotlight, wizard, both]
        targetSelector:
          type: string
        title:
          type: string
        description:
          type: string
        tooltipPosition:
          type: string
          enum: [auto, top, bottom, left, right]
        route:
          type: string
          nullable: true
        imageUrl:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    TutorialStepRequest:
      type: object
      required:
        - title
        - description
      properties:
        order:
          type: integer
        enabled:
          type: boolean
        mode:
          type: string
          enum: [spotlight, wizard, both]
        targetSelector:
          type: string
        title:
          type: string
        description:
          type: string
        tooltipPosition:
          type: string
          enum: [auto, top, bottom, left, right]
        route:
          type: string
        imageUrl:
          type: string
    UserOnboardingStatus:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        userId:
          type: integer
        welcomeCompleted:
          type: boolean
        welcomeCompletedAt:
          type: string
          format: date-time
          nullable: true
        welcomeDismissed:
          type: boolean
        tutorialCompleted:
          type: boolean
        tutorialCompletedAt:
          type: string
          format: date-time
          nullable: true
        tutorialProgress:
          type: array
          items:
            type: integer
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    OnboardingSettings:
      type: object
      properties:
        welcomeEnabled:
          type: boolean
        tutorialEnabled:
          type: boolean
        tutorialMode:
          type: string
          enum: [spotlight, wizard, both]
        allowSkipWelcome:
          type: boolean
          description: When false, users cannot skip the welcome modal
        allowSkipTutorial:
          type: boolean
          description: When false, users cannot skip the tutorial
        tutorialAutostart:
          type: boolean
        tutorialAutostartDelay:
          type: integer
          description: Delay in milliseconds before auto-starting the tutorial
        adminOnboardingCompleted:
          type: boolean
          description: When true, admin onboarding has been completed (shown once on first admin startup)
    OnboardingSettingsRequest:
      type: object
      properties:
        welcomeEnabled:
          type: boolean
        tutorialEnabled:
          type: boolean
        tutorialMode:
          type: string
          enum: [spotlight, wizard, both]
        allowSkipWelcome:
          type: boolean
        allowSkipTutorial:
          type: boolean
        tutorialAutostart:
          type: boolean
        tutorialAutostartDelay:
          type: integer
        adminOnboardingCompleted:
          type: boolean
    UserOnboardingData:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/UserOnboardingStatus'
        settings:
          $ref: '#/components/schemas/OnboardingSettings'
        welcomeContent:
          type: array
          items:
            $ref: '#/components/schemas/WelcomeContent'
        tutorialSteps:
          type: array
          items:
            $ref: '#/components/schemas/TutorialStep'
    ReorderRequest:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: object
            required:
              - id
              - order
            properties:
              id:
                type: integer
              order:
                type: integer
  securitySchemes:
    cookieAuth:
      type: apiKey
      name: streamarr.sid
      in: cookie
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key

paths:
  /status:
    get:
      summary: Get Streamarr status
      description: Returns the current Streamarr status in a JSON object.
      security: []
      tags:
        - public
      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
  /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/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/logos/upload:
    post:
      summary: Upload custom logos
      description: Uploads custom logo files for the application.
      tags:
        - settings
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                customLogo:
                  type: string
                  format: binary
                  description: Custom logo file for desktop (recommended 190x55px)
                customLogoSmall:
                  type: string
                  format: binary
                  description: Custom logo file for mobile (recommended 45x45px)
      responses:
        '200':
          description: Logos uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Logos uploaded successfully'
        '400':
          description: Bad request - invalid file format or missing files
        '500':
          description: Internal server error
  /settings/logos/delete:
    delete:
      summary: Delete custom logos
      description: Deletes uploaded custom logo files.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum: [logo, logoSmall]
                  description: Type of logo to delete
              required:
                - type
      responses:
        '200':
          description: Logo deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Logo deleted successfully'
        '400':
          description: Bad request - invalid logo type
        '404':
          description: Logo file not found
        '500':
          description: Internal server error
  /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/services:
    get:
      summary: Get services settings
      description: Retrieves current services settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
  /settings/uptime:
    get:
      summary: Get Uptime settings
      description: Retrieves current Uptime settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
    post:
      summary: Update Uptime settings
      description: Updates Uptime settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
  /settings/downloads:
    get:
      summary: Get download client settings
      description: Returns all download client configurations in a JSON array.
      tags:
        - settings
      responses:
        '200':
          description: 'Values were returned'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DownloadClientSettings'
    post:
      summary: Create download client instance
      description: Creates a new download client configuration.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DownloadClientSettings'
      responses:
        '201':
          description: 'New download client created'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadClientSettings'
  /settings/downloads/{downloadId}:
    put:
      summary: Update download client instance
      description: Updates an existing download client configuration.
      tags:
        - settings
      parameters:
        - in: path
          name: downloadId
          required: true
          schema:
            type: integer
          description: Download client instance ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DownloadClientSettings'
      responses:
        '200':
          description: 'Download client updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadClientSettings'
    delete:
      summary: Delete download client instance
      description: Deletes an existing download client configuration.
      tags:
        - settings
      parameters:
        - in: path
          name: downloadId
          required: true
          schema:
            type: integer
          description: Download client instance ID
      responses:
        '200':
          description: 'Download client deleted'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadClientSettings'
  /settings/downloads/test:
    post:
      summary: Test download client connection
      description: Tests connection to a download client with provided settings (for new/unsaved configurations).
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  $ref: '#/components/schemas/DownloadClientType'
                hostname:
                  type: string
                  example: '127.0.0.1'
                port:
                  type: number
                  example: 8080
                useSsl:
                  type: boolean
                  example: false
                username:
                  type: string
                  nullable: true
                  example: 'admin'
                password:
                  type: string
                  nullable: true
              required:
                - client
                - hostname
                - port
      responses:
        '200':
          description: 'Connection test result'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestConnectionResponse'
  /settings/downloads/test/{clientId}:
    post:
      summary: Test existing download client connection
      description: Tests connection to an existing saved download client by ID.
      tags:
        - downloads
      parameters:
        - in: path
          name: clientId
          required: true
          schema:
            type: number
          description: Download client ID
      responses:
        '200':
          description: 'Connection test result'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestConnectionResponse'
  /settings/tdarr:
    get:
      summary: Get tdarr settings
      description: Retrieves current tdarr settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
    post:
      summary: Update tdarr settings
      description: Updates tdarr settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
  /settings/bazarr:
    get:
      summary: Get bazarr settings
      description: Retrieves current bazarr settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
    post:
      summary: Update bazarr settings
      description: Updates bazarr settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
  /settings/prowlarr:
    get:
      summary: Get prowlarr settings
      description: Retrieves current prowlarr settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
    post:
      summary: Update prowlarr settings
      description: Updates prowlarr settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
  /settings/prowlarr/test:
    post:
      summary: Test Prowlarr configuration
      description: Tests if the Prowlarr configuration is valid. Returns tags 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: 9696
                apiKey:
                  type: string
                  example: yourapikey
                useSsl:
                  type: boolean
                  example: false
                urlBase:
                  type: string
              required:
                - hostname
                - port
                - apiKey
      responses:
        '200':
          description: Successfully connected to Prowlarr instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: array
                    items:
                      type: object
                  urlBase:
                    type: string
        '500':
          description: Failed to connect to Prowlarr
  /settings/prowlarr/auth:
    get:
      summary: Get Prowlarr authentication status
      description: Returns the current authentication method configured on Prowlarr.
      tags:
        - settings
      responses:
        '200':
          description: Authentication status
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticationMethod:
                    type: string
                    enum: [None, Basic, Forms, External]
                  isAuthDisabled:
                    type: boolean
        '400':
          description: Prowlarr not configured
        '500':
          description: Failed to connect to Prowlarr
    post:
      summary: Disable authentication on Prowlarr
      description: |
        Sets the authentication method to 'External' on Prowlarr.
        This allows Streamarr to proxy the Prowlarr web UI without requiring
        separate login.
      tags:
        - settings
      responses:
        '200':
          description: Authentication disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  authenticationMethod:
                    type: string
        '400':
          description: Prowlarr not configured
        '500':
          description: Failed to disable authentication on Prowlarr
  /settings/lidarr:
    get:
      summary: Get lidarr settings
      description: Retrieves current lidarr settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
    post:
      summary: Update lidarr settings
      description: Updates lidarr settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
  /settings/lidarr/test:
    post:
      summary: Test Lidarr configuration
      description: Tests if the Lidarr configuration is valid. Returns profiles, root folders, and tags 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: 8686
                apiKey:
                  type: string
                  example: yourapikey
                useSsl:
                  type: boolean
                  example: false
                urlBase:
                  type: string
              required:
                - hostname
                - port
                - apiKey
      responses:
        '200':
          description: Successfully connected to Lidarr instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceProfile'
                  rootFolders:
                    type: array
                    items:
                      type: object
                  tags:
                    type: array
                    items:
                      type: object
                  urlBase:
                    type: string
        '500':
          description: Failed to connect to Lidarr
  /settings/lidarr/auth:
    get:
      summary: Get Lidarr authentication status
      description: Returns the current authentication method configured on Lidarr.
      tags:
        - settings
      responses:
        '200':
          description: Authentication status
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticationMethod:
                    type: string
                    enum: [None, Basic, Forms, External]
                  isAuthDisabled:
                    type: boolean
        '400':
          description: Lidarr not configured
        '500':
          description: Failed to connect to Lidarr
    post:
      summary: Disable authentication on Lidarr
      description: |
        Sets the authentication method to 'External' on Lidarr.
        This allows Streamarr to proxy the Lidarr web UI without requiring
        separate login.
      tags:
        - settings
      responses:
        '200':
          description: Authentication disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  authenticationMethod:
                    type: string
        '400':
          description: Lidarr not configured
        '500':
          description: Failed to disable authentication on Lidarr
  /settings/overseerr:
    get:
      summary: Get overseerr settings
      description: Retrieves current overseerr settings.
      tags:
        - settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
    post:
      summary: Update overseerr settings
      description: Updates overseerr settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceSettings'
      responses:
        '200':
          description: 'Values were successfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSettings'
  /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/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 invite 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}/auth:
    get:
      summary: Get Radarr authentication status
      description: Returns the current authentication method configured on the Radarr instance.
      tags:
        - settings
      parameters:
        - in: path
          name: radarrId
          required: true
          schema:
            type: integer
          description: Radarr instance ID
      responses:
        '200':
          description: Authentication status
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticationMethod:
                    type: string
                    enum: [None, Basic, Forms, External]
                  isAuthDisabled:
                    type: boolean
        '404':
          description: Radarr instance not found
        '500':
          description: Failed to connect to Radarr
    post:
      summary: Disable authentication on Radarr instance
      description: |
        Sets the authentication method to 'External' on the Radarr instance.
        This allows Streamarr to proxy the Radarr web UI without requiring
        separate login.
      tags:
        - settings
      parameters:
        - in: path
          name: radarrId
          required: true
          schema:
            type: integer
          description: Radarr instance ID
      responses:
        '200':
          description: Authentication disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  authenticationMethod:
                    type: string
        '404':
          description: Radarr instance not found
        '500':
          description: Failed to disable authentication on Radarr
  /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 invite 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/sonarr/{sonarrId}/auth:
    get:
      summary: Get Sonarr authentication status
      description: Returns the current authentication method configured on the Sonarr instance.
      tags:
        - settings
      parameters:
        - in: path
          name: sonarrId
          required: true
          schema:
            type: integer
          description: Sonarr instance ID
      responses:
        '200':
          description: Authentication status
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticationMethod:
                    type: string
                    enum: [None, Basic, Forms, External]
                  isAuthDisabled:
                    type: boolean
        '404':
          description: Sonarr instance not found
        '500':
          description: Failed to connect to Sonarr
    post:
      summary: Disable authentication on Sonarr instance
      description: |
        Sets the authentication method to 'External' on the Sonarr instance.
        This allows Streamarr to proxy the Sonarr web UI without requiring
        separate login.
      tags:
        - settings
      parameters:
        - in: path
          name: sonarrId
          required: true
          schema:
            type: integer
          description: Sonarr instance ID
      responses:
        '200':
          description: Authentication disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  authenticationMethod:
                    type: string
        '404':
          description: Sonarr instance not found
        '500':
          description: Failed to disable authentication on Sonarr
  /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'
  /libraries:
    get:
      summary: Get public library stats
      security: []
      description: Returns enabled libraries and their total media counts. Mainly used for library stats on the index.
      tags:
        - settings
      responses:
        '200':
          description: List of enabled libraries with media counts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlexLibrary'
  /libraries/items:
    get:
      summary: Get library links for authenticated user
      description: Returns library links with Plex URLs for libraries the authenticated user has access to. Only accessible to authenticated users.
      tags:
        - settings
      parameters:
        - name: sort
          in: query
          description: Sort order for the library links
          required: false
          schema:
            type: string
            enum: [id, name, type]
            default: id
      responses:
        '200':
          description: Library links with metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  machineId:
                    type: string
                    description: The Plex server machine identifier
                    example: '65c8e6766fed4f8450771fbc9a6a9081c6ed698d'
                  enablePlaylists:
                    type: boolean
                    description: Whether playlists are enabled
                    example: false
                  defaultPivot:
                    type: string
                    description: The admin-configured default pivot view
                    enum: [library, collections, categories]
                    example: 'library'
                  libraries:
                    type: array
                    items:
                      $ref: '#/components/schemas/LibraryLink'
                required:
                  - machineId
                  - enablePlaylists
                  - defaultPivot
                  - libraries
        '401':
          description: Unauthorized - user not authenticated
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlexLibrary'
  /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/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
                  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/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 3000
                    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/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/inapp:
    get:
      summary: Get in-app notification settings
      description: Returns current in-app notification settings in a JSON object.
      tags:
        - settings
      responses:
        '200':
          description: Returned inapp settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InAppNotificationSettings'
    post:
      summary: Update in-app notification settings
      description: Updates in-app notification settings with the provided values.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InAppNotificationSettings'
      responses:
        '200':
          description: 'Values were sucessfully updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InAppNotificationSettings'
  /settings/notifications/inapp/test:
    post:
      summary: Test in-app notification settings
      description: Sends a test notification to the in-app notification agent.
      tags:
        - settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InAppNotificationSettings'
      responses:
        '204':
          description: Test notification attempted
  /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'
                  totalInvites:
                    type: number
                    example: 100
                  tz:
                    type: string
                    nullable: true
                    example: Asia/Tokyo
                  appDataPath:
                    type: string
                    example: /app/config
  /settings/releases:
    get:
      summary: Get GitHub releases
      description: Returns a list of Streamarr releases from GitHub, served through the server-side cache. Requires admin authentication.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: List of releases
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    url:
                      type: string
                    assets_url:
                      type: string
                    upload_url:
                      type: string
                    html_url:
                      type: string
                    id:
                      type: number
                    node_id:
                      type: string
                    tag_name:
                      type: string
                    target_commitish:
                      type: string
                    name:
                      type: string
                    draft:
                      type: boolean
                    prerelease:
                      type: boolean
                    created_at:
                      type: string
                    published_at:
                      type: string
                    tarball_url:
                      type: string
                    zipball_url:
                      type: string
                    body:
                      type: string
                  additionalProperties: true
        '401':
          description: Unauthorized - user not authenticated
        '403':
          description: Forbidden - user lacks admin permission
  /settings/restart-required:
    get:
      summary: Check if server restart is required
      description: Returns whether a restart is required and which services have changed since startup.
      tags:
        - settings
      responses:
        '200':
          description: Restart status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestartStatus'
  /settings/restart:
    post:
      summary: Trigger server restart
      description: Initiates a graceful server restart. The server will close connections, disconnect sockets, and exit. Docker/PM2/systemd will restart the process.
      tags:
        - settings
      responses:
        '200':
          description: Restart initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestartResponse'
        '500':
          description: Failed to trigger restart
  /settings/python/status:
    get:
      summary: Get Python service health status
      description: Returns the current health status of the Python (Plex Sync) service.
      tags:
        - settings
      responses:
        '200':
          description: Python service status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PythonServiceStatus'
  /settings/python/restart:
    post:
      summary: Restart Python service
      description: Restarts the Python (Plex Sync) service without restarting the main Streamarr server.
      tags:
        - settings
      responses:
        '200':
          description: Python service restarted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestartResponse'
        '500':
          description: Failed to restart Python service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestartResponse'
  /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 invites. 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/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 invites.
      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/plex/token:
    get:
      summary: Get Plex authentication token
      description: Returns the authenticated user's Plex token for client-side Plex integration. Requires an active session.
      tags:
        - auth
      responses:
        '200':
          description: Successfully retrieved Plex token
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: The user's Plex authentication token
                    example: 'xxxxxxxxxxxxxxxxxxxx'
        '404':
          description: User does not have a Plex token
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    example: 404
                  message:
                    type: string
                    example: 'Plex token not found'
        '500':
          description: Server error while retrieving token
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    example: 500
                  message:
                    type: string
                    example: 'Failed to retrieve Plex token'
  /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, invites, displayname]
            default: created
      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 invite `body.settings`. You cannot update users' Plex tokens through this invite.

        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 invite 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/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/{key}:
    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: key
          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: key
          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 invite.

        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/{userId}/invites:
    get:
      summary: Get invites for a specific user
      description: |
        Retrieves a user's invites 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 invites returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invites'
  /user/{userId}/notifications:
    get:
      summary: Get notifications for a specific user
      description: |
        Retrieves a user's notifications 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
        - in: query
          name: filter
          schema:
            type: string
            nullable: true
            enum: [all, read, unread]
      responses:
        '200':
          description: User's notifications returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Notification'
    put:
      summary: Bulk update notifications for a specific user
      description: |
        Bulk updates notifications for a specific user. Can update all notifications or specific ones by providing notificationIds.

        **Permission Requirements:**
        - For `isRead` property updates: User must own notifications OR have `MANAGE_USERS` permission
        - For other notification properties: User must have `CREATE_NOTIFICATIONS` OR `MANAGE_NOTIFICATIONS` permission

        **Usage:**
        - Omit `notificationIds` to update ALL user notifications
        - Include `notificationIds` array to update only specific notifications
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Notification'
                - type: object
                  properties:
                    notificationIds:
                      type: array
                      items:
                        type: number
                      description: Optional array of specific notification IDs to update. If omitted, all user notifications will be updated.
              example:
                isRead: true
                notificationIds: [1, 2, 3]
      responses:
        '200':
          description: Notifications successfully updated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Notification'
  /user/{userId}/notifications/{notificationId}:
    put:
      summary: Update a notification for a specific user
      description: Updates a user's notification by ID. Requires `MANAGE_USERS` permission if updating other users' notifications.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
        - in: path
          name: notificationId
          required: true
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notification'
      responses:
        '200':
          description: Notification successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
    delete:
      summary: Delete a notification for a specific user
      description: Deletes a user's notification by ID. Requires `MANAGE_USERS` permission if deleting other users' notifications.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
        - in: path
          name: notificationId
          required: true
          schema:
            type: number
      responses:
        '204':
          description: Notification successfully deleted
  /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:
                  invite:
                    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
                        description: Whether user is restricted from creating invites
                      trialPeriodActive:
                        type: boolean
                        example: false
                        description: Whether user is currently in trial period
                      trialPeriodEndsAt:
                        type: string
                        format: date-time
                        nullable: true
                        example: '2025-12-01T00:00:00.000Z'
                        description: End date of user's trial period
  /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:
                type: object
                properties:
                  username:
                    type: string
                    example: 'Mr User'
                  locale:
                    type: string
                    nullable: true
                    example: 'en'
                  inviteQuotaLimit:
                    type: integer
                    nullable: true
                  inviteQuotaDays:
                    type: integer
                    nullable: true
                  globalInviteQuotaDays:
                    type: integer
                  globalInviteQuotaLimit:
                    type: integer
                  globalInviteUsageLimit:
                    type: integer
                  globalInvitesExpiryLimit:
                    type: integer
                  globalInvitesExpiryTime:
                    type: string
                    enum: [days, weeks, months]
                  globalAllowDownloads:
                    type: boolean
                  globalLiveTv:
                    type: boolean
                  globalPlexHome:
                    type: boolean
                  sharedLibraries:
                    type: string
                    nullable: true
                  allowDownloads:
                    type: boolean
                  allowLiveTv:
                    type: boolean
                  globalSharedLibraries:
                    type: string
                    nullable: true
                  trialPeriodEndsAt:
                    type: string
                    format: date-time
                    nullable: true
                    description: End date of user's trial period
                  globalEnableTrialPeriod:
                    type: boolean
                    description: Global trial period setting
                  globalTrialPeriodDays:
                    type: integer
                    description: Global default trial period in days
                  tautulliBaseUrl:
                    type: string
                    nullable: true
                    example: '/tautulli'
                  tautulliEnabled:
                    type: boolean
                    description: Whether Tautulli integration is enabled
                  requestUrl:
                    type: string
                    nullable: true
                    example: '/overseerr'
                    description: Overseerr proxy URL base path
                  requestHostname:
                    type: string
                    nullable: true
                    example: 'localhost:5055'
                    description: Overseerr hostname and port
                  releaseSched:
                    type: boolean
                    description: Whether release schedule feature is enabled
    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:
              type: object
              properties:
                username:
                  type: string
                  nullable: true
                locale:
                  type: string
                  nullable: true
                inviteQuotaLimit:
                  type: integer
                  nullable: true
                inviteQuotaDays:
                  type: integer
                  nullable: true
                sharedLibraries:
                  type: string
                  nullable: true
                allowDownloads:
                  type: boolean
                allowLiveTv:
                  type: boolean
                trialPeriodEndsAt:
                  type: string
                  format: date-time
                  nullable: true
                  description: Trial period end date (only editable by MANAGE_USERS, not on self/owner/other admins)
      responses:
        '200':
          description: Updated user general settings returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                    example: 'Mr User'
  /user/{userId}/plex/libraries:
    get:
      summary: Get user's current Plex library access
      description: Fetches the user's current library access and permissions from Plex server. Only works for Plex users. Requires `MANAGE_USERS` permission if viewing other users.
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Current Plex library access and permissions returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  currentPlexLibraries:
                    type: string
                    nullable: true
                    description: Pipe-separated list of library IDs user has access to in Plex (empty string means all libraries, null means unable to fetch)
                    example: '1|2|3'
                  canFetchFromPlex:
                    type: boolean
                    description: Whether the system can fetch from Plex (false for non-Plex users)
                  permissions:
                    type: object
                    nullable: true
                    description: User's current Plex permissions
                    properties:
                      allowSync:
                        type: boolean
                        description: Whether user can download/sync content
                      allowCameraUpload:
                        type: boolean
                        description: Whether user can upload camera photos
                      allowChannels:
                        type: boolean
                        description: Whether user can access live TV channels
                  error:
                    type: string
                    nullable: true
  /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/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}/settings/pin-libraries:
    post:
      summary: Pin libraries to user's Plex home screen
      description: |
        Pins all shared libraries for a Plex user to their Plex home screen.

        This endpoint:
        - Retrieves the user's current Plex settings
        - Preserves pins from other Plex servers
        - Adds/updates pins for libraries shared from this server
        - Sorts libraries by ID (Movies and TV Shows interleaved), then Music, then Discover, then Watchlist
        - Automatically includes Discover and Watchlist

        Requires the user to be authenticated as themselves or have `MANAGE_USERS` permission.
        Only works for Plex users (userType === PLEX).
      tags:
        - users
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: number
          description: User ID to pin libraries for
      responses:
        '200':
          description: Libraries pinned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Libraries pinned successfully
                  pinned_count:
                    type: number
                    example: 4
                    description: Number of libraries pinned
        '400':
          description: Bad request (non-Plex user, missing token, etc.)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Library pinning is only available for Plex users.
        '403':
          description: Forbidden - user lacks permission
        '404':
          description: User not found
        '500':
          description: Server error during pinning operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Failed to pin libraries
  /downloads:
    get:
      summary: Get all torrents from download clients
      description: Returns torrents with pagination, filtering, and sorting support.
      tags:
        - downloads
      parameters:
        - in: query
          name: page
          schema:
            type: number
            default: 1
          description: Page number for pagination
        - in: query
          name: pageSize
          schema:
            type: number
            default: 50
          description: Number of items per page
        - in: query
          name: clientId
          schema:
            type: number
          description: Filter by specific download client ID
        - in: query
          name: status
          schema:
            $ref: '#/components/schemas/TorrentStatus'
          description: >
            Filter by torrent status. Accepts any TorrentStatus value, or
            'incomplete' to match all non-completed/non-seeding statuses
            (downloading, paused, stalled, queued, checking, error, moving, metadata).
        - in: query
          name: category
          schema:
            type: string
          description: Filter by category/label
        - in: query
          name: search
          schema:
            type: string
          description: Search in torrent names
        - in: query
          name: sort
          schema:
            type: string
            enum:
              - name
              - progress
              - size
              - status
              - eta
              - ratio
              - addedDate
              - speed
              - priority
              - client
            default: addedDate
          description: Sort field
        - in: query
          name: sortDirection
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Sort direction (ascending or descending)
      responses:
        '200':
          description: 'Torrents returned with stats'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadsResponse'
  /downloads/add:
    post:
      summary: Add a new torrent
      description: Adds a torrent via magnet link, URL, or .torrent file upload.
      tags:
        - downloads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTorrentRequest'
      responses:
        '200':
          description: 'Torrent added successfully'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  hash:
                    type: string
                    nullable: true
                    example: '5a8def1ffad4db26849d16f7c11c4854e1f2def8'
  /downloads/{hash}/action:
    post:
      summary: Perform action on a torrent
      description: Perform pause, resume, remove, or forceRecheck actions on a torrent.
      tags:
        - downloads
      parameters:
        - in: path
          name: hash
          required: true
          schema:
            type: string
          description: Torrent hash
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  $ref: '#/components/schemas/TorrentAction'
                clientId:
                  type: number
                  example: 0
                  description: Download client ID
                deleteFiles:
                  type: boolean
                  default: false
                  description: Whether to delete files when removing torrent
              required:
                - action
                - clientId
              additionalProperties: false
      responses:
        '200':
          description: 'Action performed successfully'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
  /downloads/action:
    post:
      summary: Perform action on multiple torrents
      description: Perform pause, resume, remove, or forceRecheck actions on multiple torrents.
      tags:
        - downloads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                torrents:
                  type: array
                  items:
                    type: object
                    properties:
                      hash:
                        type: string
                        description: Torrent hash
                      clientId:
                        type: number
                        description: Download client ID
                    required:
                      - hash
                      - clientId
                  description: Array of torrents to perform action on
                  minItems: 1
                action:
                  $ref: '#/components/schemas/TorrentAction'
                deleteFiles:
                  type: boolean
                  default: false
                  description: Whether to delete files when removing torrents
              required:
                - torrents
                - action
              additionalProperties: false
      responses:
        '200':
          description: 'Bulk action completed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: True if all actions succeeded
                    example: true
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        hash:
                          type: string
                        clientId:
                          type: number
                        success:
                          type: boolean
                        error:
                          type: string
                          nullable: true
                  summary:
                    type: object
                    properties:
                      total:
                        type: number
                        example: 5
                      success:
                        type: number
                        example: 4
                      failed:
                        type: number
                        example: 1
  /downloads/category:
    post:
      summary: Manage categories/labels
      description: |
        Create, edit, or delete categories (qBittorrent) or labels (Deluge).
        - **qBittorrent**: Supports create/edit/delete categories with save paths
        - **Deluge**: Supports create/delete labels (no edit support, no save paths)
        - **Transmission**: Not supported
      tags:
        - downloads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryActionRequest'
      responses:
        '200':
          description: 'Category action performed successfully'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
  /downloads/tag:
    post:
      summary: Manage tags
      description: |
        Create/delete global tags, or add/remove tags from torrents.
        - **qBittorrent**: Full support for global tags and per-torrent tag assignment
        - **Transmission**: Supports adding/removing labels on torrents (no global tag management)
        - **Deluge**: Not supported
      tags:
        - downloads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagActionRequest'
      responses:
        '200':
          description: 'Tag action performed successfully'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
  /downloads/tags/{clientId}:
    get:
      summary: Get all tags for a client
      description: |
        Retrieves the list of all available tags for a download client.
        Only supported by qBittorrent.
      tags:
        - downloads
      parameters:
        - in: path
          name: clientId
          required: true
          schema:
            type: integer
          description: Download client ID
      responses:
        '200':
          description: 'Tags list'
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: array
                    items:
                      type: string
                    example: ['movies', 'tv', 'music']
  /downloads/{hash}/files:
    get:
      summary: Get torrent file list
      description: |
        Retrieves the list of files within a specific torrent.
        Supported by all clients: qBittorrent, Deluge, and Transmission.
      tags:
        - downloads
      parameters:
        - in: path
          name: hash
          required: true
          schema:
            type: string
          description: Torrent hash
        - in: query
          name: clientId
          required: true
          schema:
            type: integer
          description: Download client ID
      responses:
        '200':
          description: 'Torrent files list'
          content:
            application/json:
              schema:
                type: object
                properties:
                  files:
                    type: array
                    items:
                      $ref: '#/components/schemas/TorrentFile'
  /downloads/{hash}:
    patch:
      summary: Update torrent metadata
      description: |
        Update torrent category/label and/or save path.
        - **qBittorrent**: Full support for categories and location changes
        - **Deluge**: Supports labels and location changes via move_completed options
        - **Transmission**: Supports labels and location moves via moveTorrent
      tags:
        - downloads
      parameters:
        - in: path
          name: hash
          required: true
          schema:
            type: string
          description: Torrent hash
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - clientId
              properties:
                clientId:
                  type: integer
                  description: Download client ID
                category:
                  type: string
                  description: New category name
                savePath:
                  type: string
                  description: New save path
      responses:
        '200':
          description: 'Torrent updated successfully'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /downloads/{hash}/files/priority:
    post:
      summary: Set file priority
      description: |
        Set priority for specific files within a torrent.
        - **qBittorrent**: 0=skip, 1=normal, 6=high, 7=maximal
        - **Deluge**: 0=skip, 1=low, 2=normal, 5=high (updates full priority array)
        - **Transmission**: Mapped to priority-low/normal/high arrays
      tags:
        - downloads
      parameters:
        - in: path
          name: hash
          required: true
          schema:
            type: string
          description: Torrent hash
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - clientId
                - fileIds
                - priority
              properties:
                clientId:
                  type: integer
                  description: Download client ID
                fileIds:
                  type: array
                  items:
                    type: integer
                  description: Array of file indices to update
                priority:
                  type: integer
                  description: |
                    Priority level (client-specific):
                    - qBittorrent: 0=skip, 1=normal, 6=high, 7=maximum
                    - Deluge: 0=skip, 1=low, 2=normal, 5=high
                    - Transmission: 0=skip, 1=low, 2=normal, 6=high
                  enum: [0, 1, 2, 5, 6, 7]
      responses:
        '200':
          description: 'File priority updated successfully'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /downloads/health:
    get:
      summary: Get health status for all download clients
      description: Returns health status, error messages, and cooldown information for all configured download clients.
      tags:
        - downloads
      responses:
        '200':
          description: 'Health status for all clients'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    clientId:
                      type: number
                      example: 0
                    clientName:
                      type: string
                      example: 'qBittorrent'
                    status:
                      type: string
                      enum: [healthy, retrying, unhealthy]
                      example: 'healthy'
                    lastError:
                      type: string
                      nullable: true
                      example: 'Connection timeout'
                    cooldownUntil:
                      type: string
                      format: date-time
                      nullable: true
                    isStale:
                      type: boolean
                      example: false
  /downloads/health/retry:
    post:
      summary: Retry all unhealthy download clients
      description: Resets cooldown and attempts to reconnect to all unhealthy download clients.
      tags:
        - downloads
      responses:
        '200':
          description: 'Retry results for all unhealthy clients'
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        clientId:
                          type: number
                        clientName:
                          type: string
                        success:
                          type: boolean
                        health:
                          type: object
                          properties:
                            status:
                              type: string
                              enum: [healthy, retrying, unhealthy]
                            lastError:
                              type: string
                              nullable: true
                            cooldownUntil:
                              type: string
                              format: date-time
                              nullable: true
                            isStale:
                              type: boolean
  /downloads/health/retry/{clientId}:
    post:
      summary: Retry specific download client
      description: Resets cooldown and attempts to reconnect to a specific download client.
      tags:
        - downloads
      parameters:
        - in: path
          name: clientId
          required: true
          schema:
            type: integer
          description: Download client ID to retry
      responses:
        '200':
          description: 'Retry result for specific client'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  health:
                    type: object
                    properties:
                      status:
                        type: string
                        enum: [healthy, retrying, unhealthy]
                      lastError:
                        type: string
                        nullable: true
                      cooldownUntil:
                        type: string
                        format: date-time
                        nullable: true
                      isStale:
                        type: boolean
  /invite:
    get:
      summary: Get all invites
      description: |
        Returns all invites if the user has the `ADMIN` or `MANAGE_INVITES` permissions. Otherwise, only the logged-in user's invites are returned.

        If the `createdBy` parameter is specified, only invites from that particular user ID will be returned.
      tags:
        - invite
      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, active, inactive, expired, deleted, redeemed]
        - in: query
          name: sort
          schema:
            type: string
            enum: [created, modified]
            default: created
        - in: query
          name: createdBy
          schema:
            type: number
            nullable: true
            example: 1
      responses:
        '200':
          description: invites returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invites'
    post:
      summary: Create new invite
      description: |
        Creates a new invite with the provided media ID and type. The `invite` permission is required.
        If the user has the `ADMIN` or `AUTO_APPROVE` permissions, their invite will be auomatically approved.
      tags:
        - invite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: number
                  nullable: true
      responses:
        '201':
          description: Succesfully created the invite
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invites'
        '403':
          description: User is in trial period or does not have permission
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: 'You cannot create invites while in your trial period. Trial ends on 2025-12-01'
  /invite/count:
    get:
      summary: Gets invite counts
      description: |
        Returns the number of pending and approved invites.
      tags:
        - invite
      responses:
        '200':
          description: invite counts returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: number
                  pending:
                    type: number
                  approved:
                    type: number
                  declined:
                    type: number
                  processing:
                    type: number
                  available:
                    type: number
  /invite/{inviteId}:
    get:
      summary: Get Invites
      description: Returns a specific Invites in a JSON object.
      tags:
        - invite
      parameters:
        - in: path
          name: inviteId
          description: invite ID
          required: true
          example: '1'
          schema:
            type: string
      responses:
        '200':
          description: Succesfully returns invite
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invites'
    put:
      summary: Update Invites
      description: Updates a specific media invite and returns the invite in a JSON object. Requires the `MANAGE_INVITES` permission.
      tags:
        - invite
      parameters:
        - in: path
          name: inviteId
          description: invite ID
          required: true
          example: '1'
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: number
                  nullable: true
      responses:
        '200':
          description: Succesfully updated invite
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invites'
    delete:
      summary: Delete invite
      description: Removes a invite. If the user has the `MANAGE_INVITES` permission, any invite can be removed. Otherwise, only pending invites can be removed.
      tags:
        - invite
      parameters:
        - in: path
          name: inviteId
          description: invite ID
          required: true
          example: '1'
          schema:
            type: string
      responses:
        '204':
          description: Succesfully removed invite
  /invite/{inviteId}/retry:
    post:
      summary: Retry failed invite
      description: |
        Retries a invite by resending invites to Sonarr or Radarr.

        Requires the `MANAGE_INVITES` permission or `ADMIN`.
      tags:
        - invite
      parameters:
        - in: path
          name: inviteId
          description: invite ID
          required: true
          schema:
            type: string
            example: '1'
      responses:
        '200':
          description: Retry triggered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invites'
  /invite/{inviteId}/{status}:
    post:
      summary: Update an invite's status
      description: |
        Updates an invite's status to active, inactive, expired or redeemed. Also returns the invite in a JSON object.
      tags:
        - invite
      parameters:
        - in: path
          name: inviteId
          description: invite ID
          required: true
          schema:
            type: string
            example: '1'
        - in: path
          name: status
          description: New status
          required: true
          schema:
            type: string
            enum: [active, inactive, expired, redeemed]
      responses:
        '200':
          description: invite status changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invites'
  /notification:
    get:
      summary: Get notifications
      description: Returns a list of notifications for the user.
      tags:
        - notification
      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, read, unread]
        - in: query
          name: sort
          schema:
            type: string
            enum: [created, modified]
            default: created
        - in: query
          name: createdBy
          schema:
            type: number
            nullable: true
            example: 1
      responses:
        '200':
          description: A list of notifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Notification'
    post:
      summary: Create a notification
      description: Creates a new notification for one or more users.
      tags:
        - notification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationRequest'
      responses:
        '201':
          description: Notification created successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Notification'
                  - type: array
                    items:
                      $ref: '#/components/schemas/Notification'
        '400':
          description: Bad request - validation error or user has disabled notification type
        '403':
          description: Forbidden - insufficient permissions
        '500':
          description: Server error
  /notification/{notificationId}:
    put:
      summary: Update a notification
      description: Updates an existing notification for the user.
      tags:
        - notification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notification'
      responses:
        '200':
          description: Notification updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
    delete:
      summary: Delete a notification
      description: Deletes an existing notification for the user.
      tags:
        - notification
      responses:
        '204':
          description: Notification deleted
  /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
  /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: invite 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: invite 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: invite 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: invite 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: invite successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SonarrSeries'
  /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
  /invite/{inviteId}/qrcode:
    get:
      summary: Get QR code image for invite
      description: |
        Returns the QR code image for the specified invite. If the QR code is not cached, it will be generated and cached automatically.
        Requires authentication and invite permissions.
      tags:
        - invite
      parameters:
        - in: path
          name: inviteId
          required: true
          schema:
            type: string
          description: The ID of the invite
      responses:
        '200':
          description: QR code image returned
          content:
            image/png:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized or insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '404':
          description: Invite or QR code not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
    delete:
      summary: Delete invite QR code
      description: Deletes the cached QR code image for the specified invite. Requires `MANAGE_INVITES` or `CREATE_INVITES` permission. Only the invite creator or users with `MANAGE_INVITES` can delete the QR code.
      tags:
        - invite
      parameters:
        - in: path
          name: inviteId
          description: invite ID
          required: true
          schema:
            type: string
            example: '1'
      responses:
        '204':
          description: Successfully deleted QR code image
        '401':
          description: Unauthorized You do not have permission to delete this QR code
        '404':
          description: QR code not found
  /calendar/sonarr:
    get:
      summary: Get Sonarr calendar events
      description: Returns a list of cached Sonarr calendar events (requires VIEW_SCHEDULE permission).
      tags:
        - calendar
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: List of Sonarr calendar events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalendarEvent'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
  /calendar/radarr:
    get:
      summary: Get Radarr calendar events
      description: Returns a list of cached Radarr calendar events (requires VIEW_SCHEDULE permission).
      tags:
        - calendar
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: List of Radarr calendar events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalendarEvent'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
  /calendar/local:
    get:
      summary: Get local calendar events
      description: Returns a list of cached local calendar events (requires VIEW_SCHEDULE permission).
      tags:
        - calendar
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: List of local calendar events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalendarEvent'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
    post:
      summary: Create local calendar Event
      description: Creates a new local calendar event (requires CREATE_EVENTS permission).
      tags:
        - calendar
      security:
        - cookieAuth: []
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalendarEventRequest'
      responses:
        '200':
          description: Event created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarEvent'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
  /calendar/local/{eventId}:
    put:
      summary: Update local calendar event
      description: Updates a local calendar event (requires EDIT_EVENTS permission).
      tags:
        - calendar
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: eventId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalendarEventRequest'
      responses:
        '200':
          description: Event updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarEvent'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
    delete:
      summary: Delete local calendar event
      description: Deletes a local calendar event (requires DELETE_EVENTS permission).
      tags:
        - calendar
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '204':
          description: Event deleted successfully
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
  /signup/validate/{icode}:
    get:
      tags:
        - public
      summary: Validate an invite code for signup
      parameters:
        - name: icode
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Invite code is valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteValidationResponse'
        '404':
          description: Invite code not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteValidationResponse'

  /signup/plexauth:
    post:
      tags:
        - public
      summary: Authenticate user with Plex and create account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                authToken:
                  type: string
                  description: Plex authentication token
                icode:
                  type: string
                  description: Invite code
              required:
                - authToken
                - icode
      responses:
        '200':
          description: Plex authentication successful and user created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupPlexAuthResponse'

  /signup/localauth:
    post:
      tags:
        - public
      summary: Create local user account with email and password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: User's email address
                username:
                  type: string
                  description: Desired username
                  minLength: 3
                  maxLength: 20
                  pattern: '^[a-zA-Z0-9_-]+$'
                password:
                  type: string
                  description: User's password
                  minLength: 8
                confirmPassword:
                  type: string
                  description: Password confirmation
                icode:
                  type: string
                  description: Invite code
              required:
                - email
                - username
                - password
                - confirmPassword
                - icode
      responses:
        '200':
          description: Local account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupPlexAuthResponse'
        '400':
          description: Invalid input or user already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string

  /signup/complete:
    post:
      tags:
        - public
      summary: Finalize signup and update invite
      description: |
        Completes the user signup process by updating profile information and optionally auto-pinning libraries.

        If `autoPinLibraries` is true and the user is a Plex user, their shared libraries will be automatically
        pinned to their Plex home screen in the background (non-blocking).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                icode:
                  type: string
                  description: Invite code used for signup
                userId:
                  type: integer
                  description: User ID to finalize
                displayName:
                  type: string
                  description: Display name for the user
                password:
                  type: string
                  description: Optional password for local authentication
                autoPinLibraries:
                  type: boolean
                  description: Whether to automatically pin libraries to Plex home screen (Plex users only)
                  default: true
              required:
                - userId
      responses:
        '200':
          description: Signup complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupCompleteResponse'
  /settings/onboarding:
    get:
      summary: Get onboarding settings
      description: Returns the current onboarding configuration.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: Onboarding settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingSettings'
    post:
      summary: Update onboarding settings
      description: Updates the onboarding configuration.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingSettingsRequest'
      responses:
        '200':
          description: Settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingSettings'
  /settings/onboarding/reset:
    post:
      summary: Reset onboarding content to defaults
      description: Resets all welcome content and tutorial steps to default values.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum: [welcome, tutorial]
                  description: Which content type to reset (both if not specified)
      responses:
        '200':
          description: Content reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  welcomeCount:
                    type: integer
                  tutorialCount:
                    type: integer
  /settings/onboarding/reset-all-users:
    post:
      summary: Reset onboarding for all users
      description: Resets onboarding progress for all users. Excludes users with admin or manage_users permissions.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: All users reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  count:
                    type: integer
                    description: Number of users reset
  /settings/onboarding/admin-complete:
    post:
      summary: Mark admin onboarding as completed
      description: Marks the admin onboarding as completed globally. Only shown once on first admin startup.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: Admin onboarding marked as completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '403':
          description: Forbidden - Admin permission required
  /settings/onboarding/welcome:
    get:
      summary: Get all welcome content
      description: Returns all welcome content items including disabled.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: List of welcome content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WelcomeContent'
    post:
      summary: Create welcome content
      description: Creates a new welcome content item.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WelcomeContentRequest'
      responses:
        '201':
          description: Content created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WelcomeContent'
  /settings/onboarding/welcome/{contentId}:
    put:
      summary: Update welcome content
      description: Updates an existing welcome content item.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: contentId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WelcomeContentRequest'
      responses:
        '200':
          description: Content updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WelcomeContent'
    delete:
      summary: Delete welcome content
      description: Deletes a welcome content item.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: contentId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Content deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /settings/onboarding/welcome/{id}/image:
    post:
      summary: Upload image for welcome content
      description: Uploads an image for a welcome content item.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
              required:
                - image
      responses:
        '200':
          description: Image uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
        '400':
          description: No file uploaded
        '404':
          description: Welcome content not found
  /settings/onboarding/welcome/reorder:
    post:
      summary: Reorder welcome content
      description: Updates the order of welcome content items.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReorderRequest'
      responses:
        '200':
          description: Content reordered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /settings/onboarding/tutorial:
    get:
      summary: Get all tutorial steps
      description: Returns all tutorial steps including disabled.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      responses:
        '200':
          description: List of tutorial steps
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TutorialStep'
    post:
      summary: Create tutorial step
      description: Creates a new tutorial step.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TutorialStepRequest'
      responses:
        '201':
          description: Step created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TutorialStep'
  /settings/onboarding/tutorial/{stepId}:
    put:
      summary: Update tutorial step
      description: Updates an existing tutorial step.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: stepId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TutorialStepRequest'
      responses:
        '200':
          description: Step updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TutorialStep'
    delete:
      summary: Delete tutorial step
      description: Deletes a tutorial step.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: stepId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Step deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /settings/onboarding/tutorial/{id}/image:
    post:
      summary: Upload image for tutorial step
      description: Uploads an image for a tutorial step.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
              required:
                - image
      responses:
        '200':
          description: Image uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
        '400':
          description: No file uploaded
        '404':
          description: Tutorial step not found
  /settings/onboarding/tutorial/reorder:
    post:
      summary: Reorder tutorial steps
      description: Updates the order of tutorial steps.
      tags:
        - settings
      security:
        - cookieAuth: []
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReorderRequest'
      responses:
        '200':
          description: Steps reordered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /user/{userId}/onboarding:
    get:
      summary: Get user onboarding data
      description: Returns full onboarding data for a user including status, settings, and content.
      tags:
        - users
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User onboarding data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserOnboardingData'
  /user/{userId}/onboarding/status:
    get:
      summary: Get user onboarding status
      description: Returns only the onboarding status for a user.
      tags:
        - users
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User onboarding status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserOnboardingStatus'
  /user/{userId}/onboarding/welcome/complete:
    post:
      summary: Mark welcome as completed
      description: Marks the welcome modal as completed for the user.
      tags:
        - users
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Welcome marked as completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /user/{userId}/onboarding/welcome/dismiss:
    post:
      summary: Dismiss welcome modal
      description: Marks the welcome modal as dismissed (skipped) for the user.
      tags:
        - users
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Welcome dismissed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /user/{userId}/onboarding/tutorial/complete:
    post:
      summary: Mark tutorial as completed
      description: Marks the tutorial as completed for the user.
      tags:
        - users
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Tutorial marked as completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /user/{userId}/onboarding/tutorial/skip:
    post:
      summary: Skip tutorial
      description: Marks the tutorial as skipped for the user.
      tags:
        - users
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Tutorial skipped
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /user/{userId}/onboarding/tutorial/progress:
    post:
      summary: Update tutorial progress
      description: Updates the tutorial progress by marking a step as completed.
      tags:
        - users
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - stepId
              properties:
                stepId:
                  type: integer
                  description: ID of the completed step
      responses:
        '200':
          description: Progress updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
  /user/{userId}/onboarding/reset:
    post:
      summary: Reset user onboarding
      description: Resets the onboarding progress for a user.
      tags:
        - users
      security:
        - cookieAuth: []
        - apiKey: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Onboarding reset
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean