QuizBase

List of 24 top-level categories with i18n labels. USE WHEN: building a category picker, validating ?category= input. Stable enum (rarely changes). For higher-resolution browsing → quizbase_subcategories or quizbase_topics.

Returns supported language whitelist (ISO 639-1) with question counts per language. USE WHEN: showing language picker, validating ?lang= input, deciding fallback. Day 1: en + pl.

Cursor-paginated browse over the catalog. Quality-first: by default excludes needs_review=true (use quality='all' for full pool).

USE WHEN: full catalog sync, delta sync (updated_since), exhaustive enumeration by filter. NOT WHEN: you only need N random samples (use quizbase_random) or a single record (use quizbase_question_by_id).

PAGINATION: stable cursor over id UUIDv7 DESC. First call: omit cursor. Next: pass meta.nextCursor. Stop when nextCursor is null.

KEY FILTERS (full parity with REST):

• lang: ISO 639-1, default "en". Supported: en, pl.

• category (slug), difficulty (trivial|easy|medium|hard|expert — LLM-calibrated Plan 121), type (multiple|boolean), subcategory (raw slug).

• tags (AND), tags_any (OR, max 10): raw tag slugs.

• topic (curated, alias resolver), topics_any (OR over curated): higher precision than tags.

• regions (cultural affinity, AND): empty = no cultural advantage assumed. Lowercase ISO 3166-1 alpha-2 ('us', 'pl', 'gb') + cultural codes ('jewish', 'christian-catholic', 'islam'). Filter for content statistically more likely known by residents/members. Discover via quizbase_regions.

• source: one of 12 (opentdb, opentriviaqa, kqa-pro, entityq, mintaka, mkqa, nq-open, creak, qasc, arc, webq, quizbase).

• license (SPDX): e.g. CC-BY-SA-4.0, MIT.

• quality: 'high' (default) excludes needs_review=true; 'all' for full approved pool. When 'all', each question gains a "quality" field with value 'high' or 'needs_review'.

• updated_since (ISO 8601): only questions updated after this — for delta sync caches.

PAGINATION + COUNTING:

• cursor (string): from previous meta.nextCursor. Omit for page 1.

• limit (1-100, default 20).

• count: estimate (default, EXPLAIN-based ~5-20ms, ±5-50%) | none (skip).

OUTPUT: { questions: [...], meta: { count, countMode, language, nextCursor, totalEstimate? } }. Each question carries full per-record attribution (source, author, license, licenseVersion, licenseUrl, sourceId, url, modifications, lastModified) — identical shape to REST /api/v1/questions.

ATTRIBUTION REQUIRED if you redistribute. Credit each question using its own attribution object — see license + licenseUrl + modifications fields per record.

