# Recommendation catalogues
URL: https://musicapi.com/docs/recommendations/recommendation-catalogues.md

> Upload your own ISRC list so that recommendations come only from tracks that you can play. Create, upload, commit, poll the status, change items, and the limits.

Product: MusicAPI Core. Section: Recommendations.

Without a catalogue, the [Recommendations API](https://musicapi.com/docs/recommendations/recommendations.md) answers from the whole MusicAPI catalogue (catalogue 0). Your service can maybe play only part of it. A catalogue is your own list of ISRCs. Send its id as `catalogue`, and every track in the answer is one of your ISRCs.

- The answer gives your own ISRC of each track, so you can look it up in your database at once.
- The seeds can be any ISRC, also one that is not in your catalogue.
- `GET /similar-artists` and `GET /genres` always read the whole catalogue.

You can also manage catalogues in the dashboard: open the **Catalogues** page at [app.musicapi.com/admin/account/recommendations](https://app.musicapi.com/admin/account/recommendations).

## Create and fill a catalogue

Every write needs Basic `clientId:clientSecret`. Run these calls on your server.

1. **Create the catalogue**

   `POST /catalogues` gives the catalogue id and an upload URL.
2. **Upload the file**

   `PUT` your ISRC file to the upload URL within 1 hour.
3. **Commit**

   `POST /catalogues/{id}/commit` starts the import.
4. **Poll the status**

   `GET /catalogues/{id}` until the status is `ready` or `failed`.
5. **Use it**

   Send the id as `catalogue` with your recommendation requests.

### 1. Create the catalogue

```bash
curl -X POST "https://api.musicapi.com/public/recommendations/catalogues" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "Main catalogue"}'
```

```json
{
  "id": "42",
  "uploadUrl": "https://…",
  "expiresAt": "2026-11-16T11:00:00.000Z"
}
```

The upload URL lives 1 hour. A new catalogue has the status `awaitingUpload`.

### 2. Upload the file

One ISRC per line, as plain CSV or as gzip. A first line `isrc` is skipped, so a header is optional. The file can be up to 2 GiB.

```bash
curl -T catalogue.csv.gz '<uploadUrl>'
```

Send a plain `PUT` with no extra headers. Put the URL in single quotes: it holds `&` characters.

### 3. Commit

```bash
curl -X POST "https://api.musicapi.com/public/recommendations/catalogues/42/commit" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"
```

The answer is `202` with the catalogue. The import runs in the background. A first import sets the status `processing`.

### 4. Poll the status

```bash
curl "https://api.musicapi.com/public/recommendations/catalogues/42" \
  -H "Authorization: Token $MUSICAPI_CLIENT_ID"
```

Poll every minute or so until the status is `ready` or `failed`. A large file takes longer.

### 5. Use it

Add `catalogue=42` to `GET /similar-tracks` and to `GET /users/{userId}/recommendations`, or `"catalogue": "42"` to the body of `POST /playlist` and `POST /next`. [Personal recommendations](https://musicapi.com/docs/recommendations/personal-recommendations.md) explains the user endpoints.

## The file

- One ISRC per line. If a line has several CSV fields (separated by `,`, `;` or a tab), only the first field counts.
- Dashes, spaces and lower case are accepted. Quotes around the value are removed.
- Empty lines are skipped. A line that is not an ISRC counts in `invalid` and is skipped.
- A duplicate ISRC counts once.
- A gzip file is detected by its content, not by its name.

## The status

```json
{
  "id": "42",
  "name": "Main catalogue",
  "status": "ready",
  "importing": false,
  "isrcs": 120000,
  "invalid": 12,
  "matched": 101000,
  "withVector": 88000,
  "coverage": 0.7333,
  "error": null,
  "createdAt": "2026-11-16T10:00:00.000Z",
  "updatedAt": "2026-11-16T10:20:00.000Z"
}
```

| `status`         | Meaning                                                                         |
| ---------------- | ------------------------------------------------------------------------------- |
| `awaitingUpload` | Created. No file was committed yet.                                             |
| `processing`     | The first file imports. The read endpoints answer `409` `catalogue_not_ready`.  |
| `ready`          | The catalogue answers.                                                          |
| `failed`         | The first import failed. `error` tells why. Upload a new file and commit again. |

Two more fields tell you about an import:

- `importing`: `true` while an import runs. When you upload a new file to a `ready` catalogue, it stays `ready` and answers with the old data until the new data is in.
- `error`: why the last import failed: `catalogue_limit`, `upload_missing`, `file_too_large` or `import_failed`. When a new file of a `ready` catalogue fails, the status stays `ready` with the old data, and `error` is set.

`GET /catalogues` lists all your catalogues, the newest first, in the same shape.

## Coverage

Not every ISRC of your file can come back in an answer:

- `isrcs`: the unique valid ISRCs of the catalogue.
- `matched`: the ISRCs that MusicAPI knows.
- `withVector`: the matched ISRCs whose track has a vector. Only these can be in an answer.
- `coverage`: `withVector / isrcs`, from 0 to 1.

A track gets a vector when it is in at least 3 playlists of the MusicAPI corpus. A new or rare release may have none yet. The model is trained again each week, and your catalogue then gets the new vectors by itself. You do not upload the file again for that.

## Change items without a full upload

For daily changes, add and remove ISRCs with one call:

```bash
curl -X POST "https://api.musicapi.com/public/recommendations/catalogues/42/items" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"add": ["USRC17607839"], "remove": ["GBUM71029604"]}'
```

- `add` and `remove` hold at most 10,000 ISRCs together.
- An ISRC in both lists is removed.
- The catalogue must be `ready`, with no import running.
- The answer is the catalogue with its new counts. The change applies to the next request.

For bigger changes, upload a new file.

## Upload a new file

A new file replaces the whole list. ISRCs that are not in the new file leave the catalogue.

1. `POST /catalogues/{id}/upload-url` gives a new upload URL (1 hour).
2. `PUT` the file to it.
3. `POST /catalogues/{id}/commit`.

The catalogue stays `ready` and answers with the old list while the new file imports.

## Delete a catalogue

```bash
curl -X DELETE "https://api.musicapi.com/public/recommendations/catalogues/42" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"
```

The answer is `204`. The catalogue, its ISRCs and its file are deleted. A request with its id then answers `404` `catalogue_not_found`.

## Limits

- An account holds at most 10 catalogues.
- The ISRCs of all your catalogues together have a limit that MusicAPI sets for your account. The default is 100,000. A file or an item change that goes over it fails with `catalogue_limit`. When the limit of your account is 0, you cannot fill a catalogue. [Contact us](https://schedule.musicapi.com/) to raise it.
- A file can be up to 2 GiB. The upload URL lives 1 hour.

## Errors

The body is `{ "error": "<code>", "message": "<text>" }`.

| Status | `error`                 | When                                                                                               |
| ------ | ----------------------- | -------------------------------------------------------------------------------------------------- |
| 404    | `catalogue_not_found`   | The id does not exist, was deleted, or belongs to another account.                                 |
| 409    | `catalogue_limit`       | `POST /catalogues` with 10 catalogues already, or an item change over your ISRC limit.             |
| 409    | `catalogue_busy`        | An import runs. Wait until `importing` is `false`, then try again.                                 |
| 409    | `catalogue_not_ready`   | An item change on a catalogue that is not `ready`, or a read with a catalogue that is not `ready`. |
| 409    | `upload_missing`        | A commit, but no file was uploaded to the URL.                                                     |
| 413    | `file_too_large`        | A commit of a file over 2 GiB.                                                                     |
| 403    | (the usual error shape) | A write without the Client Secret.                                                                 |

## Billing

The catalogue meter counts the ISRCs of all your catalogues together, on the largest day of the month. The catalogue calls themselves do not count on the request meter. See [Billing](https://musicapi.com/docs/recommendations/recommendations.md#billing).
