# Process an uploaded catalogue file
URL: https://musicapi.com/docs/reference/recommendations-commit-catalogue.md

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

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

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

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

## Response 202

The import started.

| 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

- 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.

## Example

```bash
curl -X POST "https://api.musicapi.com/public/recommendations/catalogues/{catalogueId}/commit" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"
```
