subcategories#

GET /api/v1/subcategories Public — no key

The middle layer of QuizBase’s three-tier taxonomy: category (24 broad buckets like “Geography”, “Film”) → subcategory (1k+ faceted slugs like science-fiction-films, polish-geography, 19th-century-poetry) → tags (10k+ proper nouns and specifics).

Each subcategory entry has a display label and question count. Use this to build narrower filter dropdowns than /categories allows, especially for quiz round generators (“films and franchises”, “European geography”, etc.).

Public, no API key required. Cached for 1h server-side.

Listing scope: the response includes only subcategories appearing in 5 or more questions to filter out one-off artifacts. Filtering questions by any subcategory works for all values regardless — the threshold applies only to this discovery listing.

Counts freshness: counts are pre-aggregated and refreshed when the dataset changes. Refresh cadence is irregular at launch — focus is on dataset quality and new languages, not a fixed import schedule. New subcategories appear once they cross the 5-question threshold and the next refresh runs.

Parameters#

Parameter	Type	Default	Description
lang	enum	en	Display language for `label`. Supported: `en`, `pl`.
q	string	—	Substring search across slug and label (1–64 chars).
cursor	string	—	Pagination cursor from `_links.next`.
limit	int	100	Page size, 1–500.

Examples#

Response#

{
  "data": [
    { "slug": "biography", "label": "Biography", "count": 47124 },
    { "slug": "american-history", "label": "American History", "count": 13611 },
    { "slug": "world-history", "label": "World History", "count": 9520 }
  ],
  "meta": {
    "count": 3,
    "total": 36200,
    "language": "en",
    "requestId": "req_..."
  },
  "_links": {
    "next": "/api/v1/subcategories?lang=en&limit=3&cursor=..."
  }
}

meta.total is the global count of subcategories meeting the ≥5 threshold (currently ~36k); meta.count is how many fit on this page.

Filtering questions by subcategory#

curl "https://quizbase.runriva.com/api/v1/questions/random?subcategory=science-fiction-films&amount=10" 
  -H "X-API-Key: qb_pk_..."

Single-value filter only. For OR logic across multiple subcategories, prefer ?topic= with curated topics — it resolves aliases and matches across both layers in one shot.

Performance#

p50 (warm): ~23ms
p95: ~29ms (sustained 50 RPS, baseline)
Last measured: 2026-05-07
SLO: p95 < 500ms, error rate < 1%
Backed by a pre-aggregated counts table (filtered to ≥5 questions per subcategory) + 1h response cache.