Generate track recommendations from seed tracks, artists, or albums. The engine clusters a large dataset of songs, artists, and audio features and returns tracks whose characteristics best match the seeds, with the result set size controlled by the size parameter. Seeds accept ReccoBeats or Spotify IDs.
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).