Skip to the content
  1. API reference
  2. Recommendations

Generate a playlist

POST/public/recommendations/playlist
CoreAuthBasicTokenDevTokenDocsSession

Builds a playlist from seeds: ISRCs, artist ids and genres (from GET /public/recommendations/genres), each with an optional weight. The seeds become one taste vector. The answer leaves out the seed tracks and exclude, keeps at most maxPerArtist tracks of one artist, and mixes near duplicates down the list. A seed that resolves to nothing is listed in unresolved; the rest still count. shuffleSeed shuffles the list inside groups of 5, so the same seed gives the same order and a new seed gives a fresh one. Each call counts as one recommendation request on your usage.

Request body

application/json · required

seeds
object
requiredAt least one of the three lists.
seeds.isrcs
string | object[]
seeds.isrcs[].isrc
string
required
seeds.isrcs[].weight
number
How much this seed counts. A negative weight steers away from it.Default: 1
seeds.artistIds
string | object[]
seeds.artistIds[].id
string
required
seeds.artistIds[].weight
number
How much this seed counts. A negative weight steers away from it.Default: 1
seeds.genres
string | object[]
seeds.genres[].genre
string
required
seeds.genres[].weight
number
How much this seed counts. A negative weight steers away from it.Default: 1
length
number
How many tracks to return.Default: 20
catalogue
string
The id of one of your catalogues. Leave it out for the whole MusicAPI catalogue.
maxPerArtist
number
Default: 2
exclude
string[]
ISRCs to leave out, for example the tracks the listener has.
shuffleSeed
string
Shuffle inside groups of 5. The same seed gives the same order.

Response

200application/json · RecommendationPlaylistResponseok
modelVersion
string
requiredThe model version that made the answer.
tracks
RecommendationTrack[]
required
tracks[].isrc
string
requiredWith catalogue: your own ISRC of the track. Else one ISRC of the track.
tracks[].score
number
requiredThe similarity to the seeds, up to 1.
tracks[].title
string | null
requiredA display aid. Your own metadata stays the source of truth.
tracks[].artist
object
required
tracks[].artist.id
string
requiredThe MusicAPI artist id. Use it as an artist seed.
tracks[].artist.name
string | null
required
unresolved
string[]
requiredThe seeds that resolved to nothing, as you sent them.
Example answer
{
  "modelVersion": "2026-11-13",
  "tracks": [
    {
      "isrc": "USRC17607839",
      "score": 0.8731,
      "title": "Forests",
      "artist": {
        "id": "123456",
        "name": "LaziiBee"
      }
    }
  ],
  "unresolved": [
    "string"
  ]
}

Errors

400

No seed, a malformed seed, or length out of range.

401

No valid credential.

404

no_signal: no seed resolved. catalogue_not_found: the catalogue does not exist or is not yours.

409

catalogue_not_ready: the catalogue is still processing.

429

Your account sent more calls this minute than its rate limit allows.

503

model_not_ready: no recommendation model is active yet. Try again later. temporarily_unavailable: the recommendation index is loading or busy (for example right after a weekly model swap). Try again after the Retry-After seconds.