:slug#

GET /api/v1/topics/:slug Public — no key

Detail view of a single curated topic. Returns the topic record (label, aliases, total count) plus facets broken down by category, difficulty, and language, the top co-occurring tags and subcategories, and 3 sample questions so you can preview the topic before composing a quiz round.

This is the “what’s actually in this topic” endpoint — the answer to “we have 1,599 Star Wars questions, but how do they break down? are they mostly easy / medium / hard? mostly films, or also books and games?“.

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

Path parameters#

Parameter	Type	Default	Description
slug *	kebab-case	—	Topic slug from [GET /v1/topics](/docs/api/topics). Aliases also resolve — `/v1/topics/star-wars-saga` redirects to the canonical `star-wars` topic.

Query parameters#

Parameter	Type	Default	Description
lang	enum	en	Display language for `label` (topic and all facet labels). Supported: `en`, `pl`. Other values return `400`.

When you’ll get 404#

The slug doesn’t match any curated topic or alias
The topic was retired (very rare; we keep aliases pointing to surviving topics where possible)

Examples#

Response#

{
  "topic": {
    "slug": "star-wars",
    "kind": "tag",
    "label": "Star Wars",
    "aliases": ["star-wars"],
    "count": 1599
  },
  "facets": {
    "byCategory": [
      { "slug": "film", "name": "Entertainment: Film", "count": 1191 },
      { "slug": "books", "name": "Entertainment: Books", "count": 202 },
      { "slug": "celebrities", "name": "Celebrities", "count": 99 }
    ],
    "byDifficulty": { "easy": 5, "medium": 1247, "hard": 347 },
    "byLanguage": { "en": 1599, "pl": 1575 },
    "coOccurringTags": [
      { "slug": "george-lucas", "label": "George Lucas", "count": 813 },
      { "slug": "lucasfilm", "label": "Lucasfilm", "count": 476 },
      { "slug": "a-new-hope", "label": "A New Hope", "count": 250 }
    ],
    "coOccurringSubcategories": [
      { "slug": "science-fiction", "label": "Science Fiction", "count": 594 },
      { "slug": "space-opera", "label": "Space Opera", "count": 523 },
      { "slug": "star-wars-franchise", "label": "Star Wars Universe", "count": 385 }
    ]
  },
  "samples": [
    { "id": "019dc5f7-02a5-774f-b627-3b4c25fb7f61", "text": "Is Voldemort a character in the Star Wars book series?", "type": "boolean", "difficulty": "medium", "language": "en" }
  ],
  "meta": { "language": "en", "requestId": "req_..." }
}

{
  "type": "https://quizbase.runriva.com/errors/topic_not_found",
  "title": "Topic not found",
  "status": 404,
  "detail": "No topic with slug=non-existent-topic.",
  "instance": "/api/v1/topics/non-existent-topic",
  "code": "topic_not_found"
}

Response fields#

topic — same shape as a single entry from /v1/topics: {slug, kind, label, aliases, count}. kind is tag or subcategory depending on which discovery layer the topic was promoted from.
facets.byCategory — top-level category breakdown for this topic. name is localized to your ?lang=. Sorted by count desc.
facets.byDifficulty — fixed shape with easy, medium, hard keys (only those present). unrated does not appear here even when present in the catalog.
facets.byLanguage — counts per supported language (en, pl at launch). Tells you whether a topic has parity across languages.
facets.coOccurringTags / coOccurringSubcategories — top tags and subcategories that appear alongside this topic in questions, sorted by frequency. Use this to suggest related topics in a quiz UI (“if you liked Star Wars, try…”) or to compose multi-tag rounds.
samples — 3 example questions (id, text, type, difficulty, language). Just a preview — fetch full content via /v1/questions or /v1/questions/random?topic=….

Performance#

p50 (warm): ~50ms
p95: ~60ms (sustained)
Last measured: 2026-05-07
SLO: p95 < 500ms, error rate < 1%
Cached for 1h after first request per (slug, lang) pair.