# Add or remove catalogue ISRCs
URL: https://musicapi.com/docs/reference/recommendations-change-catalogue-items.md

`POST https://api.musicapi.com/public/recommendations/catalogues/{catalogueId}/items`

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

Adds and removes ISRCs of a ready catalogue, at most 10,000 in one call. Use it for daily changes; only the named ISRCs change. An ISRC in both lists is removed. The answer is the catalogue with the new counts. Needs Client Secret authentication.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `catalogueId` | string | yes | The catalogue id from `POST /public/recommendations/catalogues`. |

## Request body

`application/json`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `add` | string[] | no |  |
| `remove` | string[] | no |  |

## Response 200

ok

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `name` | string | yes |  |
| `status` | string | yes | One of: awaitingUpload, processing, ready, failed. |
| `importing` | boolean | yes | True while an import runs. A `ready` catalogue stays `ready` while a new file imports. |
| `isrcs` | number | yes | Unique valid ISRCs. |
| `invalid` | number | yes | Lines of the last file that are not an ISRC. |
| `matched` | number | yes | ISRCs we know. |
| `withVector` | number | yes | Matched ISRCs that can appear in results. |
| `coverage` | number | yes | `withVector / isrcs`. |
| `error` | string \| null | yes | Why 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 | yes |  |
| `updatedAt` | date-time | yes |  |

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

- 400: A value is not an ISRC, or the lists hold more than 10,000 ISRCs together.
- 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: `catalogue_not_ready` or `catalogue_busy`: the catalogue is not ready, or an import runs. `catalogue_limit`: the change passes the limit of your account (all catalogues together).
- 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/{catalogueId}/items" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"add":["USRC17607839"],"remove":["GBAYE0601498"]}'
```