COMMON MISTAKES: not passing the cursor on subsequent calls (you'll re-read page 1); polling without updated_since when doing delta sync.

Fetch one question with FULL per-record attribution (source, author, license, modifications, lastModified, sourceId, url) and quality: "high" | "needs_review" (always present — deep-link semantic means full row). USE WHEN: deep link to a question, full provenance lookup for redistribution, cache refresh, moderation inspection. INPUTS: id (UUID), lang (affects category.name and label translations only). 404 returned via {question: null, error: "not_found"} — id may be invalid, pending/rejected, canonical-duplicate, or tombstoned.

Fetch N random trivia questions matching filters. Quality-first: by default excludes needs_review=true (use quality='all' to include for audit/research).

USE WHEN: building a quiz, sampling content for warmup, generating practice sets. NOT WHEN: you need a specific question ID (use quizbase_question_by_id) or want to explore a topic deeply with facets (use quizbase_topic_by_slug).

KEY FILTERS:

• amount: 1-50, default 10.

• lang: ISO 639-1. Default "en". Supported: en, pl. Strict — unknown language returns 400.

• category (slug): e.g. geography, history, science-and-nature. Full list via quizbase_categories.

• difficulty: trivial | easy | medium | hard | expert. LLM-calibrated (Plan 121 Pipeline I, post-rescore). Pre-rescore records hold importer placeholder (mostly "medium" for factoid sources).

• type: multiple | boolean (default both; no text_input in random).

• regions (cultural affinity, AND): empty in data = no cultural advantage assumed. Lowercase ISO 3166-1 alpha-2 ('us', 'pl', 'gb') + cultural codes ('jewish', 'christian-catholic', 'islam'). Filter for content statistically more likely known by residents/members. Discover via quizbase_regions.

• source: filter by source database (one of 12: opentdb, opentriviaqa, kqa-pro, entityq, mintaka, mkqa, nq-open, creak, qasc, arc, webq, quizbase). Use to exclude noisy auto-generated sources.

• license (SPDX): CC-BY-SA-4.0 | CC-BY-SA-3.0 | MIT | etc. Restrict to redistribution-friendly content.

• topic (curated slug): higher precision than tags. Alias resolver matches subcategories+tags. List via quizbase_topics.

• topics_any: OR over curated topics, max 10.

• tags (AND), tags_any (OR), subcategory: raw taxonomy. Use topic if available.

• quality: 'high' (default, recommended) excludes needs_review=true. Use 'all' only for audit/research — when 'all', each question gains a "quality" field with value 'high' or 'needs_review' so you can tell which records were flagged.

• exclude (UUIDs, max 250): de-dupe within a quiz session.

OUTPUT: { questions: [...], meta: { count, language } }. Each question carries full per-record attribution (source, author, license, licenseVersion, licenseUrl, sourceId, url, modifications, lastModified) — identical shape to REST /api/v1/questions/random.

ATTRIBUTION REQUIRED if you redistribute. CC-BY-SA modifications must be credited per § 3(a)(1)(B) using each question's own attribution object.

COMMON MISTAKES: forcing lang='pl' for a global audience (use 'en' default); skipping quality (default already excludes flagged content — only pass quality='all' for audit); using tags when a curated topic exists (worse precision).

Discover region codes used by the catalog. Cultural affinity — a question is tagged with a region if residents of that country, or members of that cultural/religious group, are statistically more likely to know the answer (NOT geography of the subject). USE WHEN: planning a quiz targeting users from a specific country or cultural background, exploring "what regions are represented". OUTPUT: array of {code, kind, label, count} sorted by count DESC. INPUTS: lang (en|pl), q (substring on code/label), kind (country|cultural), cursor, limit (max 500). Pair with quizbase_random or quizbase_list using regions:[...] to fetch matching questions.

Submit a content correction, copyright concern, or factual error report. USE WHEN: user (via your interface) flags a wrong answer, broken translation, attribution issue, or DMCA concern. INPUTS: at least one of (questionId UUID, questionText, questionUrl), type (translation|factual|inappropriate|attribution|other), comment (optional, max 2000), reporterEmail (optional). OUTPUT: 202 with reportId. Per-IP rate limit 5/min — overflow returns {ok:false, error:"rate_limit"}.

Public catalog counters with live breakdowns by language, source, category, difficulty, topic, tag.

USE WHEN: showing catalog overview, picking a category programmatically, building landing copy, deciding "do we have enough X-content for this quiz".

OUTPUT FIELDS:

• total: approved questions in 'en' + 'pl'.

• byLanguage: { en: N, pl: N }.

• bySource: { entityq: N, mintaka: N, 'kqa-pro': N, ... } — 12 keys, one per source database (Plan 113 S5 made this live data).

• byDifficulty: { trivial: N, easy: N, medium: N, hard: N, expert: N, unrated: N } — null difficulty mapped to 'unrated'. trivial/expert populated by LLM rescore (Plan 121).

• byCategory: top 24 with localized names.

• byTopic / byTag: top 30 curated topics + top 30 tags with localized labels.

• meta: { generatedAt: ISO 8601, language }.

INPUTS: lang (default "en") affects byCategory[].name and byTopic[].label / byTag[].label.

DATA FRESHNESS: snapshot regenerated daily (~03:00 UTC) + on demand after batch imports. generatedAt shows when. Counts stable ±0.01% between snapshots.

COMMON MISTAKES: polling stats every request (cache it on your side; 5-min Redis TTL on ours); treating bySource keys as stable enum (use quizbase_languages / quizbase_categories for canonical input enums).

Raw subcategory dump (LLM-organic kebab-case, Plan 55 middle taxonomy layer) with display label and count. USE WHEN: navigating between top-level category and individual tags, exploring topic structure. Filter questions via quizbase_random?subcategory=. INPUTS: q, cursor, limit (max 500).

Raw tag dump (10k+ entries) with display label and question count. USE WHEN: building a tag picker, searching "is X a tag", running analytics. Curated higher-level groupings → quizbase_topics. INPUTS: q (substring), cursor, limit (max 500).

Fetch one curated topic with facets (byCategory, byDifficulty, byLanguage, coOccurringTags, coOccurringSubcategories) and 3 sample questions. USE WHEN: zooming into a topic, deciding multi-round quiz structure. Returns {topic: null, error: "not_found"} when slug is unknown.

Discover curated topics (2,184 entries with aliases). USE WHEN: planning a multi-round quiz, exploring "what is available about X", showing topic browser. Sorted by count DESC, slug ASC. Cursor-paginated. INPUTS: q (substring on label/alias), kind (tag|subcategory), cursor, limit (max 500).