Taxonomy

MusiTag tag IDs grouped by category for MusiSearch filters.

Use the taxonomy endpoint to retrieve stable tag_id values for MusiTag and MusiSearch. The public endpoint is GET /v1/taxonomies/tags. Tag names are display metadata only; always filter search with tag_id, not labels.

OAuth scope

  • taxonomy.read — read MusiTag taxonomy tags grouped by category.
  • Request this scope when exchanging client credentials.

List tags

curl "https://api.musimap.com/v1/taxonomies/tags?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 category_slug (stable machine identifier), category_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 tag_id and tag_name only. Internal projection fields used only inside MusiMap services are not part of the public API.

Pagination is not used in V1. The MusiTag taxonomy is small (currently about 267 tags), so 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": [
      {
        "category_slug": "moods",
        "category_name": "Moods",
        "tag_count": 42,
        "tags": [
          { "tag_id": "0190…", "tag_name": "Happy" }
        ]
      }
    ]
  }
}

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