Catalogue Ingest API

Catalogue routing

Group works per artist with client_artist_ref, without storing our catalogue ids.

Most integrations hold many artists. client_artist_ref keeps each artist's works in their own catalogue, and you never have to store a Record catalog_id to do it.

How to use it#

Send your own stable artist id as a top-level body field. It is not a header, and it is not a per-work field.

json

{
  "client_artist_ref": "your-platform-user-8842",
  "catalog_name": "Nova Ray",
  "works": [ ... ]
}

Use the same value for every chunk you send for that artist.

Do not group by recording.artist_name. Names vary between releases and deliveries, and two artists can share a name. An id from your own system does not have that problem.

What we do with it#

When you omit catalog_id:

1

The ref already maps to a catalogue

New works go to that catalogue.

2

No mapping exists, but the batch matches one catalogue

If every matched client_work_ref already lives in one catalogue, a commit attaches your ref to that catalogue. New works in the batch go there too.

3

No mapping and no match

The first commit creates a catalogue, named by catalog_name or by the default name.

When we refuse#

Two situations return 400 VALIDATION_ERROR, because we cannot know which catalogue you meant:

One client_artist_ref matches works spread across several existing catalogues.
The ref already maps to one catalogue, but the batch's matched works belong to another.

Both mean your catalogues and your artist ids disagree. Reconcile them before you send again. We would rather refuse than split an artist's works across two catalogues.

Precedence#

If you send both catalog_id and client_artist_ref, catalog_id wins. We append to that catalogue and we do not create an artist mapping.

In dry-run#

A dry-run creates no mapping and attaches nothing.

If a dry-run finds an existing mapped or adoptable catalogue, the response catalog_id is that catalogue. If the request would create a new catalogue on commit, catalog_id comes back empty. Do not store it.

With no artist id#

Create the catalogue on the first chunk by omitting catalog_id, then send the returned catalog_id on every later chunk for that artist.