tags#

GET /api/v1/tags Public — no key

List of raw tags as they appear in the question dataset (e.g. darth-vader, world-war-ii, 19th-century-poetry). Each entry has a display label (translated to your ?lang=) and a count of approved questions carrying it.

This is the lowest layer of the taxonomy. For most quiz apps prefer /v1/topics: it’s a curated layer with aliases that group equivalent raw tags. Use /tags only when you specifically need raw access (research, dataset analysis, building your own taxonomy).

Public, no API key required. Cached for 1h server-side (Cache-Control: public, s-maxage=3600).

Listing scope: the response includes only tags appearing in 5 or more questions to filter out one-off artifacts. Filtering questions by any tag (e.g. /v1/questions?tag=foo) works for all tags 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 tags 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`. Other values return `400`.
q	string	—	Substring search across slug and label (case-insensitive, 1–64 chars).
cursor	string	—	Slug of the last item from the previous page. Use `_links.next` to navigate.
limit	int	100	Page size, 1–500.

Examples#

Response#

{
  "data": [
    { "slug": "united-states", "label": "United States", "count": 7673 },
    { "slug": "nfl", "label": "NFL", "count": 6240 },
    { "slug": "us-presidency", "label": "US Presidency", "count": 5894 }
  ],
  "meta": {
    "count": 3,
    "total": 87559,
    "language": "en",
    "requestId": "req_..."
  },
  "_links": {
    "next": "/api/v1/tags?lang=en&limit=3&cursor=..."
  }
}

Sort: count DESC, slug ASC. Pagination via _links.next when available. meta.total is the global count of tags meeting the ≥5 threshold (currently ~87k); meta.count is how many fit on this page.

Filtering questions by tag#

# AND logic — both must match
curl "https://quizbase.runriva.com/api/v1/questions/random?tags=darth-vader,skywalker&amount=10" 
  -H "X-API-Key: qb_pk_..."

# OR logic — either matches
curl "https://quizbase.runriva.com/api/v1/questions/random?tags_any=darth-vader,skywalker&amount=10" 
  -H "X-API-Key: qb_pk_..."

Performance#

p50 (warm): ~22ms
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 tag) + 1h response cache.