openapi: 3.0.3
info:
  title: ReccoBeats API
  description: >-
    ReccoBeats is a free music recommendation and database API. It serves track,
    artist, and album metadata from a database of millions of tracks, generates
    track recommendations from seed tracks/artists/albums, and returns
    Spotify-style audio features (acousticness, danceability, energy,
    instrumentalness, liveness, loudness, speechiness, tempo, valence) either for
    a catalog track by ID or extracted directly from an uploaded audio file.
    Resources are addressed by a ReccoBeats UUID (v4) or by a Spotify Base-62 ID.
    No API key or authentication is required. The API enforces internal rate
    limits and returns HTTP 429 with a Retry-After header when throttled.
  version: '1.0'
  contact:
    name: ReccoBeats
    url: https://reccobeats.com
servers:
  - url: https://api.reccobeats.com/v1
    description: ReccoBeats production API
tags:
  - name: Track
    description: Track metadata lookup by ReccoBeats or Spotify ID.
  - name: Audio Features
    description: Spotify-style audio features for a catalog track.
  - name: Audio Analysis
    description: Extract audio features directly from an uploaded audio file.
  - name: Recommendation
    description: Track recommendations generated from seeds.
  - name: Artist
    description: Artist metadata and discography.
  - name: Album
    description: Album metadata and tracklists.
