# Generate a playlist
URL: https://musicapi.com/docs/reference/recommendations-playlist.md

`POST https://api.musicapi.com/public/recommendations/playlist`

Section: Recommendations.
Product: MusicAPI Core.
Auth: Basic, Token, DevToken, DocsSession (any one of them). Use Basic with your Client ID and Client Secret from your server only.

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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seeds` | object | yes | At least one of the three lists. |
| `seeds.isrcs` | string \| object[] | no |  |
| `seeds.isrcs[].isrc` | string | yes |  |
| `seeds.isrcs[].weight` | number | no | How much this seed counts. A negative weight steers away from it. |
| `seeds.artistIds` | string \| object[] | no |  |
| `seeds.artistIds[].id` | string | yes |  |
| `seeds.artistIds[].weight` | number | no | How much this seed counts. A negative weight steers away from it. |
| `seeds.genres` | string \| object[] | no |  |
| `seeds.genres[].genre` | string | yes |  |
| `seeds.genres[].weight` | number | no | How much this seed counts. A negative weight steers away from it. |
| `length` | number | no | How many tracks to return. |
| `catalogue` | string | no | The id of one of your catalogues. Leave it out for the whole MusicAPI catalogue. |
| `maxPerArtist` | number | no |  |
| `exclude` | string[] | no | ISRCs to leave out, for example the tracks the listener has. |
| `shuffleSeed` | string | no | Shuffle inside groups of 5. The same seed gives the same order. |

## Response 200

ok

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `modelVersion` | string | yes | The model version that made the answer. |
| `tracks` | RecommendationTrack[] | yes |  |
| `tracks[].isrc` | string | yes | With `catalogue`: your own ISRC of the track. Else one ISRC of the track. |
| `tracks[].score` | number | yes | The similarity to the seeds, up to 1. |
| `tracks[].title` | string \| null | yes | A display aid. Your own metadata stays the source of truth. |
| `tracks[].artist` | object | yes |  |
| `tracks[].artist.id` | string | yes | The MusicAPI artist id. Use it as an artist seed. |
| `tracks[].artist.name` | string \| null | yes |  |
| `unresolved` | string[] | yes | The seeds that resolved to nothing, as you sent them. |

```json
{
  "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.

## Example

```bash
curl -X POST "https://api.musicapi.com/public/recommendations/playlist" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"seeds":{"isrcs":["USRC17607839"],"artistIds":["123456"],"genres":["dream pop"]},"length":20,"catalogue":"42","maxPerArtist":2,"exclude":["string"],"shuffleSeed":"string"}'
```
