Catalogues

List catalogues available to your OAuth client with GET /v1/catalogs.

Before you ingest or query tracks, confirm which catalogues your OAuth client can access. Catalogue discovery is separate from token identity: use GET /v1/catalogs to list accessible catalogues and GET /v1/me to inspect the current token context.

How catalogue access works

  • Bound client: the OAuth client has a catalogue binding. It may only use that catalogue. A request for a different catalog_id returns catalogue_forbidden.
  • Unbound client: catalog_id on /v1/me is null. The client may select among organisation catalogues. When a request omits catalog_id, the organisation default catalogue is used.
  • GET /v1/catalogs lists catalogues available under the current access rules.
  • MusiMap Atlas access is controlled by the atlas.read scope and the matching organisation entitlement. It is not listed as a customer catalogue row. See Atlas.
OAuth scope

Catalogue endpoints require the catalog.read scope. Request this scope when exchanging client credentials.

catalog_id: null means unbound

On GET /v1/me, a null catalog_id means the OAuth client is unbound, not that the organisation has no catalogues. Inspect catalog_access_mode, default_catalog_id, and GET /v1/catalogs.

List accessible catalogues

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

Example response:

{
  "status": 200,
  "message": "OK",
  "data": {
    "count": 1,
    "results": [
      {
        "id": "019c41e3-6532-7020-8f81-b9c9405384aa",
        "name": "Main catalogue",
        "description": "Primary catalogue",
        "is_default": true,
        "counts": {
          "tracks": 12840,
          "artists": 2104,
          "releases": 3560,
          "works": 980,
          "labels": 412
        }
      }
    ]
  }
}

Bound clients receive only the bound catalogue. Unbound clients receive the organisation catalogues available under access rules. When none are available, the API returns HTTP 200 with count: 0 and an empty results array.

Get one catalogue

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

Returns HTTP 404 with data.error_code: "not_found" when the catalogue does not exist or is outside your client's accessible set. This avoids leaking whether another tenant owns the id.

Response fields

  • id: public catalogue UUID.
  • name: human-readable catalogue name.
  • description: optional text, may be null.
  • is_default: true when this catalogue is the organisation default (or matches the token context).
  • counts: optional precomputed entity counts (tracks, artists, releases, works, labels) when available. Omitted or null when counts are not available.
  • Authentication: GET /v1/me catalogue fields.
  • Atlas: read-only Atlas catalogue (not listed here).
  • Errors: catalogue_forbidden, missing_catalogue_context.