paths:
  /track:
    get:
      operationId: getTracks
      tags:
        - Track
      summary: Get multiple tracks
      description: >-
        Retrieve metadata for multiple tracks in one request. Accepts a list of
        ReccoBeats UUIDs or Spotify IDs via the ids query parameter.
      parameters:
        - name: ids
          in: query
          required: true
          description: Comma-separated list of ReccoBeats UUIDs or Spotify IDs.
          schema:
            type: string
      responses:
        '200':
          description: A list of tracks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Track'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /track/{id}:
    get:
      operationId: getTrackById
      tags:
        - Track
      summary: Get track detail
      description: Retrieve detailed metadata for a single track by its ReccoBeats UUID.
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '200':
          description: The requested track.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Track'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /track/{id}/audio-features:
    get:
      operationId: getTrackAudioFeatures
      tags:
        - Audio Features
      summary: Get track's audio features
      description: >-
        Retrieve the Spotify-style audio features for a catalog track by its
        ReccoBeats UUID.
      parameters:
        - $ref: '#/components/parameters/TrackId'
      responses:
        '200':
          description: The audio features for the track.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioFeatures'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /track/recommendation:
    get:
      operationId: getRecommendation
      tags:
        - Recommendation
      summary: Track recommendation
      description: >-
        Generate track recommendations from one or more seeds (track, artist, or
        album IDs). The engine clusters songs, artists, and audio features and
        returns tracks whose characteristics best match the seeds. Optional
        audio-feature target parameters can be supplied to steer the results
        toward a desired sound and mood.
      parameters:
        - name: seeds
          in: query
          required: true
          description: >-
            Comma-separated list of seed IDs (ReccoBeats UUIDs or Spotify IDs)
            for tracks, artists, or albums.
          schema:
            type: string
        - name: size
          in: query
          required: false
          description: Number of recommended tracks to return.
          schema:
            type: integer
            default: 10
        - name: acousticness
          in: query
          required: false
          description: Target acousticness (0.0-1.0) to steer recommendations. Modeled.
          schema:
            type: number
            format: float
        - name: danceability
          in: query
          required: false
          description: Target danceability (0.0-1.0) to steer recommendations. Modeled.
          schema:
            type: number
            format: float
        - name: energy
          in: query
          required: false
          description: Target energy (0.0-1.0) to steer recommendations. Modeled.
          schema:
            type: number
            format: float
        - name: instrumentalness
          in: query
          required: false
          description: Target instrumentalness (0.0-1.0) to steer recommendations. Modeled.
          schema:
            type: number
            format: float
        - name: liveness
          in: query
          required: false
          description: Target liveness (0.0-1.0) to steer recommendations. Modeled.
          schema:
            type: number
            format: float
        - name: speechiness
          in: query
          required: false
          description: Target speechiness (0.0-1.0) to steer recommendations. Modeled.
          schema:
            type: number
            format: float
        - name: tempo
          in: query
          required: false
          description: Target tempo in BPM to steer recommendations. Modeled.
          schema:
            type: number
            format: float
        - name: valence
          in: query
          required: false
          description: Target valence (0.0-1.0) to steer recommendations. Modeled.
          schema:
            type: number
            format: float
      responses:
        '200':
          description: A list of recommended tracks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Track'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /analysis/audio-features:
    post:
      operationId: extractAudioFeatures
      tags:
        - Audio Analysis
      summary: Extract audio features
      description: >-
        Extract audio features directly from an uploaded audio file. The file is
        sent as multipart/form-data. Supported formats are MP3, OGG/Vorbis,
        AIFF/AIFC, and WAV, up to 5 MB; only the first 30 seconds are analyzed
        and a 44,100 Hz sampling rate is recommended.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - audioFile
              properties:
                audioFile:
                  type: string
                  format: binary
                  description: The audio file to analyze (MP3, OGG, WAV, AIFF; max 5 MB).
      responses:
        '200':
          description: The extracted audio features.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioFeatures'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /artist:
    get:
      operationId: getArtists
      tags:
        - Artist
      summary: Get multiple artists
      description: >-
        Retrieve metadata for multiple artists in one request. Accepts a list of
        ReccoBeats UUIDs or Spotify IDs via the ids query parameter.
      parameters:
        - name: ids
          in: query
          required: true
          description: Comma-separated list of ReccoBeats UUIDs or Spotify IDs.
          schema:
            type: string
      responses:
        '200':
          description: A list of artists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Artist'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /artist/search:
    get:
      operationId: searchArtists
      tags:
        - Artist
      summary: Search artist
      description: Search the ReccoBeats database for artists by name.
      parameters:
        - name: searchText
          in: query
          required: true
          description: The artist name (or partial name) to search for.
          schema:
            type: string
        - name: size
          in: query
          required: false
          description: Number of results per page.
          schema:
            type: integer
            default: 20
        - name: page
          in: query
          required: false
          description: Zero-based page index.
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Matching artists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Artist'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /artist/{id}:
    get:
      operationId: getArtistById
      tags:
        - Artist
      summary: Get artist detail
      description: Retrieve detailed metadata for a single artist by ReccoBeats UUID.
      parameters:
        - $ref: '#/components/parameters/ArtistId'
      responses:
        '200':
          description: The requested artist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artist'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /artist/{id}/album:
    get:
      operationId: getArtistAlbums
      tags:
        - Artist
      summary: Get artist's albums
      description: List the albums for a given artist, identified by ReccoBeats UUID.
      parameters:
        - $ref: '#/components/parameters/ArtistId'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: The artist's albums.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Album'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /artist/{id}/track:
    get:
      operationId: getArtistTracks
      tags:
        - Artist
      summary: Get artist's tracks
      description: List the tracks for a given artist, identified by ReccoBeats UUID.
      parameters:
        - $ref: '#/components/parameters/ArtistId'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: The artist's tracks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Track'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /album:
    get:
      operationId: getAlbums
      tags:
        - Album
      summary: Get multiple albums
      description: >-
        Retrieve metadata for multiple albums in one request. Accepts a list of
        ReccoBeats UUIDs or Spotify IDs via the ids query parameter.
      parameters:
        - name: ids
          in: query
          required: true
          description: Comma-separated list of ReccoBeats UUIDs or Spotify IDs.
          schema:
            type: string
      responses:
        '200':
          description: A list of albums.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Album'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /album/search:
    get:
      operationId: searchAlbums
      tags:
        - Album
      summary: Search album
      description: Search the ReccoBeats database for albums by title.
      parameters:
        - name: searchText
          in: query
          required: true
          description: The album title (or partial title) to search for.
          schema:
            type: string
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Matching albums.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Album'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /album/{id}:
    get:
      operationId: getAlbumById
      tags:
        - Album
      summary: Get album detail
      description: Retrieve detailed metadata for a single album by ReccoBeats UUID.
      parameters:
        - $ref: '#/components/parameters/AlbumId'
      responses:
        '200':
          description: The requested album.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Album'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /album/{id}/track:
    get:
      operationId: getAlbumTracks
      tags:
        - Album
      summary: Get album's tracks
      description: List the tracks on a given album, identified by ReccoBeats UUID.
      parameters:
        - $ref: '#/components/parameters/AlbumId'
        - $ref: '#/components/parameters/Size'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: The album's tracks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/Track'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    TrackId:
      name: id
      in: path
      required: true
      description: The ReccoBeats UUID of the track.
      schema:
        type: string
    ArtistId:
      name: id
      in: path
      required: true
      description: The ReccoBeats UUID of the artist.
      schema:
        type: string
    AlbumId:
      name: id
      in: path
      required: true
      description: The ReccoBeats UUID of the album.
      schema:
        type: string
    Size:
      name: size
      in: query
      required: false
      description: Number of results per page.
      schema:
        type: integer
        default: 20
    Page:
      name: page
      in: query
      required: false
      description: Zero-based page index.
      schema:
        type: integer
        default: 0
  responses:
    BadRequest:
      description: The request was malformed or missing required parameters.
    NotFound:
      description: The requested resource was not found.
    TooManyRequests:
      description: >-
        Rate limit exceeded. Inspect the Retry-After header to determine how
        long to wait before retrying.
  schemas:
    Track:
      type: object
      description: A track in the ReccoBeats database.
      properties:
        id:
          type: string
          description: The ReccoBeats UUID for the track.
        trackTitle:
          type: string
        artists:
          type: array
          items:
            $ref: '#/components/schemas/Artist'
        durationMs:
          type: integer
        isrc:
          type: string
        ean:
          type: string
        upc:
          type: string
        href:
          type: string
        availableCountries:
          type: string
        popularity:
          type: integer
    Artist:
      type: object
      description: An artist in the ReccoBeats database.
      properties:
        id:
          type: string
          description: The ReccoBeats UUID for the artist.
        name:
          type: string
        href:
          type: string
    Album:
      type: object
      description: An album in the ReccoBeats database.
      properties:
        id:
          type: string
          description: The ReccoBeats UUID for the album.
        albumTitle:
          type: string
        artists:
          type: array
          items:
            $ref: '#/components/schemas/Artist'
        releaseDate:
          type: string
        href:
          type: string
    AudioFeatures:
      type: object
      description: >-
        Spotify-style audio features describing a track's sound and mood. Values
        are numeric; the 0.0-1.0 measures are confidence/intensity scores.
      properties:
        id:
          type: string
          description: The ReccoBeats UUID of the analyzed track (omitted for file uploads).
        acousticness:
          type: number
          format: float
          description: Confidence (0.0-1.0) that the track is acoustic.
        danceability:
          type: number
          format: float
          description: How suitable the track is for dancing (0.0-1.0).
        energy:
          type: number
          format: float
          description: Perceptual intensity and activity (0.0-1.0).
        instrumentalness:
          type: number
          format: float
          description: Likelihood the track has no vocals (0.0-1.0).
        liveness:
          type: number
          format: float
          description: Presence of a live audience (0.0-1.0).
        loudness:
          type: number
          format: float
          description: Overall loudness in decibels (typically -60 to 0 dB).
        speechiness:
          type: number
          format: float
          description: Presence of spoken words (0.0-1.0).
        tempo:
          type: number
          format: float
          description: Estimated tempo in beats per minute.
        valence:
          type: number
          format: float
          description: Musical positivity / happiness (0.0-1.0).