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

  • An OAuth client may have access to zero, one, or (in future) many catalogues.
  • GET /v1/catalogs answers: which catalogues are available to this client?
  • GET /v1/me may include a catalog_id field. That value is the default or current catalogue context for the token, not necessarily the full list of accessible catalogues.
  • Per-request catalogue selection uses the token's current catalogue context from /v1/me. Some endpoints also accept an explicit catalog_id when your integration has access to multiple catalogues.
V1 data model note

Today, many OAuth clients are bound to at most one catalogue in IAM. The list response still uses a count + results array so your integration stays compatible when multi-catalogue access ships.

OAuth scope

Catalogue endpoints use the catalog.read scope. Request this scope when exchanging client credentials. Tenant and catalogue access is enforced on every call.

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
      }
    ]
  }
}

When no catalogue is available to the client, 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 matches the token's current/default catalog_id context from /v1/me.

Admin-only IAM fields (organisation internals, soft-delete flags, audit timestamps) are not exposed.

MusiMap Atlas is not listed in catalogue discovery — it is a separate read-only layer. See MusiMap Atlas.

  • Authentication — obtain tokens and read /v1/me.
  • Errors — invalid_token and not_found handling.
  • Ingestions — create an ingestion and track delivery (when enabled for your client).
  • MusiMap Atlas — read-only shared layer (not listed here).