openapi: 3.0.3
info:
  title: FablePool API
  version: 1.0.0
  description: |
    FablePool is a self-hosted music streaming server that mounts libraries
    directly from S3-compatible object stores and WebDAV servers, with
    Chromecast support, an Android client, and an AI autoplay/recommendation
    engine.

    This document is the API contract for milestone 1. It covers two surfaces:

    1. **REST v1** (`/api/v1/...`) — the first-party API used by the FablePool
       web UI, Android app, and Chromecast receiver. JSON only. Authenticated
       with JWT bearer tokens or long-lived API keys, plus short-lived signed
       *cast tokens* for media URLs handed to Chromecast devices (see
       `docs/05-auth-and-security.md` and `docs/06-chromecast.md`).

    2. **Subsonic-compatible** (`/rest/...`) — a compatibility surface
       implementing the widely supported Subsonic API (target version
       **1.16.1**) so existing Subsonic/Navidrome clients work unmodified.
       Endpoints are listed here without the legacy `.view` suffix; the server
       MUST also accept the same path with a trailing `.view`
       (e.g. `/rest/ping` and `/rest/ping.view` are equivalent). All Subsonic
       endpoints accept both `GET` and `POST` (form-encoded); only `GET` is
       modeled here.

    **Pagination** (REST): collection endpoints use `limit`/`offset` and return
    `{ items, total, limit, offset }` envelopes.

    **Errors** (REST): non-2xx responses carry the `Error` schema with a stable
    machine-readable `code`.

    **Range requests**: `/api/v1/stream/{trackId}` and `/rest/stream` fully
    support `Range`/`206 Partial Content`, backed by S3 ranged GETs or WebDAV
    partial GETs as described in `docs/03-storage-abstraction.md`.
  license:
    name: AGPL-3.0-or-later
    url: https://www.gnu.org/licenses/agpl-3.0.html
  contact:
    name: FablePool project
    url: https://example.org/fablepool

servers:
  - url: "{baseUrl}"
    description: FablePool server root (REST under /api/v1, Subsonic under /rest)
    variables:
      baseUrl:
        default: http://localhost:4533

tags:
  - name: auth
    description: Login, token refresh, API keys, current user.
  - name: users
    description: User administration (admin only).
  - name: sources
    description: S3 / WebDAV library source management and scanning (admin only).
  - name: library
    description: Browse artists, albums, tracks, genres; full-text search.
  - name: streaming
    description: Audio streaming, stream decision negotiation, cover art.
  - name: playlists
    description: Playlist CRUD and item management.
  - name: history
    description: Play history submission and retrieval.
  - name: reactions
    description: Like/dislike reactions on tracks.
  - name: recommendations
    description: Autoplay next-track recommendations and per-user autoplay settings.
  - name: cast
    description: Chromecast token minting and receiver configuration.
  - name: system
    description: Health, version, capabilities.
  - name: subsonic
    description: Subsonic 1.16.1 compatibility surface.

security:
  - bearerAuth: []
  - apiKeyAuth: []

