MusiMap Atlas

Read-only MusiMap Atlas layer — entitlement, search, and inventory access.

MusiMap Atlas is MusiMap's read-only shared music intelligence layer. It holds canonical track, artist, and release metadata curated by MusiMap — separate from catalogues your organisation ingests. Entitled clients can discover Atlas content through MusiSearch and read individual items through inventory endpoints.

Read-only — not a customer catalogue

MusiMap Atlas is not listed in GET /v1/catalogs and cannot be targeted by ingestion. Public write paths always deliver into your organisation-owned catalogues. Atlas access is browse-and-read only for entitled integrations.

What MusiMap Atlas provides

  • A shared layer of MusiMap-curated music metadata for discovery and enrichment.
  • Search results and inventory reads that identify Atlas items with source.layer: "musimap-atlas".
  • Customer catalogue rows continue to use source.layer: "customer_catalog".
  • Internal catalogue identifiers are never exposed in public responses.

Authorization

Visible MusiMap Atlas access requires both of the following:

  • OAuth scope musimap-atlas.read on your access token.
  • Organisation entitlement musimap_atlas_read for your integration.

Configure the scope on your OAuth client when exchanging client credentials. The entitlement is provisioned by MusiMap for eligible organisations. If either requirement is missing, Atlas-inclusive search and Atlas inventory reads return HTTP 403 with data.error_code: "musimap_atlas_not_entitled".

See Scopes for the full scope list and Authentication for token exchange.

MusiSearch (POST /v1/search/tracks) searches your accessible customer catalogue by default. To also include MusiMap Atlas in the same query, set include_musimap_atlas: true in the request body.

  • When omitted or false, search remains customer-catalogue only.
  • When true, entitled clients search both layers in one request.
  • Requires search.read plus the Atlas scope and entitlement above.
  • At equal relevance, customer catalogue results rank before MusiMap Atlas results.
curl -X POST "https://api.musimap.com/v1/search/tracks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "uplifting electronic",
    "include_musimap_atlas": true,
    "page": 1,
    "page_size": 20
  }'

Each search hit includes a source object. Use source.layer to tell whether the match came from your catalogue or MusiMap Atlas before fetching full details. 

{
  "track": { "id": "0190…", "title": "Track title", "isrc": "GBUM71904911" },
  "source": { "layer": "musimap-atlas" },
  "search": { "score": 0.91 }
}

Full MusiSearch request and filter documentation: Catalogue search.

Read Atlas items from inventory

When MusiSearch returns an item with source.layer: "musimap-atlas", fetch the full record through the matching inventory endpoint and pass source=musimap-atlas as a query parameter:

  • GET /v1/tracks/{track_id}?source=musimap-atlas
  • GET /v1/artists/{artist_id}?source=musimap-atlas
  • GET /v1/releases/{release_id}?source=musimap-atlas
curl "https://api.musimap.com/v1/tracks/$MUSIMAP_TRACK_UUID?source=musimap-atlas" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Rules:

  • Requires catalog.read, musimap-atlas.read, and the organisation entitlement.
  • Without source=musimap-atlas, inventory GET endpoints remain scoped to your customer catalogue.
  • There is no implicit fallback from customer catalogue to MusiMap Atlas — pass the query parameter explicitly.
  • List endpoints (GET /v1/tracks, etc.) remain customer-catalogue inventory only.

Endpoint-specific field documentation: Tracks, Artists, Releases.

Response source semantics

Public responses use a safe source.layer field with one of these values:

source.layer Meaning
customer_catalog Row from a catalogue your organisation ingested and owns.
musimap-atlas Row from the MusiMap Atlas read-only layer.

MusiMap internal UUIDs, catalogue codes, and storage details are never returned on the public API surface.

Ingestion and catalogues

  • All ingestion modes deliver into organisation-owned customer catalogues only.
  • MusiMap Atlas does not appear in GET /v1/catalogs — use that endpoint for your catalogues only.
  • There is no public API path to write or publish into MusiMap Atlas.

See Ingestions and Catalogues.

  • Catalogue search — MusiSearch with include_musimap_atlas.
  • Scopes — musimap-atlas.read.
  • Errors — musimap_atlas_not_entitled handling.