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 for reads and writes. 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.

Selecting a catalogue on Workspace and ingestions

Catalogue selection uses the catalog_id query parameter on Workspace inventory endpoints (lists, creates, detail reads, and patches) and on POST /v1/ingestions. Resource bodies stay focused on the resource fields themselves. 

# Read from catalogue B (unbound client)
curl "https://api.musimap.com/v1/workspace/tracks?catalog_id=$CATALOG_B" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Create a track in catalogue B (unbound client), with optional outer_id
curl -X POST "https://api.musimap.com/v1/workspace/tracks?catalog_id=$CATALOG_B" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Demo track","outer_id":"external-track-123"}'
  • Omit catalog_id: bound clients use their binding; unbound clients use the organisation default catalogue.
  • Invalid UUID: HTTP 400 with data.error_code: "invalid_request".
  • Other organisation / inaccessible catalogue: HTTP 403 with data.error_code: "catalogue_forbidden".
  • Bound client selects another catalogue: HTTP 403 with data.error_code: "catalogue_forbidden".
  • No resolvable catalogue (unbound, no default): HTTP 422 with data.error_code: "missing_catalogue_context" on creates.
  • Patches / detail GETs: pass catalog_id when the resource lives in a non-default catalogue. Selection authorises access; it does not move the resource to another catalogue. Workspace entities have no public DELETE.
  • Ingestion create: catalog_id may also appear in the JSON body. If both query and body are set, the values must match or the API returns invalid_request.
  • Catalogue selection never bypasses OAuth scopes (catalog.read / catalog.write / ingestion.*) or entitlements.
  • Authentication: GET /v1/me catalogue fields.
  • Atlas: read-only Atlas catalogue (not listed here).
  • Errors: catalogue_forbidden, missing_catalogue_context.