- Docs
- Recommendations
Recommendation catalogues
Without a catalogue, the Recommendations API 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-artistsandGET /genresalways read the whole catalogue.
You can also manage catalogues in the dashboard: open the Catalogues page at app.musicapi.com/admin/account/recommendations.
Create and fill a catalogue
Every write needs Basic clientId:clientSecret. Run these calls on your server.
- Create the catalogue
POST /cataloguesgives the catalogue id and an upload URL. - Upload the file
PUTyour ISRC file to the upload URL within 1 hour. - Commit
POST /catalogues/{id}/commitstarts the import. - Poll the status
GET /catalogues/{id}until the status isreadyorfailed. - Use it
Send the id as
cataloguewith your recommendation requests.
1. Create the catalogue
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"}'
{
"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.
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
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
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 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
invalidand is skipped. - A duplicate ISRC counts once.
- A gzip file is detected by its content, not by its name.
The status
{
"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:truewhile an import runs. When you upload a new file to areadycatalogue, it staysreadyand answers with the old data until the new data is in.error: why the last import failed:catalogue_limit,upload_missing,file_too_largeorimport_failed. When a new file of areadycatalogue fails, the status staysreadywith the old data, anderroris 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:
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"]}'
addandremovehold 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.
POST /catalogues/{id}/upload-urlgives a new upload URL (1 hour).PUTthe file to it.POST /catalogues/{id}/commit.
The catalogue stays ready and answers with the old list while the new file imports.
Delete a catalogue
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 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.