- API reference
- Recommendations
Process an uploaded catalogue file
Checks the uploaded file and starts its import. Read GET /public/recommendations/catalogues/{catalogueId} until importing is false. A first import has the status processing, and recommendation calls that name the catalogue answer 409 catalogue_not_ready until it is ready or failed. A new file for a ready catalogue keeps it ready: calls answer from the old data until the new data is in place. If the new file fails, the old data stays and error names the reason. A failed import names the reason in error (catalogue_limit: more unique ISRCs than your account allows). Needs Client Secret authentication.
Path parameters
The catalogue id from POST /public/recommendations/catalogues.
Response
ready catalogue stays ready while a new file imports.withVector / isrcs.catalogue_limit, upload_missing, file_too_large or import_failed. After a failed new file of a ready catalogue, the status stays ready with the old data.{
"id": "42",
"name": "Main catalogue",
"status": "awaitingUpload",
"importing": true,
"isrcs": 120000,
"invalid": 12,
"matched": 101000,
"withVector": 88000,
"coverage": 0.7333,
"error": "string",
"createdAt": "2026-10-16T09:41:07.000Z",
"updatedAt": "2026-10-16T09:41:07.000Z"
}
Errors
No valid credential.
The request does not use Client Secret authentication.
catalogue_not_found: the catalogue does not exist or is not yours.
upload_missing: no file is at the upload URL. catalogue_busy: an import of the catalogue runs.
file_too_large: the file is larger than 2 GiB.
Your account sent more calls this minute than its rate limit allows.