Skip to the content
  1. API reference
  2. Recommendations

Create a catalogue

POST/public/recommendations/catalogues
CoreAuthBasic

Creates an empty catalogue of your own ISRCs and answers a URL to upload its file to. Upload the file with an HTTP PUT to uploadUrl within one hour (curl -T catalogue.csv '<uploadUrl>'), then call POST /public/recommendations/catalogues/{catalogueId}/commit. The file is a CSV or a gzip CSV with one ISRC per line, at most 2 GiB. A first line isrc is skipped. Recommendations with catalogue then come only from your catalogue. Your account limits the ISRCs of all its catalogues together (100,000 until we raise it), and holds at most 10 catalogues. Needs Client Secret authentication.

Request body

application/json · required

name
string
required

Response

201application/json · RecommendationCatalogueUploadThe catalogue and its upload URL.
id
string
required
uploadUrl
uri
requiredPUT the file here. Valid for one hour.
expiresAt
date-time
required
Example answer
{
  "id": "42",
  "uploadUrl": "https://example.com",
  "expiresAt": "2026-10-16T09:41:07.000Z"
}

Errors

400

name is missing or longer than 200 characters.

401

No valid credential.

403

The request does not use Client Secret authentication.

409

catalogue_limit: your account already holds 10 catalogues.

429

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