Catalogue search

Use MusiSearch to discover tracks across accessible Workspace catalogues and, when entitled, MusiMap Atlas. The public endpoint is POST /v1/search/tracks. This is search and discovery, not technical inventory.

OAuth scopes

• search.read: run MusiSearch track discovery.
• atlas.read: required when include_atlas is true or targets includes atlas (plus matching organisation entitlement).

Tag IDs

MusiSearch filters use stable tag IDs from GET /v1/tagging/taxonomy (categories[].tags[].id). Pass those values as tag_id in filters. Tag labels are display metadata only.

Workspace and Atlas inclusion

• include_workspace: include organisation Workspace catalogues.
• include_atlas: include MusiMap Atlas (requires atlas.read).
• targets: alternative array of workspace and/or atlas.
• catalog_id / catalog_ids: optional Workspace catalogue overrides.

Each hit includes source.layer: workspace or atlas. When you need the full inventory record, retrieve it from GET /v1/workspace/tracks/{id} or GET /v1/atlas/tracks/{id} accordingly. Atlas and Workspace inventory are also browsable directly without searching first. See Atlas.

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…",
    "include_workspace": true,
    "include_atlas": true,
    "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",
    "page": 1,
    "page_size": 20
  }'

Tag filter modes

• required: hard filters: the track must match every condition.
• optional: soft filters: influence ranking when matched.
• excluded: exclude tracks where the tag score falls within the range.

Other supported filters

• isrc, outer_id.
• bpm_min, bpm_max, energy_min, energy_max.

Use taxonomy tag id values (as tag_id in filters) rather than label lists such as genres or moods. Unknown filter names are rejected.

Response shape

{
  "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": "workspace", "catalog_id": "0190…" },
        "audio_tagging": {
          "taxonomy_version": "v1",
          "tags": {
            "moods": [{ "uid": "mood_happy", "name": "Happy", "score": 82 }]
          }
        },
        "search": { "score": 0.91 }
      }
    ]
  }
}