Releases

Technical catalogue inventory for ingested releases with GET /v1/releases.

The releases endpoints expose technical catalogue inventory: album and product rows your organisation has ingested, with identifiers such as UPC/EAN and links to your client-side catalogue keys.

Not catalogue search

Release inventory answers what releases exist in my ingested catalogue? It is for known catalogue rows, not open-ended discovery. Use Catalogue search for MusiSearch track discovery, or contact the MusiMap team for advanced catalogue workflows.

Scope and access

  • GET /v1/releases lists releases visible in organisation-owned catalogues through your current API context.
  • In V1, inventory is scoped to the token's current catalogue context from /v1/me (catalog_id). An optional catalog_id query filter must match that context.
  • GET /v1/releases/{release_id} uses the MusiMap release UUID only. Client/source ids belong in the outer_id list filter.
  • OAuth scope: catalog.read. Request this scope when exchanging client credentials. Tenant and catalogue access is enforced on every call.
  • To read a release from MusiMap Atlas, call GET /v1/releases/{release_id}?source=musimap-atlas. Requires musimap-atlas.read and organisation entitlement musimap_atlas_read. See MusiMap Atlas.

Releases and tracks

A release is a product or album container. Tracks are individual recordings and are listed separately through GET /v1/tracks. Release inventory does not embed full track listings in V1 — use tracks inventory or ingestion entity inspection when you need recording-level detail.

List releases

curl "https://api.musimap.com/v1/releases?upc=602566073002" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Supported list filters include:

  • outer_id — client/source-side identifier.
  • title — exact title match (case-insensitive).
  • upc, ean, release_date.
  • source_record_key, delivery_id.
  • created_after, created_before, updated_after, updated_before.
  • page, page_size (1–100) for pagination.

List responses use the standard MusiMap paginated envelope inside data. See Pagination.

Typical response fields

Each release summary in data.results includes:

  • id — MusiMap canonical release UUID.
  • title, optional release_date.
  • upc, ean when present.
  • catalog_id, outer_id when present.
  • created_at, updated_at.

Get one release

curl "https://api.musimap.com/v1/releases/$MUSIMAP_RELEASE_UUID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

For MusiMap Atlas items, pass source=musimap-atlas: 

curl "https://api.musimap.com/v1/releases/$MUSIMAP_RELEASE_UUID?source=musimap-atlas" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Detail responses use the same public summary fields as list rows in V1. Returns HTTP 404 when the release does not exist or is outside your access scope.

  • Tracks — recording inventory.
  • Artists — performer inventory.
  • Works — composition inventory.

Errors

Missing or invalid tokens return HTTP 401 with the MusiMap error envelope. Inaccessible release ids return HTTP 404 with data.error_code: "not_found" so callers cannot infer cross-tenant existence.