Skip to the content
  1. Docs
  2. Recommendations

Recommendation catalogues

CoreGuide · 5 min
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.

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-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.

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

curl
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"}'
201 Created
{
  "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
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
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
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 invalid and is skipped.
  • A duplicate ISRC counts once.
  • A gzip file is detected by its content, not by its name.

The status

GET /catalogues/42
{
  "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"
}
statusMeaning
awaitingUploadCreated. No file was committed yet.
processingThe first file imports. The read endpoints answer 409 catalogue_not_ready.
readyThe catalogue answers.
failedThe 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:

curl
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

curl
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>" }.

StatuserrorWhen
404catalogue_not_foundThe id does not exist, was deleted, or belongs to another account.
409catalogue_limitPOST /catalogues with 10 catalogues already, or an item change over your ISRC limit.
409catalogue_busyAn import runs. Wait until importing is false, then try again.
409catalogue_not_readyAn item change on a catalogue that is not ready, or a read with a catalogue that is not ready.
409upload_missingA commit, but no file was uploaded to the URL.
413file_too_largeA 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.