topics#

GET /api/v1/topics API key required

List of curated topics — stable conceptual identifiers (e.g. star-wars, world-war-ii) with all aliases that map to them in the dataset, plus question counts. Requires X-API-Key (or Authorization: Bearer …). Cached for 1h server-side, with Cache-Control: public, s-maxage=3600.

Counts freshness: question counts are pre-aggregated and refreshed when the dataset changes.

Use this for typeahead search, dropdown filters, or as the first step of any “give me questions about X” flow.

Parameters#

Parameter	Type	Default	Description
lang	enum	en	Display language for `label`. Supported: `en`, `pl`. Other values return `400`.
q	string	—	Substring search across label, slug, and aliases (case-insensitive, 1–64 chars).
kind	enum	—	`tag` or `subcategory`. Limits results to one taxonomy layer.
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": "biography",
      "kind": "subcategory",
      "label": "Biography",
      "aliases": [
        "biography",
        "biographical-facts",
        "biographies",
        "biographical-data",
        "biographical-trivia",
        "celebrity-biography",
        "biographical-information"
      ],
      "count": 62541
    },
    {
      "slug": "nfl",
      "kind": "subcategory",
      "label": "NFL",
      "aliases": [
        "nfl",
        "nfl-football",
        "american-football"
      ],
      "count": 18290
    }
  ],
  "meta": {
    "count": 2,
    "total": 2161,
    "language": "en",
    "requestId": "req_..."
  },
  "_links": {
    "next": "/api/v1/topics?lang=en&limit=2&cursor=..."
  }
}

Performance#

p50 (warm): ~22ms
p95: ~46ms (sustained 50 RPS, 5-min baseline). Single-request warm: ~28ms.
Last measured: 2026-05-30
SLO: p95 < 500ms, error rate < 1%
Backed by pre-aggregated topic counts + 1h response cache.