Catalogue search

Use MusiSearch to discover tracks in an accessible catalogue. The public endpoint is POST /v1/search/tracks. This is search and discovery, not technical inventory.

OAuth scopes

• search.read — run MusiSearch track search in an accessible catalogue.
• musimap-atlas.read — include MusiMap Atlas results when include_musimap_atlas is true. Also requires organisation entitlement musimap_atlas_read. See MusiMap Atlas.
• Request these scopes when exchanging client credentials.

Tag IDs

MusiSearch filters use stable tag_id UUIDs from GET /v1/taxonomies/tags. Tag labels are not query identifiers. Internal storage or database field names are never exposed in search responses.

Catalogue selection

By default, search uses your OAuth client's default catalogue from the token context. You may pass an optional catalog_id in the request body to search another catalogue you are allowed to access. Access is validated: your organisation must have membership for that catalogue. Arbitrary catalogues are rejected.

MusiMap Atlas

To search MusiMap's read-only shared intelligence layer alongside your catalogue, set include_musimap_atlas: true in the request body. When omitted or false, search remains customer-catalogue only.

• Requires musimap-atlas.read and organisation entitlement musimap_atlas_read.
• At equal relevance, customer catalogue results rank before MusiMap Atlas results.
• Each hit includes source.layer — customer_catalog or musimap-atlas.
• To read full details for an Atlas hit, use inventory GET with ?source=musimap-atlas.

See References → MusiMap Atlas for entitlement rules and inventory access.

Search request

Provide at least one of query or filters.

curl -X POST "https://api.musimap.com/v1/search/tracks" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "uplifting electronic",
    "catalog_id": "0190…",
    "filters": {
      "tags": {
        "required": [
          { "tag_id": "0190…", "score_min": 70, "score_max": 100 }
        ],
        "optional": [
          { "tag_id": "0190…", "score_min": 50 }
        ],
        "excluded": [
          { "tag_id": "0190…", "score_min": 60 }
        ]
      },
      "isrc": "GBUM71904911",
      "bpm_min": 100,
      "bpm_max": 140
    },
    "sort": "relevance",
    "include_musimap_atlas": true,
    "page": 1,
    "page_size": 20
  }'

Tag filter modes

• required — hard filters: the track must match every condition (tag score within the range).
• optional — soft filters: influence ranking when matched; they do not exclude tracks on their own.
• excluded — exclude tracks where the tag score falls within the range.

Score bounds

Each tag condition supports score_min and score_max on a 0–100 scale (matching stored MusiTag scores). At least one bound may be omitted; defaults depend on the filter mode when both are absent. Invalid ranges (e.g. score_min > score_max) are rejected.

Other supported filters

• isrc — exact ISRC within the requested catalogue.
• outer_id — your client outer ID from catalogue membership.
• bpm_min, bpm_max, energy_min, energy_max.

Use stable tag_id values from the taxonomy endpoint rather than label lists such as genres or moods. Unknown filter names are rejected.

Response shape

Responses use the standard MusiMap envelope with paginated data. Each result includes safe track, artist, optional release, optional MusiTag summary, and a final relevance score. Pipeline internals and storage paths are not returned.

{
  "status": 200,
  "message": "OK",
  "data": {
    "count": 1,
    "page": 1,
    "page_size": 20,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "results": [
      {
        "track": {
          "id": "0190…",
          "title": "Track title",
          "outer_id": "client-track-42",
          "isrc": "GBUM71904911"
        },
        "artists": [{ "id": "0190…", "name": "Artist" }],
        "release": { "id": "0190…", "title": "Release title" },
        "source": { "layer": "customer_catalog" },
        "audio_tagging": {
          "taxonomy_version": "v1",
          "tags": {
            "moods": [{ "uid": "mood_happy", "name": "Happy", "score": 82 }]
          }
        },
        "search": { "score": 0.91 }
      }
    ]
  }
}