openapi.yml

openapi: 3.1.0
info:
  title: Tunecamp REST API
  version: 2.0.0
  description: |
    The Tunecamp API provides programmatic access to the platform's music library, artists, albums, tracks,
    releases, playlists, and administrative functions. It supports the decentralized music ecosystem via
    ActivityPub federation and HTTP gossip instance discovery.

    ## Authentication
    Public endpoints (catalog browsing, streaming) require no authentication.
    User endpoints require a Bearer token from `/api/auth/login`.
    Admin endpoints require a Bearer token with an admin role.

    ## Subsonic API
    For Subsonic/OpenSubsonic client compatibility, use the `/rest` endpoint.
    See [SUBSONIC.md](./SUBSONIC.md) for the full endpoint reference.

servers:
  - url: /api
    description: Tunecamp API base path

paths:
  # ── Authentication ──────────────────────────────────────────────────────────
  /auth/login:
    post:
      summary: User Login
      tags: [Authentication]
      description: |
        Authenticates a user with username and password.
        The response includes a `mustChangePassword` flag when the account still uses the default password.
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Successful authentication. Returns JWT and user info.
        '401':
          description: Invalid username or password.

  /auth/status:
    get:
      summary: Get Current User
      tags: [Authentication]
      description: Returns the current session and the authenticated user's profile.
      operationId: getCurrentUser
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Current user info.
        '401':
          description: Not authenticated.

  # ── Users ───────────────────────────────────────────────────────────────────
  /users/register:
    post:
      summary: User Registration
      tags: [Users]
      description: Registers a new user account (username and password). Can be disabled via the `allowRegistration` setting.
      operationId: register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Registration successful.
        '409':
          description: Username already taken.

  # ── Catalog (Public) ────────────────────────────────────────────────────────
  /catalog:
    get:
      summary: Get Full Catalog
      tags: [Catalog]
      description: Returns the complete public catalog with site metadata, artists, albums, and tracks.
      operationId: getCatalog
      responses:
        '200':
          description: The full catalog.

  # ── Artists ─────────────────────────────────────────────────────────────────
  /artists:
    get:
      summary: List Artists
      tags: [Artists]
      description: Retrieves all public artists.
      operationId: getArtists
      responses:
        '200':
          description: A list of artists.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Artist'

  /artists/{slug}:
    get:
      summary: Get Artist Details
      tags: [Artists]
      description: Retrieves detailed information for a specific artist by slug or ID.
      operationId: getArtistBySlug
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The artist details with albums and tracks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artist'
        '404':
          description: Artist not found.

  /artists/{slug}/cover:
    get:
      summary: Get Artist Cover Image
      tags: [Artists]
      description: Returns the artist's profile photo/avatar.
      operationId: getArtistCover
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Image file.

  # ── Albums ──────────────────────────────────────────────────────────────────
  /albums:
    get:
      summary: List Albums
      tags: [Albums]
      description: Retrieves all public albums.
      operationId: getAlbums
      responses:
        '200':
          description: A list of albums.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Album'

  /albums/{idOrSlug}:
    get:
      summary: Get Album Details
      tags: [Albums]
      description: Retrieves album details with track listing by ID or slug.
      operationId: getAlbum
      parameters:
        - name: idOrSlug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Album with tracks.
        '404':
          description: Album not found.

  /albums/{id}/cover:
    get:
      summary: Get Album Cover Art
      tags: [Albums]
      description: Returns the album's cover art image.
      operationId: getAlbumCover
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Image file.

  # ── Tracks ──────────────────────────────────────────────────────────────────
  /tracks:
    get:
      summary: List Tracks
      tags: [Tracks]
      description: Retrieves all public tracks. Supports filtering by album.
      operationId: getTracks
      parameters:
        - name: albumId
          in: query
          schema:
            type: integer
          description: Filter tracks by album ID.
      responses:
        '200':
          description: A list of tracks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Track'

  /tracks/{id}:
    get:
      summary: Get Track Details
      tags: [Tracks]
      description: Get a single track by ID.
      operationId: getTrack
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Track details.
        '404':
          description: Track not found.
    put:
      summary: Update Track
      tags: [Tracks]
      description: Update track metadata (requires authentication, ownership check).
      operationId: updateTrack
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Track updated.
    delete:
      summary: Delete Track
      tags: [Tracks]
      description: Delete a track (requires authentication, ownership check).
      operationId: deleteTrack
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Track deleted.

  /tracks/{id}/stream:
    get:
      summary: Stream Track Audio
      tags: [Tracks]
      description: Stream the audio file for a track. Supports range requests.
      operationId: streamTrack
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Audio stream.
        '404':
          description: Track not found.

  /tracks/{id}/cover:
    get:
      summary: Get Track Cover Art
      tags: [Tracks]
      description: Returns the cover art for a track (from album or embedded).
      operationId: getTrackCover
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Image file.

  /tracks/batch:
    put:
      summary: Batch Update Tracks
      tags: [Tracks]
      description: Update metadata for multiple tracks at once.
      operationId: batchUpdateTracks
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Tracks updated.
    delete:
      summary: Batch Delete Tracks
      tags: [Tracks]
      description: Delete multiple tracks at once.
      operationId: batchDeleteTracks
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Tracks deleted.

  # ── Samples ─────────────────────────────────────────────────────────────────
  /samples:
    get:
      summary: List Samples
      tags: [Samples]
      description: |
        Lists approved free samples. Packed samples (belonging to a sample pack) are excluded —
        they only surface through their pack. `mine=true` scopes to the caller's own uploads
        (any status) and is not filtered by pack membership.
      operationId: listSamples
      parameters:
        - name: mine
          in: query
          schema:
            type: boolean
        - name: q
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of samples.
    post:
      summary: Upload Sample
      tags: [Samples]
      description: Uploads a single free sample. Starts `pending` unless auto-approved.
      operationId: uploadSample
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, title]
              properties:
                file:
                  type: string
                  format: binary
                title:
                  type: string
                description:
                  type: string
                bpm:
                  type: integer
                musicalKey:
                  type: string
                license:
                  type: string
                  enum: [cc0, cc-by, cc-by-sa, royalty-free]
                attributionName:
                  type: string
                tags:
                  type: string
                  description: Comma-separated tags.
      responses:
        '201':
          description: Sample created.

  /samples/{id}:
    get:
      summary: Get Sample
      tags: [Samples]
      operationId: getSample
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Sample metadata.
    put:
      summary: Update Sample
      tags: [Samples]
      description: Owner or moderator only.
      operationId: updateSample
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Sample updated.
    delete:
      summary: Delete Sample
      tags: [Samples]
      description: Owner or moderator only.
      operationId: deleteSample
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Sample deleted.

  /samples/{id}/download:
    get:
      summary: Download Sample
      tags: [Samples]
      description: Approved samples are public; pending samples require the owner or a moderator. Supports `?token=` query auth.
      operationId: downloadSample
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Sample audio file.

  /samples/{id}/waveform:
    get:
      summary: Get Sample Waveform
      tags: [Samples]
      description: Returns an SVG waveform visualization for a sample.
      operationId: getSampleWaveform
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: SVG waveform image.
          content:
            image/svg+xml:
              schema:
                type: string

  /samples/{id}/approve:
    post:
      summary: Approve Sample
      tags: [Samples]
      description: Root-admin/admin/super-user only.
      operationId: approveSample
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Sample approved.

  /samples/{id}/reject:
    post:
      summary: Reject Sample
      tags: [Samples]
      description: Root-admin/admin/super-user only.
      operationId: rejectSample
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                notes:
                  type: string
      responses:
        '200':
          description: Sample rejected.

  /samples/moderation/pending:
    get:
      summary: List Pending Samples
      tags: [Samples]
      description: Root-admin/admin/super-user only.
      operationId: listPendingSamples
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Samples awaiting curation.

  # ── Sample Packs ────────────────────────────────────────────────────────────
  /sample-packs:
    get:
      summary: List Sample Packs
      tags: [Sample Packs]
      description: Lists approved sample packs. `mine=true` scopes to the caller's own packs (any status).
      operationId: listSamplePacks
      parameters:
        - name: mine
          in: query
          schema:
            type: boolean
        - name: q
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of sample packs.
    post:
      summary: Upload Sample Pack
      tags: [Sample Packs]
      description: |
        Uploads multiple files at once as a pack. Same publish gate and auto-approve rules as
        `POST /samples`; starts `pending` unless auto-approved.
      operationId: uploadSamplePack
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [files, title]
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                title:
                  type: string
                description:
                  type: string
                license:
                  type: string
                  enum: [cc0, cc-by, cc-by-sa, royalty-free]
                attributionName:
                  type: string
      responses:
        '201':
          description: Sample pack created.

  /sample-packs/{id}:
    get:
      summary: Get Sample Pack
      tags: [Sample Packs]
      description: Returns pack metadata plus its member samples.
      operationId: getSamplePack
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Sample pack with samples.
    put:
      summary: Update Sample Pack
      tags: [Sample Packs]
      description: Owner or moderator only.
      operationId: updateSamplePack
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Sample pack updated.
    delete:
      summary: Delete Sample Pack
      tags: [Sample Packs]
      description: Deletes the pack and all its member samples. Owner or moderator only.
      operationId: deleteSamplePack
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Sample pack deleted.

  /sample-packs/{id}/cover:
    get:
      summary: Get Sample Pack Cover
      tags: [Sample Packs]
      description: Serves the pack's cover image, falling back to a generated placeholder SVG if none is set.
      operationId: getSamplePackCover
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Cover image or placeholder SVG.
    post:
      summary: Set Sample Pack Cover
      tags: [Sample Packs]
      description: Sets or replaces the pack cover image. Owner or moderator only.
      operationId: uploadSamplePackCover
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [cover]
              properties:
                cover:
                  type: string
                  format: binary
      responses:
        '200':
          description: Sample pack updated with new cover.

  /sample-packs/{id}/approve:
    post:
      summary: Approve Sample Pack
      tags: [Sample Packs]
      description: Root-admin/admin/super-user only. Cascades to the pack's samples.
      operationId: approveSamplePack
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Sample pack approved.

  /sample-packs/{id}/reject:
    post:
      summary: Reject Sample Pack
      tags: [Sample Packs]
      description: Root-admin/admin/super-user only.
      operationId: rejectSamplePack
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                notes:
                  type: string
      responses:
        '200':
          description: Sample pack rejected.

  /sample-packs/moderation/pending:
    get:
      summary: List Pending Sample Packs
      tags: [Sample Packs]
      description: Root-admin/admin/super-user only.
      operationId: listPendingSamplePacks
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Sample packs awaiting curation.

  # ── Releases ────────────────────────────────────────────────────────────────
  /releases:
    get:
      summary: List Releases
      tags: [Releases]
      description: Retrieves all public published releases.
      operationId: getReleases
      responses:
        '200':
          description: A list of releases.
    post:
      summary: Create Release
      tags: [Releases]
      description: Create a new release (requires authentication).
      operationId: createRelease
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Release created.

  /releases/{id}:
    get:
      summary: Get Release Details
      tags: [Releases]
      description: Get release details with track listing.
      operationId: getRelease
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Release with tracks.
    put:
      summary: Update Release
      tags: [Releases]
      description: Update a release (requires ownership or admin).
      operationId: updateRelease
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Release updated.
    delete:
      summary: Delete Release
      tags: [Releases]
      description: Delete a release (requires ownership or admin).
      operationId: deleteRelease
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Release deleted.

  # ── Playlists ───────────────────────────────────────────────────────────────
  /playlists:
    get:
      summary: List Playlists
      tags: [Playlists]
      description: Retrieves all public playlists.
      operationId: getPlaylists
      responses:
        '200':
          description: A list of playlists.
    post:
      summary: Create Playlist
      tags: [Playlists]
      description: Create a new playlist (requires authentication).
      operationId: createPlaylist
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Playlist created.

  /playlists/{id}:
    get:
      summary: Get Playlist
      tags: [Playlists]
      description: Get a playlist with its tracks.
      operationId: getPlaylist
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Playlist with tracks.
    delete:
      summary: Delete Playlist
      tags: [Playlists]
      description: Delete a playlist (requires ownership).
      operationId: deletePlaylist
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Playlist deleted.

  # ── Stats ───────────────────────────────────────────────────────────────────
  /stats:
    get:
      summary: Get Instance Statistics
      tags: [Stats]
      description: Returns play counts, top tracks/artists, and listening stats.
      operationId: getStats
      responses:
        '200':
          description: Statistics summary.

  /stats/library:
    get:
      summary: Get Library Statistics
      tags: [Stats]
      description: Returns library-level statistics (track/album/artist counts, storage, genres).
      operationId: getLibraryStats
      responses:
        '200':
          description: Library statistics.

  # ── Comments ────────────────────────────────────────────────────────────────
  /comments/track/{trackId}:
    get:
      summary: Get Comments
      tags: [Comments]
      description: Get comments for a track from the local database.
      operationId: getComments
      parameters:
        - name: trackId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of comments.

  # ── Payments & Unlock ───────────────────────────────────────────────────────
  /payments:
    post:
      summary: Record Payment
      tags: [Payments]
      description: Record an on-chain payment verification for a release/track.
      operationId: recordPayment
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Payment recorded.

  /unlock:
    post:
      summary: Validate Unlock Code
      tags: [Payments]
      description: Validate and redeem an unlock code for a gated release.
      operationId: validateUnlockCode
      responses:
        '200':
          description: Code validation result.

  # ── Admin ───────────────────────────────────────────────────────────────────
  /admin/system/rescan:
    post:
      summary: Scan Music Library
      tags: [Admin]
      description: Trigger a full scan of the music directory to index new files.
      operationId: scanLibrary
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Scan started or completed.

  /admin/settings:
    get:
      summary: Get Site Settings
      tags: [Admin]
      description: Get all site configuration settings.
      operationId: getSettings
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Settings object.
    put:
      summary: Update Site Settings
      tags: [Admin]
      description: Update site configuration (name, description, URL, etc.).
      operationId: updateSettings
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Settings updated.

  /admin/upload:
    post:
      summary: Upload Tracks
      tags: [Admin]
      description: Upload one or more audio files with metadata.
      operationId: uploadTracks
      security:
        - bearerAuth: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        '200':
          description: Upload result with created track IDs.

  /admin/backup:
    post:
      summary: Create Backup
      tags: [Admin]
      description: Create a full database backup (admin only).
      operationId: createBackup
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Backup created, returns download link.

  /admin/system/resources:
    get:
      summary: System Resource Snapshot
      tags: [Admin]
      description: |
        Live process/host metrics — CPU usage, memory (heap/RSS), host RAM,
        SQLite DB file size, and currently running background tasks. Cheap
        enough to poll every few seconds for memory-leak detection. Root admin only.
      operationId: getSystemResources
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Resource snapshot (process, system, db, tasks).
        '403':
          description: Root admin access required.

  /admin/storage/overview:
    get:
      summary: Storage Overview
      tags: [Admin]
      description: Instance-wide disk usage, logical DB total, allocated quota, and per-user breakdown. Root admin only.
      operationId: getStorageOverview
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Storage overview.
        '403':
          description: Root admin access required.

  # ── Radio ───────────────────────────────────────────────────────────────────
  /radio:
    get:
      summary: Radio Status
      tags: [Radio]
      description: Current station status — active flag, name, current track, listener count, and HLS URL. Public.
      operationId: getRadioStatus
      responses:
        '200':
          description: Radio status.

  /radio/start:
    post:
      summary: Start Radio
      tags: [Radio]
      description: |
        Start the station (admin only). Provide at least one source: `sources`
        (an array mixing numeric playlist ids and `genre:<name>` ids), or the
        legacy `playlistId` / `trackIds`.
      operationId: startRadio
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                sources:
                  type: array
                  items: { type: string }
                  description: 'Mix of playlist ids and genre ids, e.g. ["12", "genre:jazz"]'
                playlistId:
                  type: integer
                trackIds:
                  type: array
                  items: { type: integer }
                shuffle:
                  type: boolean
      responses:
        '200':
          description: Radio started; returns the new status.
        '400':
          description: Missing name or no source provided.
        '403':
          description: Admin access required.

  /radio/stop:
    post:
      summary: Stop Radio
      tags: [Radio]
      description: Stop the station (admin only).
      operationId: stopRadio
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Radio stopped.
        '403':
          description: Admin access required.

  /radio/stream.m3u:
    get:
      summary: Radio M3U Playlist
      tags: [Radio]
      description: M3U playlist pointing at the live HLS stream — opens in VLC, foobar2000, mpv, etc. Public.
      operationId: getRadioM3u
      responses:
        '200':
          description: M3U playlist.
          content:
            audio/x-mpegurl:
              schema:
                type: string
        '404':
          description: Radio is not active.

  /radio/feed.rss:
    get:
      summary: Radio RSS Feed
      tags: [Radio]
      description: Podcast-style RSS feed with an HLS enclosure, for clients like Pocket Casts and AntennaPod. Public.
      operationId: getRadioFeed
      responses:
        '200':
          description: RSS feed.
          content:
            application/rss+xml:
              schema:
                type: string

  /radio/hls/{file}:
    get:
      summary: Radio HLS Segment
      tags: [Radio]
      description: Serve the HLS playlist (`stream.m3u8`) and its `.ts` segments. Public.
      operationId: getRadioHls
      parameters:
        - name: file
          in: path
          required: true
          schema:
            type: string
          description: Playlist or segment filename (e.g. stream.m3u8, seg000001.ts).
      responses:
        '200':
          description: HLS playlist or media segment.
        '404':
          description: Radio is not active or file not found.

  # ── ActivityPub ─────────────────────────────────────────────────────────────
  /ap/followers/{artistId}:
    get:
      summary: Get Artist Followers
      tags: [ActivityPub]
      description: Get the list of ActivityPub followers for an artist.
      operationId: getArtistFollowers
      security:
        - bearerAuth: []
      parameters:
        - name: artistId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: List of followers.

  # ── Waveform ────────────────────────────────────────────────────────────────
  /waveform/{id}:
    get:
      summary: Get Track Waveform
      tags: [Tracks]
      description: Returns an SVG waveform visualization for a track.
      operationId: getWaveform
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: SVG waveform image.
          content:
            image/svg+xml:
              schema:
                type: string

  # ── Search ──────────────────────────────────────────────────────────────────
  /catalog/search:
    get:
      summary: Search Catalog
      tags: [Search]
      description: Full-text search across artists, albums, and tracks.
      operationId: searchCatalog
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query.
      responses:
        '200':
          description: Search results grouped by type.

  # ── Proxy ───────────────────────────────────────────────────────────────────
  /proxy:
    get:
      summary: Proxy External Resources
      tags: [Proxy]
      description: Proxy external images/resources to avoid CORS issues (e.g., remote cover art).
      operationId: proxyResource
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Proxied resource.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Artist:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        bio:
          type: string
          nullable: true
        photo_path:
          type: string
          nullable: true
        links:
          type: string
          nullable: true
          description: JSON string of external links.
        wallet_address:
          type: string
          nullable: true
          description: Blockchain wallet address.
        public_key:
          type: string
          nullable: true
          description: ActivityPub RSA public key (PEM).
        created_at:
          type: string
          format: date-time

    Album:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        slug:
          type: string
        artist_id:
          type: integer
          nullable: true
        artist_name:
          type: string
        date:
          type: string
          nullable: true
        cover_path:
          type: string
          nullable: true
        genre:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        type:
          type: string
          enum: [album, single, ep]
          nullable: true
        year:
          type: integer
          nullable: true
        price:
          type: number
          nullable: true
        price_usdc:
          type: number
          nullable: true
        currency:
          type: string
          enum: [ETH, USD]
        visibility:
          type: string
          enum: [public, private, unlisted]
        is_release:
          type: boolean
        published_to_gundb:
          type: boolean
        published_to_ap:
          type: boolean
        license:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time

    Track:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        album_id:
          type: integer
          nullable: true
        album_title:
          type: string
        artist_id:
          type: integer
          nullable: true
        artist_name:
          type: string
        track_num:
          type: integer
          nullable: true
        duration:
          type: number
          nullable: true
          description: Duration in seconds.
        file_path:
          type: string
          nullable: true
        format:
          type: string
          nullable: true
        bitrate:
          type: integer
          nullable: true
        sample_rate:
          type: integer
          nullable: true
        price:
          type: number
          nullable: true
        price_usdc:
          type: number
          nullable: true
        currency:
          type: string
          enum: [ETH, USD]
        lyrics:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time

    Release:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        slug:
          type: string
        artist_id:
          type: integer
          nullable: true
        owner_id:
          type: integer
          nullable: true
        artist_name:
          type: string
        type:
          type: string
          enum: [album, single, ep]
        visibility:
          type: string
          enum: [public, private, unlisted]
        published_to_gundb:
          type: boolean
        published_to_ap:
          type: boolean
        price:
          type: number
          nullable: true
        license:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time

    Playlist:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        username:
          type: string
        description:
          type: string
          nullable: true
        isPublic:
          type: boolean
        created_at:
          type: string
          format: date-time

    Error:
      type: object
      properties:
        error:
          type: string
          description: A brief error code or description.
        message:
          type: string
          description: Detailed error explanation.