GET /v1/topics/:slug#

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 across the five LLM-calibrated difficulty levels? mostly films, or also books and games?“.

Requires X-API-Key (or Authorization: Bearer …). Cached for 1h server-side.

Path parameters#

Query parameters#

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": { "trivial": 12, "easy": 187, "medium": 514, "hard": 638, "expert": 248 },
    "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 5 LLM-calibrated keys: trivial, easy, medium, hard, expert. Only keys with count > 0 are populated; missing keys mean zero. 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: ~110ms (sustained 50 RPS; estimated — not in load mix). Single-request warm: ~60ms.
• Last measured: 2026-05-27
• SLO: p95 < 500ms, error rate < 1%
• Cached for 1h after first request per (slug, lang) pair.

See also#

• GET /v1/topics — discover topics by substring or kind
• GET /v1/questions/random?topic=:slug — fetch random questions for a topic
• GET /v1/questions?topic=:slug&lang=… — paginated browse of all questions for a topic
• Multi-round quiz tutorial — end-to-end round composition using topics + facets