Catalogue search

Use catalogue search to find tracks across accessible Workspace catalogues and, when entitled, MusiMap Atlas. The public endpoint is POST /v1/search/tracks. Criteria are explicit: title and artist text, taxonomy tags, identifiers, and audio-feature ranges.

OAuth scopes

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

Tag IDs

Tag 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": "Beat It Michael Jackson",
    "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": "score",
    "sort_direction": "desc",
    "page": 1,
    "page_size": 20
  }'

Text matching

query is required eligibility when present. After Unicode case-folding and collapsed whitespace, every term must appear as a whole token in the track title, the primary artist credit, or both. Terms do not need to sit in the same field or next to one another, so Beat It Michael Jackson matches title Beat It and artist Michael Jackson. Combine it with BPM, tags, or identifiers using AND: every required condition must hold. Additional title/artist filters (title_contains, title_exact, artist_contains, artist_exact) are also AND constraints.

Tag filter modes

• required: eligibility. The track must match every required condition.
• optional: preference. Eligible tracks remain in the result; optional matches change search.score.
• 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.
• title_contains, title_exact, artist_contains, artist_exact.

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

Preference score

search.score is a value from 0 to 100. Required criteria decide whether a track is returned at all. When there are no optional tag or numeric preferences, every eligible result scores 100. With optional preferences, the score is the share of the available optional weight that the track actually earned (clamped to 0–100). A score of 0 with optional preferences means none of those preferences matched; the track is still eligible.

Sort and pagination

Default order is score descending, then immutable track_id ascending. Supported sort values: score, track_id, title, artist, bpm, updated_at. relevance is a compatibility alias for score. Optional sort_direction is asc or desc. updated_at is the analysis projection timestamp and can move while ingest is active. Pagination is over logical tracks after collapsing multiple analyses per track, not an unordered sample.

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": "Beat It",
          "outer_id": "client-track-42",
          "isrc": "GBUM71904911"
        },
        "artists": [{ "id": "0190…", "name": "Michael Jackson" }],
        "release": { "id": "0190…", "title": "Thriller" },
        "source": { "layer": "workspace", "catalog_id": "0190…" },
        "audio_tagging": {
          "taxonomy_version": "v1",
          "tags": {
            "moods": [{ "uid": "mood_happy", "name": "Happy", "score": 82 }]
          }
        },
        "search": { "score": 100 }
      }
    ]
  }
}