Taxonomy

MusiTag tag IDs from GET /v1/tagging/taxonomy for MusiSearch filters.

Use the taxonomy endpoint to retrieve stable tag id values for MusiTag and MusiSearch. The public endpoint is GET /v1/tagging/taxonomy. Tag names are display metadata only; always filter search with the tag id (as tag_id in MusiSearch filters), not labels.

OAuth scope

  • Require tagging.read.
  • Request this scope when exchanging client credentials. See Scopes.

List tags

curl "https://api.musimap.com/v1/tagging/taxonomy?category=moods&tag_name=happy" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Query filters

  • category: exact category slug (e.g. moods, genres).
  • tag_name: case-insensitive substring match on the tag label.

Filters can be combined. Results remain grouped by category slug. Count fields reflect the filtered result set, not the full taxonomy totals. An empty match returns an empty categories array with zero counts.

Response shape

Tags are grouped by category. Each category exposes slug (stable machine identifier), name (human-readable label), and tag_count (tags returned in that category). Taxonomy-level tag_count and category_count summarise the filtered response. Each tag exposes id and name.

Pagination is not needed here. The MusiTag taxonomy is small enough that the full filtered set is returned in one response. 

{
  "status": 200,
  "message": "OK",
  "data": {
    "taxonomy": {
      "id": "musitag",
      "version": "v1",
      "tag_count": 42,
      "category_count": 1
    },
    "categories": [
      {
        "slug": "moods",
        "name": "Moods",
        "tag_count": 42,
        "tags": [
          { "id": "0190…", "name": "Happy" }
        ]
      }
    ]
  }
}

Pass taxonomy tag id values in POST /v1/search/tracks under filters.tags.required, optional, or excluded as tag_id. See the Catalogue search documentation for score bounds and catalogue selection.

Related: Tagging (live tagging and GET /v1/tagging/matrix).