Skip to the content
  1. API reference
  2. Recommendations

Process an uploaded catalogue file

POST/public/recommendations/catalogues/{catalogueId}/commit
CoreAuthBasic

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

catalogueId
stringrequired

The catalogue id from POST /public/recommendations/catalogues.

Response

202application/json · RecommendationCatalogueThe import started.
id
string
required
name
string
required
status
string
requiredOne of: awaitingUpload, processing, ready, failed
importing
boolean
requiredTrue while an import runs. A ready catalogue stays ready while a new file imports.
isrcs
number
requiredUnique valid ISRCs.
invalid
number
requiredLines of the last file that are not an ISRC.
matched
number
requiredISRCs we know.
withVector
number
requiredMatched ISRCs that can appear in results.
coverage
number
requiredwithVector / isrcs.
error
string | null
requiredWhy the last import failed: 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.
createdAt
date-time
required
updatedAt
date-time
required
Example answer
{
  "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

401

No valid credential.

403

The request does not use Client Secret authentication.

404

catalogue_not_found: the catalogue does not exist or is not yours.

409

upload_missing: no file is at the upload URL. catalogue_busy: an import of the catalogue runs.

413

file_too_large: the file is larger than 2 GiB.

429

Your account sent more calls this minute than its rate limit allows.