categories#

GET /api/v1/categories API key required

Returns the full list of categories with localized name. Requires X-API-Key (or Authorization: Bearer …). Cached for 1h server-side. Responses are sent with Cache-Control: private, no-store — an authenticated response must never be stored by a shared cache, so handle any client-side caching yourself.

Use this for dropdowns, filter UIs, and landing page counts. Categories change rarely — fetch once, cache for hours.

Parameters#

Parameter	Type	Default	Description
lang	enum	en	Supported: `en`, `pl`. Sets the language of `name`. Falls back to English where a category translation is missing. Any other value returns `400`.

Examples#

Response#

{
  "data": [
    { "id": 1, "slug": "general-knowledge", "name": "Wiedza ogólna", "opentdbId": 9, "parentId": null },
    { "id": 3, "slug": "film", "name": "Rozrywka: Film", "opentdbId": 11, "parentId": null },
    { "id": 14, "slug": "geography", "name": "Geografia", "opentdbId": 22, "parentId": null },
    { "id": 15, "slug": "history", "name": "Historia", "opentdbId": 23, "parentId": null }
  ],
  "meta": { "count": 24, "language": "pl", "requestId": "req_..." }
}

{
  "type": "https://quizbase.runriva.com/errors/invalid_query_param",
  "title": "Invalid query parameters",
  "status": 400,
  "detail": "lang: lang \"xyz\" is not supported. Supported: en, pl",
  "instance": "/api/v1/categories?lang=xyz",
  "code": "invalid_query_param",
  "errors": [
    { "path": "lang", "message": "lang \"xyz\" is not supported. Supported: en, pl" }
  ]
}

Performance#

p50 (warm): ~22ms
p95: ~43ms (sustained 50 RPS, 5-min baseline). Single-request warm: ~30ms.
Last measured: 2026-05-30
SLO: p95 < 500ms, error rate < 1%
Server-side response cache (1h) in front of a pre-aggregated table — warm requests are served without touching the database.