paths:
  # ---------------------------------------------------------------------------
  # AUTH
  # ---------------------------------------------------------------------------
  /api/v1/auth/login:
    post:
      tags: [auth]
      operationId: login
      summary: Exchange username/password for a JWT token pair
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Authenticated; token pair issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenPair'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/v1/auth/refresh:
    post:
      tags: [auth]
      operationId: refreshToken
      summary: Rotate a refresh token for a new token pair
      description: |
        Refresh tokens are single-use and rotated on every call. Reuse of a
        consumed refresh token revokes the whole token family (see
        `docs/05-auth-and-security.md`).
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refreshToken]
              properties:
                refreshToken:
                  type: string
      responses:
        '200':
          description: New token pair.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenPair'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/auth/logout:
    post:
      tags: [auth]
      operationId: logout
      summary: Revoke the current refresh-token family
      responses:
        '204':
          description: Session revoked.
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/auth/me:
    get:
      tags: [auth]
      operationId: getCurrentUser
      summary: Get the authenticated user
      responses:
        '200':
          description: Current user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/auth/api-keys:
    get:
      tags: [auth]
      operationId: listApiKeys
      summary: List the caller's API keys
      responses:
        '200':
          description: API keys (secret material is never returned after creation).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags: [auth]
      operationId: createApiKey
      summary: Create an API key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  maxLength: 64
                expiresAt:
                  type: string
                  format: date-time
                  nullable: true
      responses:
        '201':
          description: |
            Key created. The plaintext `key` is returned exactly once and
            stored server-side only as a hash.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'

  /api/v1/auth/api-keys/{keyId}:
    delete:
      tags: [auth]
      operationId: deleteApiKey
      summary: Revoke an API key
      parameters:
        - $ref: '#/components/parameters/KeyId'
      responses:
        '204':
          description: Key revoked.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  # ---------------------------------------------------------------------------
  # USERS (admin)
  # ---------------------------------------------------------------------------
  /api/v1/users:
    get:
      tags: [users]
      operationId: listUsers
      summary: List users (admin)
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Users page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPage'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags: [users]
      operationId: createUser
      summary: Create a user (admin)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: User created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'

  /api/v1/users/{userId}:
    parameters:
      - $ref: '#/components/parameters/UserId'
    get:
      tags: [users]
      operationId: getUser
      summary: Get a user (admin, or self)
      responses:
        '200':
          description: User.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags: [users]
      operationId: updateUser
      summary: Update a user (admin, or self for non-privileged fields)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: Updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags: [users]
      operationId: deleteUser
      summary: Delete a user (admin)
      responses:
        '204':
          description: User deleted; their sessions and API keys are revoked.
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ---------------------------------------------------------------------------
  # SOURCES (S3 / WebDAV) + SCANNING (admin)
  # ---------------------------------------------------------------------------
  /api/v1/sources:
    get:
      tags: [sources]
      operationId: listSources
      summary: List configured library sources
      responses:
        '200':
          description: Sources (secrets redacted).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Source'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags: [sources]
      operationId: createSource
      summary: Add an S3 or WebDAV source
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceCreate'
      responses:
        '201':
          description: Source created (not yet scanned).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'

  /api/v1/sources/{sourceId}:
    parameters:
      - $ref: '#/components/parameters/SourceId'
    get:
      tags: [sources]
      operationId: getSource
      summary: Get a source
      responses:
        '200':
          description: Source.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags: [sources]
      operationId: updateSource
      summary: Update source configuration
      description: |
        Secret fields (`secretAccessKey`, `password`) are write-only; omit them
        to keep stored values, send a new value to rotate them.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceUpdate'
      responses:
        '200':
          description: Updated source.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags: [sources]
      operationId: deleteSource
      summary: Remove a source and all library entries derived from it
      responses:
        '204':
          description: Source removed.
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/sources/{sourceId}/test:
    post:
      tags: [sources]
      operationId: testSource
      summary: Test connectivity and credentials for a source
      description: |
        For S3: HEAD bucket + a single-page `ListObjectsV2` + one ranged GET on
        the first object found. For WebDAV: `OPTIONS` + `PROPFIND Depth: 1` on
        the root + one `Range` GET. Returns capability probes used by the
        stream decision engine (range support, presign support).
      parameters:
        - $ref: '#/components/parameters/SourceId'
      responses:
        '200':
          description: Probe results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceTestResult'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/sources/{sourceId}/scan:
    post:
      tags: [sources]
      operationId: startScan
      summary: Start (or queue) a scan of one source
      parameters:
        - $ref: '#/components/parameters/SourceId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum: [incremental, full]
                  default: incremental
                  description: >
                    `incremental` diffs by ETag/Last-Modified; `full` re-reads
                    all tags and re-derives audio features.
      responses:
        '202':
          description: Scan job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanJob'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: A scan for this source is already running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/sources/{sourceId}/scans:
    get:
      tags: [sources]
      operationId: listScans
      summary: List scan jobs for a source (most recent first)
      parameters:
        - $ref: '#/components/parameters/SourceId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Scan jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanJobPage'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # ---------------------------------------------------------------------------
  # LIBRARY BROWSE / SEARCH
  # ---------------------------------------------------------------------------
  /api/v1/artists:
    get:
      tags: [library]
      operationId: listArtists
      summary: List artists
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - name: sort
          in: query
          schema:
            type: string
            enum: [name, albumCount, recentlyAdded]
            default: name
        - name: startsWith
          in: query
          description: Filter by sort-name initial (A–Z, or "#" for non-alpha).
          schema:
            type: string
            maxLength: 1
      responses:
        '200':
          description: Artists page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtistPage'

  /api/v1/artists/{artistId}:
    get:
      tags: [library]
      operationId: getArtist
      summary: Get an artist
      parameters:
        - $ref: '#/components/parameters/ArtistId'
      responses:
        '200':
          description: Artist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artist'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/artists/{artistId}/albums:
    get:
      tags: [library]
      operationId: listArtistAlbums
      summary: List an artist's albums
      parameters:
        - $ref: '#/components/parameters/ArtistId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Albums page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlbumPage'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/albums:
    get:
      tags: [library]
      operationId: listAlbums
      summary: List albums
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - name: sort
          in: query
          schema:
            type: string
            enum: [name, artist, year, recentlyAdded, recentlyPlayed, mostPlayed, random]
            default: name
        - name: genre
          in: query
          schema:
            type: string
        - name: yearFrom
          in: query
          schema:
            type: integer
        - name: yearTo
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Albums page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlbumPage'

  /api/v1/albums/{albumId}:
    get:
      tags: [library]
      operationId: getAlbum
      summary: Get an album
      parameters:
        - $ref: '#/components/parameters/AlbumId'
      responses:
        '200':
          description: Album.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Album'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/albums/{albumId}/tracks:
    get:
      tags: [library]
      operationId: listAlbumTracks
      summary: List an album's tracks in disc/track order
      parameters:
        - $ref: '#/components/parameters/AlbumId'
      responses:
        '200':
          description: Tracks (whole album; not paginated).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Track'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/tracks/{trackId}:
    get:
      tags: [library]
      operationId: getTrack
      summary: Get a track
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '200':
          description: Track.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Track'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/genres:
    get:
      tags: [library]
      operationId: listGenres
      summary: List genres with counts
      responses:
        '200':
          description: Genres.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Genre'

  /api/v1/search:
    get:
      tags: [library]
      operationId: search
      summary: Full-text search over artists, albums and tracks
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: types
          in: query
          description: Comma-separated subset of `artist,album,track`. Default all.
          schema:
            type: string
            default: artist,album,track
        - name: limit
          in: query
          description: Per-type result limit.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Search results grouped by type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'

  # ---------------------------------------------------------------------------
  # STREAMING + ART
  # ---------------------------------------------------------------------------
  /api/v1/stream/{trackId}:
    get:
      tags: [streaming]
      operationId: streamTrack
      summary: Stream a track's audio
      description: |
        Serves the track per the same negotiation as `/decision`:

        * **proxy** — server pipes bytes from S3 (ranged `GetObject`) or
          WebDAV (`GET` with `Range`), honoring the client `Range` header and
          replying `206` with `Content-Range`.
        * **transcode** — server transcodes on the fly (see
          `docs/04-caching-and-transcoding.md`); `Range` is honored only for
          already-cached transcodes, otherwise the stream is chunked with
          `Accept-Ranges: none`.
        * **redirect** — `302` to a presigned S3 URL when
          `allowRedirect=true` and the source permits it.

        Authentication: bearer/API key as usual, or a `token` query parameter
        carrying a signed cast/stream token (for Chromecast and `<audio>`
        elements that cannot set headers).
      security:
        - bearerAuth: []
        - apiKeyAuth: []
        - castToken: []
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - name: maxBitRate
          in: query
          description: Max bitrate in kbit/s; 0 or absent means unlimited.
          schema:
            type: integer
            minimum: 0
        - name: format
          in: query
          description: Desired container/codec (`raw` forces no transcode).
          schema:
            type: string
            enum: [raw, mp3, opus, aac, flac]
        - name: allowRedirect
          in: query
          schema:
            type: boolean
            default: false
        - name: Range
          in: header
          required: false
          schema:
            type: string
            example: bytes=0-1048575
      responses:
        '200':
          description: Full audio stream.
          headers:
            Accept-Ranges:
              schema: {type: string}
            Content-Length:
              schema: {type: integer, format: int64}
            X-FablePool-Decision:
              description: The stream decision applied (proxy|transcode|redirect).
              schema: {type: string}
          content:
            audio/*:
              schema:
                type: string
                format: binary
        '206':
          description: Partial content for a `Range` request.
          headers:
            Content-Range:
              schema: {type: string, example: bytes 0-1048575/8388608}
            Accept-Ranges:
              schema: {type: string, example: bytes}
          content:
            audio/*:
              schema:
                type: string
                format: binary
        '302':
          description: Redirect to a presigned S3 URL.
          headers:
            Location:
              schema: {type: string, format: uri}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '416':
          description: Range not satisfiable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/stream/{trackId}/decision:
    get:
      tags: [streaming]
      operationId: getStreamDecision
      summary: Negotiate how a track will be delivered, without streaming it
      description: |
        Clients (especially the Chromecast sender and Android app) call this
        before playback to learn whether the track will be proxied, redirected
        to a presigned URL, or transcoded, and with which codec/bitrate. The
        decision algorithm is specified in `docs/04-caching-and-transcoding.md`.
      parameters:
        - $ref: '#/components/parameters/TrackId'
        - name: maxBitRate
          in: query
          schema:
            type: integer
            minimum: 0
        - name: codecs
          in: query
          description: Comma-separated codecs the client can play (e.g. `mp3,aac,opus,flac`).
          schema:
            type: string
        - name: allowRedirect
          in: query
          schema:
            type: boolean
            default: false
        - name: target
          in: query
          description: Playback target; `cast` constrains to Chromecast-supported media types.
          schema:
            type: string
            enum: [self, cast]
            default: self
      responses:
        '200':
          description: Stream decision.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamDecision'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/art/{artId}:
    get:
      tags: [streaming]
      operationId: getArt
      summary: Get cover art (resizable)
      security:
        - bearerAuth: []
        - apiKeyAuth: []
        - castToken: []
      parameters:
        - name: artId
          in: path
          required: true
          schema:
            type: string
        - name: size
          in: query
          description: Square size in px; server returns the nearest cached rendition (allowed - 64, 160, 300, 600, 1200).
          schema:
            type: integer
            minimum: 16
            maximum: 2048
      responses:
        '200':
          description: Image bytes (JPEG or WebP by `Accept` negotiation).
          headers:
            Cache-Control:
              schema: {type: string, example: "public, max-age=86400, immutable"}
            ETag:
              schema: {type: string}
          content:
            image/jpeg:
              schema: {type: string, format: binary}
            image/webp:
              schema: {type: string, format: binary}
        '304':
          description: Not modified (conditional request).
        '404':
          $ref: '#/components/responses/NotFound'

  # ---------------------------------------------------------------------------
  # PLAYLISTS
  # ---------------------------------------------------------------------------
  /api/v1/playlists:
    get:
      tags: [playlists]
      operationId: listPlaylists
      summary: List playlists visible to the caller (own + public)
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Playlists page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistPage'
    post:
      tags: [playlists]
      operationId: createPlaylist
      summary: Create a playlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaylistCreate'
      responses:
        '201':
          description: Playlist created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
        '422':
          $ref: '#/components/responses/ValidationError'

  /api/v1/playlists/{playlistId}:
    parameters:
      - $ref: '#/components/parameters/PlaylistId'
    get:
      tags: [playlists]
      operationId: getPlaylist
      summary: Get a playlist (metadata only)
      responses:
        '200':
          description: Playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags: [playlists]
      operationId: updatePlaylist
      summary: Update playlist metadata (owner only)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaylistUpdate'
      responses:
        '200':
          description: Updated playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [playlists]
      operationId: deletePlaylist
      summary: Delete a playlist (owner only)
      responses:
        '204':
          description: Playlist deleted.
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/playlists/{playlistId}/tracks:
    parameters:
      - $ref: '#/components/parameters/PlaylistId'
    get:
      tags: [playlists]
      operationId: listPlaylistTracks
      summary: List playlist entries in order
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Entries page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistEntryPage'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags: [playlists]
      operationId: addPlaylistTracks
      summary: Append or insert tracks (owner only)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [trackIds]
              properties:
                trackIds:
                  type: array
                  minItems: 1
                  maxItems: 500
                  items: {type: string, format: uuid}
                atPosition:
                  type: integer
                  minimum: 0
                  nullable: true
                  description: Insert position (0-based); null/absent appends.
      responses:
        '200':
          description: Updated playlist metadata (new counts).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags: [playlists]
      operationId: removePlaylistTracks
      summary: Remove entries by position (owner only)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [positions]
              properties:
                positions:
                  type: array
                  minItems: 1
                  items: {type: integer, minimum: 0}
                  description: 0-based positions to remove; remaining entries are compacted.
      responses:
        '200':
          description: Updated playlist metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/playlists/{playlistId}/tracks/move:
    post:
      tags: [playlists]
      operationId: movePlaylistTracks
      summary: Reorder a contiguous block of entries (owner only)
      parameters:
        - $ref: '#/components/parameters/PlaylistId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [from, to]
              properties:
                from: {type: integer, minimum: 0}
                count: {type: integer, minimum: 1, default: 1}
                to:
                  type: integer
                  minimum: 0
                  description: Target position evaluated after the block is lifted out.
      responses:
        '204':
          description: Reordered.
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'

  # ---------------------------------------------------------------------------
  # HISTORY
  # ---------------------------------------------------------------------------
  /api/v1/history/plays:
    post:
      tags: [history]
      operationId: recordPlay
      summary: Record a play event (scrobble)
      description: |
        Clients submit one event per playback attempt, ideally when playback
        ends or crosses the 50% / 4-minute "counts as played" threshold.
        Events feed the recommendation engine's last-N window
        (`docs/07-recommendation-engine.md`). Idempotent on
        (`userId`,`trackId`,`startedAt`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlayEventSubmit'
      responses:
        '201':
          description: Event stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayHistoryItem'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    get:
      tags: [history]
      operationId: listPlays
      summary: List the caller's play history (most recent first)
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - name: since
          in: query
          schema:
            type: string
            format: date-time
        - name: until
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: History page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayHistoryPage'

  /api/v1/history/recent-tracks:
    get:
      tags: [history]
      operationId: listRecentTracks
      summary: Distinct recently played tracks (deduplicated history)
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
      responses:
        '200':
          description: Tracks, most recently played first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Track'

  # ---------------------------------------------------------------------------
  # REACTIONS
  # ---------------------------------------------------------------------------
  /api/v1/tracks/{trackId}/reaction:
    put:
      tags: [reactions]
      operationId: setReaction
      summary: Set or clear the caller's reaction on a track
      parameters:
        - $ref: '#/components/parameters/TrackId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reaction]
              properties:
                reaction:
                  type: string
                  enum: [like, dislike, none]
      responses:
        '200':
          description: Track with updated reaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Track'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/reactions:
    get:
      tags: [reactions]
      operationId: listReactions
      summary: List the caller's reacted tracks
      parameters:
        - name: reaction
          in: query
          schema:
            type: string
            enum: [like, dislike]
            default: like
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Tracks page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackPage'

  # ---------------------------------------------------------------------------
  # RECOMMENDATIONS + AUTOPLAY SETTINGS
  # ---------------------------------------------------------------------------
  /api/v1/recommendations/next:
    post:
      tags: [recommendations]
      operationId: recommendNext
      summary: Get the next track(s) for autoplay
      description: |
        Scores candidates against the caller's last-N play window (N from
        autoplay settings, overridable per request), the seed track, reactions
        and audio/metadata features, per `docs/07-recommendation-engine.md`.
        Returns candidates with per-feature score breakdowns so clients can
        show "why this song".
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecommendNextRequest'
      responses:
        '200':
          description: Ranked candidates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendNextResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'

  /api/v1/recommendations/radio:
    get:
      tags: [recommendations]
      operationId: getRadio
      summary: Build an instant-mix queue from a seed
      parameters:
        - name: seedTrackId
          in: query
          schema: {type: string, format: uuid}
        - name: seedArtistId
          in: query
          schema: {type: string, format: uuid}
        - name: seedAlbumId
          in: query
          schema: {type: string, format: uuid}
        - name: count
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
      responses:
        '200':
          description: Mix queue (exactly one seed parameter must be supplied).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Track'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'

  /api/v1/me/autoplay-settings:
    get:
      tags: [recommendations]
      operationId: getAutoplaySettings
      summary: Get the caller's autoplay/recommendation settings
      responses:
        '200':
          description: Settings (defaults if never modified).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoplaySettings'
    put:
      tags: [recommendations]
      operationId: updateAutoplaySettings
      summary: Update the caller's autoplay/recommendation settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoplaySettings'
      responses:
        '200':
          description: Stored settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoplaySettings'
        '422':
          $ref: '#/components/responses/ValidationError'

  # ---------------------------------------------------------------------------
  # CAST
  # ---------------------------------------------------------------------------
  /api/v1/cast/token:
    post:
      tags: [cast]
      operationId: createCastToken
      summary: Mint a short-lived signed token for Chromecast media URLs
      description: |
        Sender apps call this before loading media on a receiver. The token is
        an HMAC-signed compact token scoped to specific track IDs (and their
        art) with a short TTL; the receiver appends it as `?token=` on
        `/api/v1/stream/...` and `/api/v1/art/...`. See `docs/06-chromecast.md`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [trackIds]
              properties:
                trackIds:
                  type: array
                  minItems: 1
                  maxItems: 200
                  items: {type: string, format: uuid}
                ttlSeconds:
                  type: integer
                  minimum: 60
                  maximum: 43200
                  default: 21600
      responses:
        '201':
          description: Cast token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CastToken'
        '422':
          $ref: '#/components/responses/ValidationError'

  /api/v1/cast/config:
    get:
      tags: [cast]
      operationId: getCastConfig
      summary: Get receiver app ID and cast capabilities
      responses:
        '200':
          description: Cast configuration for sender apps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CastConfig'

  # ---------------------------------------------------------------------------
  # SYSTEM
  # ---------------------------------------------------------------------------
  /api/v1/system/ping:
    get:
      tags: [system]
      operationId: ping
      summary: Liveness probe (no auth)
      security: []
      responses:
        '200':
          description: Server is alive.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: {type: string, example: ok}

  /api/v1/system/health:
    get:
      tags: [system]
      operationId: health
      summary: Readiness/health with component checks (admin)
      responses:
        '200':
          description: Healthy or degraded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        '503':
          description: Unhealthy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'

  /api/v1/system/info:
    get:
      tags: [system]
      operationId: systemInfo
      summary: Server version and capability flags
      security: []
      responses:
        '200':
          description: Server info.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemInfo'

  # ===========================================================================
  # SUBSONIC-COMPATIBLE SURFACE (target API version 1.16.1)
  # ===========================================================================
  /rest/ping:
    get:
      tags: [subsonic]
      operationId: subsonicPing
      summary: 'Subsonic: ping'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
      responses:
        '200':
          $ref: '#/components/responses/SubsonicOk'

  /rest/getLicense:
    get:
      tags: [subsonic]
      operationId: subsonicGetLicense
      summary: 'Subsonic: getLicense (always valid — FablePool is free software)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
      responses:
        '200':
          description: License envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicLicenseResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicLicenseResponse'

  /rest/getMusicFolders:
    get:
      tags: [subsonic]
      operationId: subsonicGetMusicFolders
      summary: 'Subsonic: getMusicFolders (one folder per FablePool source)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
      responses:
        '200':
          description: Music folders envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicMusicFoldersResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicMusicFoldersResponse'

  /rest/getIndexes:
    get:
      tags: [subsonic]
      operationId: subsonicGetIndexes
      summary: 'Subsonic: getIndexes (folder-style artist index)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: musicFolderId
          in: query
          schema: {type: string}
        - name: ifModifiedSince
          in: query
          schema: {type: integer, format: int64, description: Epoch millis.}
      responses:
        '200':
          description: Indexes envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicIndexesResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicIndexesResponse'

  /rest/getMusicDirectory:
    get:
      tags: [subsonic]
      operationId: subsonicGetMusicDirectory
      summary: 'Subsonic: getMusicDirectory (folder browse)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Directory envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicDirectoryResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicDirectoryResponse'

  /rest/getGenres:
    get:
      tags: [subsonic]
      operationId: subsonicGetGenres
      summary: 'Subsonic: getGenres'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
      responses:
        '200':
          description: Genres envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicGenresResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicGenresResponse'

  /rest/getArtists:
    get:
      tags: [subsonic]
      operationId: subsonicGetArtists
      summary: 'Subsonic: getArtists (ID3 artist index)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: musicFolderId
          in: query
          schema: {type: string}
      responses:
        '200':
          description: Artists envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicArtistsResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicArtistsResponse'

  /rest/getArtist:
    get:
      tags: [subsonic]
      operationId: subsonicGetArtist
      summary: 'Subsonic: getArtist (ID3 artist with albums)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Artist envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicArtistResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicArtistResponse'

  /rest/getAlbum:
    get:
      tags: [subsonic]
      operationId: subsonicGetAlbum
      summary: 'Subsonic: getAlbum (ID3 album with songs)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Album envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicAlbumResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicAlbumResponse'

  /rest/getSong:
    get:
      tags: [subsonic]
      operationId: subsonicGetSong
      summary: 'Subsonic: getSong'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Song envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicSongResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicSongResponse'

  /rest/getAlbumList2:
    get:
      tags: [subsonic]
      operationId: subsonicGetAlbumList2
      summary: 'Subsonic: getAlbumList2 (ID3 album lists)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: type
          in: query
          required: true
          schema:
            type: string
            enum: [random, newest, frequent, recent, starred, alphabeticalByName, alphabeticalByArtist, byYear, byGenre]
        - name: size
          in: query
          schema: {type: integer, minimum: 1, maximum: 500, default: 10}
        - name: offset
          in: query
          schema: {type: integer, minimum: 0, default: 0}
        - name: fromYear
          in: query
          schema: {type: integer}
        - name: toYear
          in: query
          schema: {type: integer}
        - name: genre
          in: query
          schema: {type: string}
        - name: musicFolderId
          in: query
          schema: {type: string}
      responses:
        '200':
          description: Album list envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicAlbumList2Response'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicAlbumList2Response'

  /rest/getRandomSongs:
    get:
      tags: [subsonic]
      operationId: subsonicGetRandomSongs
      summary: 'Subsonic: getRandomSongs'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: size
          in: query
          schema: {type: integer, minimum: 1, maximum: 500, default: 10}
        - name: genre
          in: query
          schema: {type: string}
        - name: fromYear
          in: query
          schema: {type: integer}
        - name: toYear
          in: query
          schema: {type: integer}
        - name: musicFolderId
          in: query
          schema: {type: string}
      responses:
        '200':
          description: Random songs envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicRandomSongsResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicRandomSongsResponse'

  /rest/getSongsByGenre:
    get:
      tags: [subsonic]
      operationId: subsonicGetSongsByGenre
      summary: 'Subsonic: getSongsByGenre'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: genre
          in: query
          required: true
          schema: {type: string}
        - name: count
          in: query
          schema: {type: integer, minimum: 1, maximum: 500, default: 10}
        - name: offset
          in: query
          schema: {type: integer, minimum: 0, default: 0}
        - name: musicFolderId
          in: query
          schema: {type: string}
      responses:
        '200':
          description: Songs-by-genre envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicSongsByGenreResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicSongsByGenreResponse'

  /rest/search3:
    get:
      tags: [subsonic]
      operationId: subsonicSearch3
      summary: 'Subsonic: search3 (ID3 search)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: query
          in: query
          required: true
          schema: {type: string}
        - name: artistCount
          in: query
          schema: {type: integer, default: 20}
        - name: artistOffset
          in: query
          schema: {type: integer, default: 0}
        - name: albumCount
          in: query
          schema: {type: integer, default: 20}
        - name: albumOffset
          in: query
          schema: {type: integer, default: 0}
        - name: songCount
          in: query
          schema: {type: integer, default: 20}
        - name: songOffset
          in: query
          schema: {type: integer, default: 0}
        - name: musicFolderId
          in: query
          schema: {type: string}
      responses:
        '200':
          description: Search result envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicSearch3Response'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicSearch3Response'

  /rest/getPlaylists:
    get:
      tags: [subsonic]
      operationId: subsonicGetPlaylists
      summary: 'Subsonic: getPlaylists'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
      responses:
        '200':
          description: Playlists envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicPlaylistsResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicPlaylistsResponse'

  /rest/getPlaylist:
    get:
      tags: [subsonic]
      operationId: subsonicGetPlaylist
      summary: 'Subsonic: getPlaylist (with entries)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Playlist envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicPlaylistResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicPlaylistResponse'

  /rest/createPlaylist:
    get:
      tags: [subsonic]
      operationId: subsonicCreatePlaylist
      summary: 'Subsonic: createPlaylist'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: name
          in: query
          schema: {type: string}
          description: Required when creating; omit with `playlistId` to overwrite entries.
        - name: playlistId
          in: query
          schema: {type: string}
        - name: songId
          in: query
          description: Repeatable.
          schema: {type: string}
          explode: true
      responses:
        '200':
          description: Created/updated playlist envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicPlaylistResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicPlaylistResponse'

  /rest/updatePlaylist:
    get:
      tags: [subsonic]
      operationId: subsonicUpdatePlaylist
      summary: 'Subsonic: updatePlaylist'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: playlistId
          in: query
          required: true
          schema: {type: string}
        - name: name
          in: query
          schema: {type: string}
        - name: comment
          in: query
          schema: {type: string}
        - name: public
          in: query
          schema: {type: boolean}
        - name: songIdToAdd
          in: query
          schema: {type: string}
          explode: true
        - name: songIndexToRemove
          in: query
          schema: {type: integer}
          explode: true
      responses:
        '200':
          $ref: '#/components/responses/SubsonicOk'

  /rest/deletePlaylist:
    get:
      tags: [subsonic]
      operationId: subsonicDeletePlaylist
      summary: 'Subsonic: deletePlaylist'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          required: true
          schema: {type: string}
      responses:
        '200':
          $ref: '#/components/responses/SubsonicOk'

  /rest/stream:
    get:
      tags: [subsonic]
      operationId: subsonicStream
      summary: 'Subsonic: stream (Range-capable; same decision engine as REST)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          required: true
          schema: {type: string}
        - name: maxBitRate
          in: query
          schema: {type: integer, minimum: 0}
        - name: format
          in: query
          schema:
            type: string
            enum: [raw, mp3, opus, aac, flac]
        - name: estimateContentLength
          in: query
          schema: {type: boolean, default: false}
        - name: Range
          in: header
          required: false
          schema: {type: string}
      responses:
        '200':
          description: Audio stream.
          content:
            audio/*:
              schema: {type: string, format: binary}
        '206':
          description: Partial content.
          headers:
            Content-Range:
              schema: {type: string}
          content:
            audio/*:
              schema: {type: string, format: binary}
        '404':
          description: Subsonic error envelope (code 70, data not found).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicErrorResponse'

  /rest/download:
    get:
      tags: [subsonic]
      operationId: subsonicDownload
      summary: 'Subsonic: download (original file, never transcoded)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Original bytes with `Content-Disposition: attachment`.
          content:
            application/octet-stream:
              schema: {type: string, format: binary}
        '404':
          description: Subsonic error envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicErrorResponse'

  /rest/getCoverArt:
    get:
      tags: [subsonic]
      operationId: subsonicGetCoverArt
      summary: 'Subsonic: getCoverArt'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          required: true
          schema: {type: string}
        - name: size
          in: query
          schema: {type: integer, minimum: 16, maximum: 2048}
      responses:
        '200':
          description: Image bytes.
          content:
            image/jpeg:
              schema: {type: string, format: binary}
            image/png:
              schema: {type: string, format: binary}
        '404':
          description: Subsonic error envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicErrorResponse'

  /rest/scrobble:
    get:
      tags: [subsonic]
      operationId: subsonicScrobble
      summary: 'Subsonic: scrobble (feeds the same play_history as REST)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          required: true
          schema: {type: string}
          explode: true
        - name: time
          in: query
          schema: {type: integer, format: int64, description: Epoch millis.}
          explode: true
        - name: submission
          in: query
          schema: {type: boolean, default: true, description: "false = now-playing only, not stored as a play."}
      responses:
        '200':
          $ref: '#/components/responses/SubsonicOk'

  /rest/star:
    get:
      tags: [subsonic]
      operationId: subsonicStar
      summary: 'Subsonic: star (maps to FablePool "like" reaction for songs)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          schema: {type: string}
          explode: true
        - name: albumId
          in: query
          schema: {type: string}
          explode: true
        - name: artistId
          in: query
          schema: {type: string}
          explode: true
      responses:
        '200':
          $ref: '#/components/responses/SubsonicOk'

  /rest/unstar:
    get:
      tags: [subsonic]
      operationId: subsonicUnstar
      summary: 'Subsonic: unstar'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: id
          in: query
          schema: {type: string}
          explode: true
        - name: albumId
          in: query
          schema: {type: string}
          explode: true
        - name: artistId
          in: query
          schema: {type: string}
          explode: true
      responses:
        '200':
          $ref: '#/components/responses/SubsonicOk'

  /rest/getStarred2:
    get:
      tags: [subsonic]
      operationId: subsonicGetStarred2
      summary: 'Subsonic: getStarred2 (ID3 starred items)'
      security: []
      parameters:
        - $ref: '#/components/parameters/SubU'
        - $ref: '#/components/parameters/SubT'
        - $ref: '#/components/parameters/SubS'
        - $ref: '#/components/parameters/SubV'
        - $ref: '#/components/parameters/SubC'
        - $ref: '#/components/parameters/SubF'
        - name: musicFolderId
          in: query
          schema: {type: string}
      responses:
        '200':
          description: Starred envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsonicStarred2Response'
            application/xml:
              schema:
                $ref: '#/components/schemas/SubsonicStarred2Response'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived access token from /api/v1/auth/login or /refresh.
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Long-lived API key (created via /api/v1/auth/api-keys).
    castToken:
      type: apiKey
      in: query
      name: token
      description: |
        Short-lived HMAC-signed token minted by POST /api/v1/cast/token,
        valid only for /api/v1/stream/* and /api/v1/art/* on the track IDs it
        was scoped to. Subsonic endpoints use their own query auth
        (u + t + s, salted MD5 per the Subsonic 1.13+ scheme) instead.

  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
    UserId:
      name: userId
      in: path
      required: true
      schema: {type: string, format: uuid}
    KeyId:
      name: keyId
      in: path
      required: true
      schema: {type: string, format: uuid}
    SourceId:
      name: sourceId
      in: path
      required: true
      schema: {type: string, format: uuid}
    ArtistId:
      name: artistId
      in: path
      required: true
      schema: {type: string, format: uuid}
    AlbumId:
      name: albumId
      in: path
      required: true
      schema: {type: string, format: uuid}
    TrackId:
      name: trackId
      in: path
      required: true
      schema: {type: string, format: uuid}
    PlaylistId:
      name: playlistId
      in: path
      required: true
      schema: {type: string, format: uuid}
    # ---- Subsonic common query params (1.13+ token auth) ----
    SubU:
      name: u
      in: query
      required: true
      description: Username.
      schema: {type: string}
    SubT:
      name: t
      in: query
      required: true
      description: md5(password + salt) hex token.
      schema: {type: string}
    SubS:
      name: s
      in: query
      required: true
      description: Random salt (>= 6 chars) used to compute `t`.
      schema: {type: string, minLength: 6}
    SubV:
      name: v
      in: query
      required: true
      description: Subsonic protocol version the client implements (e.g. 1.16.1).
      schema: {type: string}
    SubC:
      name: c
      in: query
      required: true
      description: Client identifier.
      schema: {type: string}
    SubF:
      name: f
      in: query
      required: false
      description: Response format.
      schema:
        type: string
        enum: [xml, json, jsonp]
        default: xml

  responses:
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Authenticated but not permitted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource does not exist or is not visible to the caller.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Resource conflict (e.g. duplicate username).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Request body or parameters failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many attempts; retry later.
      headers:
        Retry-After:
          schema: {type: integer}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    SubsonicOk:
      description: Empty-ok Subsonic envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubsonicOkResponse'
        application/xml:
          schema:
            $ref: '#/components/schemas/SubsonicOkResponse'

  schemas:
    # =========================================================================
    # COMMON
    # =========================================================================
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Stable machine-readable code (e.g. `auth.invalid_credentials`, `library.track_not_found`, `validation.failed`).
          example: validation.failed
        message:
          type: string
        details:
          type: object
          additionalProperties: true
          nullable: true

    # =========================================================================
    # AUTH / USERS
    # =========================================================================
    LoginRequest:
      type: object
      required: [username, password]
      properties:
        username: {type: string}
        password: {type: string, format: password}
        clientName:
          type: string
          description: Free-form device/client label shown in session listings.
          maxLength: 64

    TokenPair:
      type: object
      required: [accessToken, refreshToken, expiresIn, tokenType]
      properties:
        accessToken: {type: string}
        refreshToken: {type: string}
        expiresIn:
          type: integer
          description: Access-token lifetime in seconds.
          example: 900
        tokenType:
          type: string
          enum: [Bearer]
        user:
          $ref: '#/components/schemas/User'

    User:
      type: object
      required: [id, username, isAdmin, createdAt]
      properties:
        id: {type: string, format: uuid}
        username: {type: string}
        email: {type: string, format: email, nullable: true}
        displayName: {type: string, nullable: true}
        isAdmin: {type: boolean}
        createdAt: {type: string, format: date-time}
        lastLoginAt: {type: string, format: date-time, nullable: true}

    UserCreate:
      type: object
      required: [username, password]
      properties:
        username:
          type: string
          minLength: 2
          maxLength: 64
          pattern: '^[a-zA-Z0-9._-]+$'
        password: {type: string, format: password, minLength: 8}
        email: {type: string, format: email, nullable: true}
        displayName: {type: string, nullable: true}
        isAdmin: {type: boolean, default: false}

    UserUpdate:
      type: object
      properties:
        password: {type: string, format: password, minLength: 8}
        email: {type: string, format: email, nullable: true}
        displayName: {type: string, nullable: true}
        isAdmin:
          type: boolean
          description: Admin-only field.

    UserPage:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/User'}
        total: {type: integer}
        limit: {type: integer}
        offset: {type: integer}

    ApiKey:
      type: object
      required: [id, name, prefix, createdAt]
      properties:
        id: {type: string, format: uuid}
        name: {type: string}
        prefix:
          type: string
          description: First 8 chars of the key, for identification.
        createdAt: {type: string, format: date-time}
        lastUsedAt: {type: string, format: date-time, nullable: true}
        expiresAt: {type: string, format: date-time, nullable: true}

    ApiKeyCreated:
      allOf:
        - $ref: '#/components/schemas/ApiKey'
        - type: object
          required: [key]
          properties:
            key:
              type: string
              description: Full plaintext key; shown only in this response.

    # =========================================================================
    # SOURCES / SCANNING
    # =========================================================================
    S3SourceConfig:
      type: object
      required: [bucket]
      properties:
        endpoint:
          type: string
          format: uri
          nullable: true
          description: Custom endpoint for MinIO/B2/R2 etc.; null = AWS.
        region: {type: string, nullable: true, example: us-east-1}
        bucket: {type: string}
        prefix:
          type: string
          default: ""
          description: Key prefix that roots the library inside the bucket.
        accessKeyId: {type: string, nullable: true}
        secretAccessKey:
          type: string
          format: password
          writeOnly: true
          nullable: true
        forcePathStyle: {type: boolean, default: false}
        usePresignedUrls:
          type: boolean
          default: false
          description: Allow `redirect` stream decisions via presigned GETs.
        presignExpirySeconds:
          type: integer
          minimum: 60
          maximum: 604800
          default: 3600

    WebDavSourceConfig:
      type: object
      required: [baseUrl]
      properties:
        baseUrl: {type: string, format: uri}
        username: {type: string, nullable: true}
        password:
          type: string
          format: password
          writeOnly: true
          nullable: true
        trustSelfSigned: {type: boolean, default: false}
        depth1Traversal:
          type: boolean
          default: true
          description: >
            Traverse with repeated `PROPFIND Depth: 1` (safe everywhere)
            instead of `Depth: infinity` (faster but often disabled by servers).

    Source:
      type: object
      required: [id, name, type, enabled, createdAt]
      properties:
        id: {type: string, format: uuid}
        name: {type: string}
        type:
          type: string
          enum: [s3, webdav]
        enabled: {type: boolean}
        config:
          oneOf:
            - $ref: '#/components/schemas/S3SourceConfig'
            - $ref: '#/components/schemas/WebDavSourceConfig'
          description: Shape depends on `type`; secrets are redacted on read.
        status:
          type: string
          enum: [unscanned, scanning, ready, error]
        lastScanAt: {type: string, format: date-time, nullable: true}
        trackCount: {type: integer}
        createdAt: {type: string, format: date-time}

    SourceCreate:
      type: object
      required: [name, type, config]
      properties:
        name: {type: string, maxLength: 64}
        type:
          type: string
          enum: [s3, webdav]
        enabled: {type: boolean, default: true}
        config:
          oneOf:
            - $ref: '#/components/schemas/S3SourceConfig'
            - $ref: '#/components/schemas/WebDavSourceConfig'

    SourceUpdate:
      type: object
      properties:
        name: {type: string, maxLength: 64}
        enabled: {type: boolean}
        config:
          oneOf:
            - $ref: '#/components/schemas/S3SourceConfig'
            - $ref: '#/components/schemas/WebDavSourceConfig'

    SourceTestResult:
      type: object
      required: [ok]
      properties:
        ok: {type: boolean}
        latencyMs: {type: integer, nullable: true}
        supportsRange:
          type: boolean
          description: Backend honored a `Range`/ranged-GET probe.
        supportsPresign:
          type: boolean
          description: S3 only; presigned GET succeeded.
        objectCountSampled: {type: integer, nullable: true}
        error: {type: string, nullable: true}

    ScanJob:
      type: object
      required: [id, sourceId, state, mode]
      properties:
        id: {type: string, format: uuid}
        sourceId: {type: string, format: uuid}
        mode:
          type: string
          enum: [incremental, full]
        state:
          type: string
          enum: [queued, running, completed, failed, cancelled]
        startedAt: {type: string, format: date-time, nullable: true}
        finishedAt: {type: string, format: date-time, nullable: true}
        stats:
          type: object
          properties:
            filesSeen: {type: integer}
            tracksAdded: {type: integer}
            tracksUpdated: {type: integer}
            tracksRemoved: {type: integer}
            errors: {type: integer}
        error: {type: string, nullable: true}

    ScanJobPage:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/ScanJob'}
        total: {type: integer}
        limit: {type: integer}
        offset: {type: integer}

    # =========================================================================
    # LIBRARY
    # =========================================================================
    Artist:
      type: object
      required: [id, name]
      properties:
        id: {type: string, format: uuid}
        name: {type: string}
        sortName: {type: string, nullable: true}
        albumCount: {type: integer}
        trackCount: {type: integer}
        artId: {type: string, nullable: true}

    Album:
      type: object
      required: [id, name]
      properties:
        id: {type: string, format: uuid}
        name: {type: string}
        artistId: {type: string, format: uuid, nullable: true}
        artistName: {type: string, nullable: true}
        year: {type: integer, nullable: true}
        genre: {type: string, nullable: true}
        trackCount: {type: integer}
        durationSec: {type: integer}
        artId: {type: string, nullable: true}
        createdAt: {type: string, format: date-time}

    Track:
      type: object
      required: [id, title, durationSec, sourceId]
      properties:
        id: {type: string, format: uuid}
        title: {type: string}
        albumId: {type: string, format: uuid, nullable: true}
        albumName: {type: string, nullable: true}
        artistId: {type: string, format: uuid, nullable: true}
        artistName: {type: string, nullable: true}
        trackNumber: {type: integer, nullable: true}
        discNumber: {type: integer, nullable: true}
        durationSec: {type: integer}
        genre: {type: string, nullable: true}
        year: {type: integer, nullable: true}
        container: {type: string, nullable: true, example: flac}
        codec: {type: string, nullable: true, example: flac}
        bitrateKbps: {type: integer, nullable: true}
        sampleRateHz: {type: integer, nullable: true}
        channels: {type: integer, nullable: true}
        sizeBytes: {type: integer, format: int64, nullable: true}
        sourceId: {type: string, format: uuid}
        path:
          type: string
          description: Object key (S3) or href path (WebDAV) within the source. Admin callers only; redacted otherwise.
          nullable: true
        artId: {type: string, nullable: true}
        reaction:
          type: string
          enum: [like, dislike]
          nullable: true
          description: Caller's reaction, if any.
        playCount: {type: integer}
        lastPlayedAt: {type: string, format: date-time, nullable: true}

    Genre:
      type: object
      required: [name]
      properties:
        name: {type: string}
        trackCount: {type: integer}
        albumCount: {type: integer}

    ArtistPage:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/Artist'}
        total: {type: integer}
        limit: {type: integer}
        offset: {type: integer}

    AlbumPage:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/Album'}
        total: {type: integer}
        limit: {type: integer}
        offset: {type: integer}

    TrackPage:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/Track'}
        total: {type: integer}
        limit: {type: integer}
        offset: {type: integer}

    SearchResults:
      type: object
      required: [query]
      properties:
        query: {type: string}
        artists:
          type: array
          items: {$ref: '#/components/schemas/Artist'}
        albums:
          type: array
          items: {$ref: '#/components/schemas/Album'}
        tracks:
          type: array
          items: {$ref: '#/components/schemas/Track'}

    # =========================================================================
    # STREAMING
    # =========================================================================
    StreamDecision:
      type: object
      required: [trackId, decision, container, codec, supportsRange]
      properties:
        trackId: {type: string, format: uuid}
        decision:
          type: string
          enum: [proxy, redirect, transcode]
        url:
          type: string
          format: uri
          nullable: true
          description: Present for `redirect` (presigned S3 URL) — fetch directly, no auth header.
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: Presigned-URL expiry for `redirect` decisions.
        container: {type: string, example: mp3}
        codec: {type: string, example: mp3}
        bitrateKbps: {type: integer, nullable: true}
        estimatedSizeBytes:
          type: integer
          format: int64
          nullable: true
          description: Exact for proxy/redirect; estimated for transcode.
        supportsRange: {type: boolean}
        reason:
          type: string
          description: Human-readable explanation of the decision.
          example: "client cannot play flac; transcoding to opus@160 per server policy"

    # =========================================================================
    # PLAYLISTS
    # =========================================================================
    Playlist:
      type: object
      required: [id, name, ownerId, isPublic, trackCount, createdAt, updatedAt]
      properties:
        id: {type: string, format: uuid}
        name: {type: string}
        description: {type: string, nullable: true}
        ownerId: {type: string, format: uuid}
        ownerName: {type: string, nullable: true}
        isPublic: {type: boolean}
        trackCount: {type: integer}
        durationSec: {type: integer}
        artId:
          type: string
          nullable: true
          description: Derived from first track's album art.
        createdAt: {type: string, format: date-time}
        updatedAt: {type: string, format: date-time}

    PlaylistCreate:
      type: object
      required: [name]
      properties:
        name: {type: string, minLength: 1, maxLength: 128}
        description: {type: string, maxLength: 1024, nullable: true}
        isPublic: {type: boolean, default: false}
        trackIds:
          type: array
          items: {type: string, format: uuid}
          description: Optional initial entries, in order.

    PlaylistUpdate:
      type: object
      properties:
        name: {type: string, minLength: 1, maxLength: 128}
        description: {type: string, maxLength: 1024, nullable: true}
        isPublic: {type: boolean}

    PlaylistEntry:
      type: object
      required: [position, addedAt, track]
      properties:
        position: {type: integer, minimum: 0}
        addedAt: {type: string, format: date-time}
        track: {$ref: '#/components/schemas/Track'}

    PlaylistEntryPage:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/PlaylistEntry'}
        total: {type: integer}
        limit: {type: integer}
        offset: {type: integer}

    PlaylistPage:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/Playlist'}
        total: {type: integer}
        limit: {type: integer}
        offset: {type: integer}

    # =========================================================================
    # HISTORY
    # =========================================================================
    PlayEventSubmit:
      type: object
      required: [trackId, startedAt]
      properties:
        trackId: {type: string, format: uuid}
        startedAt: {type: string, format: date-time}
        playedMs:
          type: integer
          minimum: 0
          description: Milliseconds actually heard (sum across seeks).
        completed:
          type: boolean
          default: false
          description: Track reached its natural end.
        context:
          type: string
          enum: [queue, album, playlist, radio, autoplay, search, cast, subsonic]
          default: queue
        client:
          type: string
          maxLength: 64
          nullable: true

    PlayHistoryItem:
      type: object
      required: [id, track, startedAt]
      properties:
        id: {type: string, format: uuid}
        track: {$ref: '#/components/schemas/Track'}
        startedAt: {type: string, format: date-time}
        playedMs: {type: integer, nullable: true}
        completed: {type: boolean}
        context: {type: string}
        client: {type: string, nullable: true}

    PlayHistoryPage:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/PlayHistoryItem'}
        total: {type: integer}
        limit: {type: integer}
        offset: {type: integer}

    # =========================================================================
    # RECOMMENDATIONS / AUTOPLAY
    # =========================================================================
    AutoplaySettings:
      type: object
      properties:
        enabled:
          type: boolean
          default: true
        windowSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: The user-configurable "last N played songs" window.
        recencyHalfLife:
          type: integer
          minimum: 1
          maximum: 100
          default: 5
          description: >
            Half-life (in window positions) for exponential decay of older
            plays' influence; position 0 is the most recent track.
        explorationFactor:
          type: number
          format: float
          minimum: 0
          maximum: 1
          default: 0.15
          description: Probability mass given to lower-ranked candidates to avoid loops.
        avoidRepeatMinutes:
          type: integer
          minimum: 0
          maximum: 1440
          default: 120
          description: Exclude tracks played within this many minutes (0 disables).
        dislikePenalty:
          type: number
          format: float
          minimum: 0
          maximum: 1
          default: 1.0
          description: 1.0 = disliked tracks fully excluded; lower values only down-rank.
        weights:
          type: object
          description: >
            Relative feature weights, normalized server-side. See
            docs/07-recommendation-engine.md for feature definitions.
          properties:
            genre: {type: number, format: float, minimum: 0, default: 1.0}
            artistSimilarity: {type: number, format: float, minimum: 0, default: 1.0}
            audioFeatures:
              type: number
              format: float
              minimum: 0
              default: 1.0
              description: Tempo/energy/loudness/spectral profile distance.
            popularity: {type: number, format: float, minimum: 0, default: 0.5}
            novelty:
              type: number
              format: float
              minimum: 0
              default: 0.5
              description: Boost for tracks the user has rarely/never heard.

    RecommendNextRequest:
      type: object
      required: [currentTrackId]
      properties:
        currentTrackId: {type: string, format: uuid}
        count:
          type: integer
          minimum: 1
          maximum: 25
          default: 1
        windowSizeOverride:
          type: integer
          minimum: 1
          maximum: 100
          nullable: true
          description: One-off override of the user's configured window size.
        excludeTrackIds:
          type: array
          maxItems: 200
          items: {type: string, format: uuid}
          description: Client-side queue contents to never recommend again this session.
        sessionId:
          type: string
          nullable: true
          description: Opaque autoplay-session ID; lets the server diversify across a session.

    FeatureContribution:
      type: object
      required: [feature, weight, contribution]
      properties:
        feature:
          type: string
          example: genre
        weight: {type: number, format: float}
        contribution:
          type: number
          format: float
          description: Weighted contribution to the final score.

    RecommendationCandidate:
      type: object
      required: [track, score]
      properties:
        track: {$ref: '#/components/schemas/Track'}
        score:
          type: number
          format: float
          description: Final normalized score in [0, 1].
        breakdown:
          type: array
          items: {$ref: '#/components/schemas/FeatureContribution'}

    RecommendNextResponse:
      type: object
      required: [candidates, windowTrackIds]
      properties:
        candidates:
          type: array
          items: {$ref: '#/components/schemas/RecommendationCandidate'}
        windowTrackIds:
          type: array
          items: {type: string, format: uuid}
          description: The exact last-N window the scorer used (most recent first).
        settingsApplied:
          $ref: '#/components/schemas/AutoplaySettings'

    # =========================================================================
    # CAST
    # =========================================================================
    CastToken:
      type: object
      required: [token, expiresAt]
      properties:
        token: {type: string}
        expiresAt: {type: string, format: date-time}
        streamBaseUrl:
          type: string
          format: uri
          description: Externally reachable base URL the receiver should use for /api/v1/stream and /api/v1/art.

    CastConfig:
      type: object
      required: [receiverAppId]
      properties:
        receiverAppId:
          type: string
          description: Google Cast receiver application ID registered for FablePool (or a self-hosted custom receiver).
        customReceiverUrl:
          type: string
          format: uri
          nullable: true
        supportedCodecs:
          type: array
          items: {type: string}
          example: [mp3, aac, opus, flac]
        maxCastBitrateKbps:
          type: integer
          description: Server policy cap applied to `target=cast` stream decisions.

    # =========================================================================
    # SYSTEM
    # =========================================================================
    Health:
      type: object
      required: [status, checks]
      properties:
        status:
          type: string
          enum: [ok, degraded, unhealthy]
        checks:
          type: object
          additionalProperties:
            type: object
            properties:
              status:
                type: string
                enum: [ok, degraded, unhealthy]
              detail: {type: string, nullable: true}
              latencyMs: {type: integer, nullable: true}
          example:
            database: {status: ok, latencyMs: 2}
            cache: {status: ok, latencyMs: 1}
            sources: {status: degraded, detail: "1 of 2 sources unreachable"}

    SystemInfo:
      type: object
      required: [serverName, version, apiVersion, subsonicApiVersion]
      properties:
        serverName: {type: string, example: FablePool}
        version: {type: string, example: 1.0.0}
        apiVersion: {type: string, example: v1}
        subsonicApiVersion: {type: string, example: 1.16.1}
        features:
          type: array
          items: {type: string}
          example: [transcoding, presigned-redirect, chromecast, recommendations]

    # =========================================================================
    # SUBSONIC SCHEMAS
    # =========================================================================
    SubsonicBase:
      type: object
      required: [status, version, type]
      properties:
        status:
          type: string
          enum: [ok, failed]
        version:
          type: string
          example: 1.16.1
        type:
          type: string
          example: fablepool
        serverVersion:
          type: string
          example: 1.0.0
        openSubsonic:
          type: boolean
          description: True; FablePool reports OpenSubsonic-style extension fields.
        error:
          $ref: '#/components/schemas/SubsonicError'

    SubsonicError:
      type: object
      required: [code, message]
      properties:
        code:
          type: integer
          description: |
            Standard Subsonic codes: 0 generic, 10 missing parameter,
            20 client must upgrade, 30 server must upgrade, 40 wrong
            username/password, 41 token auth not supported for LDAP-style
            users, 50 not authorized, 60 trial expired (never returned),
            70 data not found.
        message: {type: string}

    SubsonicOkResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          $ref: '#/components/schemas/SubsonicBase'

    SubsonicErrorResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
          description: status=failed with `error` populated.

    SubsonicLicenseResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                license:
                  type: object
                  properties:
                    valid: {type: boolean, example: true}
                    email: {type: string, nullable: true}
                    licenseExpires: {type: string, format: date-time, nullable: true}

    SubsonicMusicFolder:
      type: object
      required: [id, name]
      properties:
        id: {type: string}
        name: {type: string}

    SubsonicMusicFoldersResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                musicFolders:
                  type: object
                  properties:
                    musicFolder:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicMusicFolder'}

    SubsonicChild:
      type: object
      description: A song or directory entry (Subsonic "Child").
      required: [id, isDir, title]
      properties:
        id: {type: string}
        parent: {type: string, nullable: true}
        isDir: {type: boolean}
        title: {type: string}
        album: {type: string, nullable: true}
        artist: {type: string, nullable: true}
        track: {type: integer, nullable: true}
        discNumber: {type: integer, nullable: true}
        year: {type: integer, nullable: true}
        genre: {type: string, nullable: true}
        coverArt: {type: string, nullable: true}
        size: {type: integer, format: int64, nullable: true}
        contentType: {type: string, nullable: true}
        suffix: {type: string, nullable: true}
        transcodedContentType: {type: string, nullable: true}
        transcodedSuffix: {type: string, nullable: true}
        duration: {type: integer, nullable: true}
        bitRate: {type: integer, nullable: true}
        path: {type: string, nullable: true}
        playCount: {type: integer, nullable: true}
        created: {type: string, format: date-time, nullable: true}
        starred: {type: string, format: date-time, nullable: true}
        albumId: {type: string, nullable: true}
        artistId: {type: string, nullable: true}
        type: {type: string, example: music}

    SubsonicArtistID3:
      type: object
      required: [id, name]
      properties:
        id: {type: string}
        name: {type: string}
        coverArt: {type: string, nullable: true}
        albumCount: {type: integer}
        starred: {type: string, format: date-time, nullable: true}

    SubsonicAlbumID3:
      type: object
      required: [id, name, songCount, duration, created]
      properties:
        id: {type: string}
        name: {type: string}
        artist: {type: string, nullable: true}
        artistId: {type: string, nullable: true}
        coverArt: {type: string, nullable: true}
        songCount: {type: integer}
        duration: {type: integer}
        playCount: {type: integer, nullable: true}
        created: {type: string, format: date-time}
        starred: {type: string, format: date-time, nullable: true}
        year: {type: integer, nullable: true}
        genre: {type: string, nullable: true}

    SubsonicIndexEntry:
      type: object
      required: [name, artist]
      properties:
        name:
          type: string
          description: Index letter (A, B, ..., '#').
        artist:
          type: array
          items:
            type: object
            required: [id, name]
            properties:
              id: {type: string}
              name: {type: string}

    SubsonicIndexesResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                indexes:
                  type: object
                  properties:
                    lastModified: {type: integer, format: int64}
                    ignoredArticles: {type: string, example: "The El La Los Las Le Les"}
                    index:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicIndexEntry'}

    SubsonicDirectoryResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                directory:
                  type: object
                  required: [id, name]
                  properties:
                    id: {type: string}
                    parent: {type: string, nullable: true}
                    name: {type: string}
                    starred: {type: string, format: date-time, nullable: true}
                    child:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicChild'}

    SubsonicGenresResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                genres:
                  type: object
                  properties:
                    genre:
                      type: array
                      items:
                        type: object
                        properties:
                          value: {type: string}
                          songCount: {type: integer}
                          albumCount: {type: integer}

    SubsonicArtistsIndexEntry:
      type: object
      required: [name, artist]
      properties:
        name: {type: string}
        artist:
          type: array
          items: {$ref: '#/components/schemas/SubsonicArtistID3'}

    SubsonicArtistsResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                artists:
                  type: object
                  properties:
                    ignoredArticles: {type: string}
                    index:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicArtistsIndexEntry'}

    SubsonicArtistResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                artist:
                  allOf:
                    - $ref: '#/components/schemas/SubsonicArtistID3'
                    - type: object
                      properties:
                        album:
                          type: array
                          items: {$ref: '#/components/schemas/SubsonicAlbumID3'}

    SubsonicAlbumResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                album:
                  allOf:
                    - $ref: '#/components/schemas/SubsonicAlbumID3'
                    - type: object
                      properties:
                        song:
                          type: array
                          items: {$ref: '#/components/schemas/SubsonicChild'}

    SubsonicSongResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                song:
                  $ref: '#/components/schemas/SubsonicChild'

    SubsonicAlbumList2Response:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                albumList2:
                  type: object
                  properties:
                    album:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicAlbumID3'}

    SubsonicRandomSongsResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                randomSongs:
                  type: object
                  properties:
                    song:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicChild'}

    SubsonicSongsByGenreResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                songsByGenre:
                  type: object
                  properties:
                    song:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicChild'}

    SubsonicSearch3Response:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                searchResult3:
                  type: object
                  properties:
                    artist:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicArtistID3'}
                    album:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicAlbumID3'}
                    song:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicChild'}

    SubsonicPlaylistSummary:
      type: object
      required: [id, name, songCount, duration, owner, public, created, changed]
      properties:
        id: {type: string}
        name: {type: string}
        comment: {type: string, nullable: true}
        owner: {type: string}
        public: {type: boolean}
        songCount: {type: integer}
        duration: {type: integer}
        created: {type: string, format: date-time}
        changed: {type: string, format: date-time}
        coverArt: {type: string, nullable: true}

    SubsonicPlaylistsResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                playlists:
                  type: object
                  properties:
                    playlist:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicPlaylistSummary'}

    SubsonicPlaylistResponse:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                playlist:
                  allOf:
                    - $ref: '#/components/schemas/SubsonicPlaylistSummary'
                    - type: object
                      properties:
                        entry:
                          type: array
                          items: {$ref: '#/components/schemas/SubsonicChild'}

    SubsonicStarred2Response:
      type: object
      required: [subsonic-response]
      properties:
        subsonic-response:
          allOf:
            - $ref: '#/components/schemas/SubsonicBase'
            - type: object
              properties:
                starred2:
                  type: object
                  properties:
                    artist:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicArtistID3'}
                    album:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicAlbumID3'}
                    song:
                      type: array
                      items: {$ref: '#/components/schemas/SubsonicChild'}