SFX Taxonomy

Endpoint

Returns the full SFX category hierarchy: ~12 broader groups, ~82 UCS-style categories, and ~722 subcategories. Use this to build browse UIs without hard-coding the taxonomy in your client. The hierarchy is groups broader_category → category → subcategory, mirroring how the AudioScape catalog is organized.

Drive search using the values returned here: filters.categories and filters.subcategories on /v1/sfx/search. Broader categories are intended for navigation only — clicking one should expand its child categories, not fire a search.

Headers

Response

Returns the full hierarchy plus a counts breakdown.

{
  "taxonomy": [
    {
      "broader_category": "string",
      "categories": [
        {
          "category": "string",
          "subcategories": ["string", ...]
        }
      ]
    }
  ],
  "meta": {
    "broader_category_count": number,
    "category_count": number,
    "subcategory_count": number
  }
}

Example: Sound picker tree

Power a sound picker — for a Studio plugin, an in-game admin panel, or a creator tool — by walking the taxonomy into a tree view. Assumes a client from the Quickstart.

-- Studio plugin sound picker: render a category tree
local taxonomy, err = client:getSfxTaxonomy()
if not taxonomy then warn(err) return end

for _, group in taxonomy.taxonomy do
    local header = Instance.new("TextLabel")
    header.Text = group.broader_category
    header.Parent = treeFrame -- your ScrollingFrame for the tree

    for _, cat in group.categories do
        local button = Instance.new("TextButton")
        button.Text = `  {cat.category} ({#cat.subcategories})`
        button.Parent = treeFrame

        button.Activated:Connect(function()
            -- Drive /sfx/search with filters.categories = { cat.category }
        end)
    end
end

Caching

The taxonomy changes rarely — only when we ship new categories. Each Lambda container memoizes the response for 10 minutes, so repeat requests are fast. On your end you can safely cache it for the lifetime of the game session.

Error Responses

{
  "error": "Invalid API key"
}

{
  "message": "Too Many Requests"
}