# Create a catalogue
URL: https://musicapi.com/docs/reference/recommendations-create-catalogue.md

`POST https://api.musicapi.com/public/recommendations/catalogues`

Section: Recommendations.
Product: MusicAPI Core.
Auth: Basic (any one of them). Use Basic with your Client ID and Client Secret from your server only.

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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |

## Response 201

The catalogue and its upload URL.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `uploadUrl` | uri | yes | PUT the file here. Valid for one hour. |
| `expiresAt` | date-time | yes |  |

```json
{
  "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.

## Example

```bash
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"}'
```
