QuizBase

Fetch N random trivia questions matching filters. Quality-first: by default excludes questions flagged for review (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. Records not yet LLM-rated hold the 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 (array): include only these source databases (one or more of 12: opentdb, opentriviaqa, kqa-pro, entityq, mintaka, mkqa, nq-open, creak, qasc, arc, webq, quizbase). - exclude_source (array): drop these sources, e.g. ["entityq"] for human-curated only. Applied after source. - 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) = cleanest, most broadly-useful. 'standard' = broader pool incl. niche/too-specific (more volume). 'all' = audit/research, includes flagged — when 'all', each question gains a "quality" field ('high' or 'needs_review'). - 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).

{
  "type": "object",
  "properties": {
    "amount": {
      "default": 10,
      "description": "Number of random questions to return. Range 1-50, default 10. Each call samples independently — pass `exclude` with previously-seen UUIDs to avoid duplicates across calls within one session.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "lang": {
      "default": "en",
      "description": "Question language as ISO 639-1 code. Default \"en\". Supported: en, pl. Strict — unknown language returns 400. The same `id` may exist in multiple languages (translated rows share `id`).",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    },
    "category": {
      "description": "Top-level category slug (kebab-case) — e.g. `geography`, `history`, `science-and-nature`. 24 categories total. Use `quizbase_categories` for the full canonical list with localized names.",
      "type": "string"
    },
    "difficulty": {
      "description": "LLM-calibrated 5-level difficulty. trivial=common-knowledge, easy=approachable, medium=requires-thought, hard=needs-domain-context, expert=specialist. Records not yet LLM-rated hold the importer placeholder (mostly \"medium\" for factoid sources).",
      "type": "string",
      "enum": [
        "trivial",
        "easy",
        "medium",
        "hard",
        "expert"
      ]
    },
    "type": {
      "description": "\"multiple\" = 1 correct + 3 distractors. \"boolean\" = True/False (Prawda/Fałsz in pl).",
      "type": "string",
      "enum": [
        "multiple",
        "boolean"
      ]
    },
    "subcategory": {
      "description": "Raw subcategory slug (kebab-case). Prefer `topic` for OR semantics + alias resolver.",
      "type": "string"
    },
    "tags": {
      "description": "AND-logic: question must have ALL these tag slugs (kebab-case)",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tags_any": {
      "description": "OR-logic: question must have AT LEAST ONE of these tag slugs",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "topic": {
      "description": "Curated topic slug — alias resolver matches subcategories and tags",
      "type": "string"
    },
    "topics_any": {
      "description": "OR-logic over curated topic slugs (resolves aliases)",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "regions": {
      "description": "Cultural affinity codes. 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). Lowercase ISO 3166-1 alpha-2 (`us`, `pl`, `gb`) plus cultural codes (`jewish`, `christian-catholic`, `islam`). AND-logic. Empty array in DB = universally accessible (no cultural advantage assumed). Use `quizbase_regions` for the full catalog with counts.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "source": {
      "description": "Include only these source databases (one or more of 12: opentdb, opentriviaqa, mkqa, mintaka, kqa-pro, entityq, nq-open, creak, qasc, arc, webq, quizbase). Matches `attribution.source` per question.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "arc",
          "creak",
          "entityq",
          "kqa-pro",
          "mintaka",
          "mkqa",
          "nq-open",
          "opentdb",
          "opentriviaqa",
          "qasc",
          "quizbase",
          "webq"
        ]
      }
    },
    "exclude_source": {
      "description": "Exclude these source databases. Use to drop noisy auto-generated sources, e.g. `[\"entityq\"]` for human-curated only. Applied after `source` if both are present.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "arc",
          "creak",
          "entityq",
          "kqa-pro",
          "mintaka",
          "mkqa",
          "nq-open",
          "opentdb",
          "opentriviaqa",
          "qasc",
          "quizbase",
          "webq"
        ]
      }
    },
    "license": {
      "description": "SPDX license string (e.g. CC-BY-SA-4.0, CC-BY-SA-3.0, MIT). Filter for redistribution-friendly content. Each question carries its own `attribution.license`.",
      "type": "string",
      "enum": [
        "CC-BY-SA-4.0",
        "CC-BY-SA-3.0",
        "CC-BY-4.0",
        "MIT",
        "proprietary"
      ]
    },
    "quality": {
      "default": "high",
      "description": "Quality preset. \"high\" (default) returns only the cleanest, most broadly-useful questions. \"standard\" broadens to the full reviewed pool incl. niche/too-specific (more volume). \"all\" includes everything flagged for review too — for audit, research, or BY-SA dump consumption.",
      "type": "string",
      "enum": [
        "high",
        "standard",
        "all"
      ]
    },
    "exclude": {
      "description": "List of question UUIDs to exclude from random sampling. Use to de-dupe within a quiz session — pass IDs you already showed the user so they are not repeated. Max 250 IDs per call.",
      "maxItems": 250,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "questions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "text"
        ],
        "additionalProperties": {}
      },
      "description": "Array of trivia questions, each carries full per-record attribution."
    },
    "meta": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "language": {
          "type": "string"
        }
      },
      "required": [
        "count",
        "language"
      ],
      "additionalProperties": {},
      "description": "Response metadata: how many questions returned and which language."
    }
  },
  "required": [
    "questions",
    "meta"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Cursor-paginated browse over the catalog. Quality-first: by default excludes questions flagged for review (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), 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 (array): include only these of 12 (opentdb, opentriviaqa, kqa-pro, entityq, mintaka, mkqa, nq-open, creak, qasc, arc, webq, quizbase). - exclude_source (array): drop these sources, e.g. ["entityq"]. Applied after source. - license (SPDX): e.g. CC-BY-SA-4.0, MIT. - quality: 'high' (default) = cleanest, most broadly-useful. 'standard' = broader pool incl. niche/too-specific. 'all' = full pool incl. flagged; when 'all', each question gains a "quality" field ('high' or 'needs_review'). - updated_since (ISO 8601): only questions updated after this — for delta sync caches. BATCH + TRANSLATION MAPPING: - ids (up to 250): fetch those exact records in one call (anti-repeat, deep-links, restoring a saved set). Terminal selector — browse filters and cursor are ignored. Missing ids → meta.missing. - content_language (en|pl): with ids, returns each question's sibling in that CONTENT language across the translation chain — the same questions in another language. Distinct from lang (labels only). PAGINATION + COUNTING: - cursor (string): from previous meta.nextCursor. Omit for page 1. - limit (1-100, default 20). - count: none (default, skip — page via nextCursor) | exact (precise COUNT(*), index-only ~25-90ms). OUTPUT: { questions: [...], meta: { count, countMode, language, nextCursor, total? } }. 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.

{
  "type": "object",
  "properties": {
    "lang": {
      "default": "en",
      "description": "Question language as ISO 639-1 code. Default \"en\". Supported: en, pl. Translated rows share the same `id` across languages.",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    },
    "category": {
      "description": "Top-level category slug (kebab-case) — e.g. `geography`, `history`, `science-and-nature`. 24 total. Use `quizbase_categories` for canonical list with localized names.",
      "type": "string"
    },
    "difficulty": {
      "description": "LLM-calibrated 5-level difficulty. trivial=common-knowledge, easy=approachable, medium=requires-thought, hard=needs-domain-context, expert=specialist. Records not yet LLM-rated hold the importer placeholder (mostly \"medium\" for factoid sources).",
      "type": "string",
      "enum": [
        "trivial",
        "easy",
        "medium",
        "hard",
        "expert"
      ]
    },
    "type": {
      "description": "\"multiple\" = 1 correct + 3 distractors. \"boolean\" = True/False.",
      "type": "string",
      "enum": [
        "multiple",
        "boolean"
      ]
    },
    "subcategory": {
      "description": "Raw subcategory slug (kebab-case). Prefer `topic` for OR + alias resolver.",
      "type": "string"
    },
    "tags": {
      "description": "AND-logic: question must have ALL these tag slugs (kebab-case)",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tags_any": {
      "description": "OR-logic: question must have AT LEAST ONE of these tag slugs",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "topic": {
      "description": "Curated topic slug — alias resolver matches subcategories and tags",
      "type": "string"
    },
    "topics_any": {
      "description": "OR-logic over curated topic slugs (resolves aliases)",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "regions": {
      "description": "Cultural affinity codes. 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). Lowercase ISO 3166-1 alpha-2 (`us`, `pl`, `gb`) plus cultural codes (`jewish`, `christian-catholic`, `islam`). AND-logic. Empty array in DB = universally accessible. Use `quizbase_regions` for the full catalog with counts.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "source": {
      "description": "Include only these source databases (one or more of 12): opentdb, opentriviaqa, mkqa, mintaka, kqa-pro, entityq, nq-open, creak, qasc, arc, webq, quizbase. Matches `attribution.source`.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "arc",
          "creak",
          "entityq",
          "kqa-pro",
          "mintaka",
          "mkqa",
          "nq-open",
          "opentdb",
          "opentriviaqa",
          "qasc",
          "quizbase",
          "webq"
        ]
      }
    },
    "exclude_source": {
      "description": "Exclude these source databases, e.g. `[\"entityq\"]`. Use to drop noisy auto-generated sources. Applied after `source` if both are present.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "arc",
          "creak",
          "entityq",
          "kqa-pro",
          "mintaka",
          "mkqa",
          "nq-open",
          "opentdb",
          "opentriviaqa",
          "qasc",
          "quizbase",
          "webq"
        ]
      }
    },
    "license": {
      "description": "SPDX license string (e.g. CC-BY-SA-4.0, MIT). Filter for redistribution-friendly content.",
      "type": "string",
      "enum": [
        "CC-BY-SA-4.0",
        "CC-BY-SA-3.0",
        "CC-BY-4.0",
        "MIT",
        "proprietary"
      ]
    },
    "quality": {
      "default": "high",
      "description": "Quality preset. \"high\" (default) returns only the cleanest, most broadly-useful questions. \"standard\" broadens to the full reviewed pool incl. niche/too-specific. \"all\" includes everything flagged for review — for audit, research, or BY-SA dump.",
      "type": "string",
      "enum": [
        "high",
        "standard",
        "all"
      ]
    },
    "cursor": {
      "description": "Opaque pagination cursor from previous `meta.nextCursor`. Omit for page 1; pass last response's `meta.nextCursor` for subsequent pages. Stop when `nextCursor` is null.",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Page size (1-100, default 20). Larger pages reduce round-trips but increase latency.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "updated_since": {
      "description": "ISO 8601 timestamp — return only questions updated after this (delta sync)",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "count": {
      "default": "none",
      "description": "Total count strategy. `none` (default, fastest — page via nextCursor, no total). `exact` (precise COUNT(*), index-only ~25-90ms — when you need the exact number of matches).",
      "type": "string",
      "enum": [
        "exact",
        "none"
      ]
    },
    "ids": {
      "description": "Batch fetch by id (up to 250). Returns those exact records in one call — anti-repeat, deep-links, reconstructing a saved set. Terminal selector: all browse filters and cursor are ignored. Ids with no result come back in `meta.missing`. Combine with `content_language` to map a set across languages.",
      "maxItems": 250,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "content_language": {
      "description": "With `ids`, returns each question in this CONTENT language (its `text`/answers) by following the translation chain — the same questions in another language, not a re-draw. Distinct from `lang` (which only localizes category/tag labels). Supported: en, pl. Untranslated ids land in `meta.missing`.",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "questions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "text"
        ],
        "additionalProperties": {}
      },
      "description": "Array of trivia questions for the current page, each with full attribution."
    },
    "meta": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "countMode": {
          "type": "string",
          "enum": [
            "exact",
            "none"
          ]
        },
        "language": {
          "type": "string"
        },
        "nextCursor": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "count",
        "countMode",
        "language",
        "nextCursor"
      ],
      "additionalProperties": {},
      "description": "Pagination metadata: count of returned rows, total (exact match count, only when count=exact), nextCursor (null = end), language echoed."
    }
  },
  "required": [
    "questions",
    "meta"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Question UUID (v7 format). Stable across language translations — the same UUID may exist in multiple languages with different text but same canonical answer."
    },
    "lang": {
      "default": "en",
      "description": "Language for the response (ISO 639-1). Default \"en\". Supported: en, pl. Affects `text`, `correct`, `incorrect`, plus localized labels in `category.name`, `subcategories[].label`, `tags[].label`.",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "question": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            "text": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "text"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ],
      "description": "Question object with full attribution and quality flag. Null when not found."
    },
    "error": {
      "description": "Error code when question is null (e.g. `not_found`).",
      "type": "string"
    }
  },
  "required": [
    "question"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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. - byDifficulty: { trivial: N, easy: N, medium: N, hard: N, expert: N, unrated: N } — null difficulty mapped to 'unrated'. trivial/expert populated by LLM calibration. - 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).

{
  "type": "object",
  "properties": {
    "lang": {
      "default": "en",
      "description": "Language for localized labels in `byCategory[].name`, `byTopic[].label`, `byTag[].label`. Default \"en\". Supported: en, pl. Numeric counts (total, byLanguage, bySource, byDifficulty) are language-agnostic.",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "total": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Approved questions count across all supported languages."
    },
    "byLanguage": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      },
      "description": "Count per language code."
    },
    "bySource": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      },
      "description": "Count per source database (12 keys)."
    },
    "byDifficulty": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "integer",
        "minimum": -9007199254740991,
        "maximum": 9007199254740991
      },
      "description": "Count per difficulty bucket (trivial / easy / medium / hard / expert / unrated)."
    },
    "byCategory": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          }
        },
        "required": [
          "slug"
        ],
        "additionalProperties": {}
      },
      "description": "Top 24 categories with localized names and counts."
    },
    "byTopic": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          }
        },
        "required": [
          "slug"
        ],
        "additionalProperties": {}
      },
      "description": "Top 30 curated topics with localized labels."
    },
    "byTag": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          }
        },
        "required": [
          "slug"
        ],
        "additionalProperties": {}
      },
      "description": "Top 30 raw tags with localized labels."
    },
    "meta": {
      "type": "object",
      "properties": {
        "generatedAt": {
          "type": "string"
        },
        "language": {
          "type": "string"
        }
      },
      "required": [
        "generatedAt",
        "language"
      ],
      "additionalProperties": {},
      "description": "Snapshot metadata: generation timestamp and echoed language."
    }
  },
  "required": [
    "total",
    "byLanguage",
    "bySource",
    "byDifficulty",
    "byCategory",
    "byTopic",
    "byTag",
    "meta"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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).

{
  "type": "object",
  "properties": {
    "lang": {
      "default": "en",
      "description": "Language for `label` field in each topic (ISO 639-1). Default \"en\". Supported: en, pl. Slugs themselves are language-agnostic (canonical).",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    },
    "q": {
      "description": "Substring search across topic label, slug, and aliases (case-insensitive). Use to find a curated topic by partial name — e.g. `q=star` returns `star-wars`, `star-trek`, `stars-and-astronomy`.",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "kind": {
      "description": "Filter by underlying taxonomy origin. `tag` returns topics resolving to tag-level slugs (proper nouns, specific entities). `subcategory` returns topics resolving to broader subcategory groupings. Omit for all.",
      "type": "string",
      "enum": [
        "tag",
        "subcategory"
      ]
    },
    "cursor": {
      "description": "Opaque pagination cursor from previous `meta.nextCursor`. Omit for page 1; pass last response's `meta.nextCursor` for next pages. Stop when `nextCursor` is null.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Page size (1-500, default 100). Higher = fewer round-trips.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "topics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        },
        "required": [
          "slug",
          "label"
        ],
        "additionalProperties": {}
      },
      "description": "Topics on this page with localized labels, counts, and underlying kind."
    },
    "meta": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "total": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "language": {
          "type": "string"
        },
        "nextCursor": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "count",
        "total",
        "language",
        "nextCursor"
      ],
      "additionalProperties": {},
      "description": "Pagination metadata: count returned, total available, cursor for next page."
    }
  },
  "required": [
    "topics",
    "meta"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Curated topic slug (kebab-case) — e.g. `star-wars`, `world-war-ii`, `programming-languages`. List all via `quizbase_topics`. Aliases resolve automatically (e.g. `sw` → `star-wars`)."
    },
    "lang": {
      "default": "en",
      "description": "Language for `topic.label` and sample question text (ISO 639-1). Default \"en\". Supported: en, pl. Numeric facet counts language-agnostic.",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    }
  },
  "required": [
    "slug"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "topic": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "slug": {
              "type": "string"
            },
            "label": {
              "type": "string"
            }
          },
          "required": [
            "slug",
            "label"
          ],
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ],
      "description": "Topic detail with metadata. Null if slug not found."
    },
    "facets": {
      "description": "Facet breakdowns: byCategory, byDifficulty, byLanguage, coOccurringTags, coOccurringSubcategories.",
      "type": "object",
      "properties": {},
      "additionalProperties": {}
    },
    "samples": {
      "description": "Up to 3 sample questions matching this topic.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": {}
      }
    },
    "meta": {
      "description": "Response metadata.",
      "type": "object",
      "properties": {
        "language": {
          "type": "string"
        }
      },
      "required": [
        "language"
      ],
      "additionalProperties": {}
    },
    "error": {
      "description": "Error code when topic is null (e.g. `not_found`).",
      "type": "string"
    }
  },
  "required": [
    "topic"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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).

{
  "type": "object",
  "properties": {
    "lang": {
      "default": "en",
      "description": "Language for tag `label` (ISO 639-1). Default \"en\". Supported: en, pl. Slugs are language-agnostic canonical identifiers.",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    },
    "q": {
      "description": "Substring search across tag slug + label (case-insensitive). Use to find specific tags by partial name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "cursor": {
      "description": "Opaque pagination cursor from previous `meta.nextCursor`. Omit for page 1. Stop when null.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Page size (1-500, default 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "slug",
          "label",
          "count"
        ],
        "additionalProperties": {}
      },
      "description": "Tags on this page with display labels and per-tag question counts."
    },
    "meta": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "total": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "language": {
          "type": "string"
        },
        "nextCursor": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "count",
        "total",
        "language",
        "nextCursor"
      ],
      "additionalProperties": {},
      "description": "Pagination metadata: count returned, total available, cursor for next page."
    }
  },
  "required": [
    "tags",
    "meta"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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

{
  "type": "object",
  "properties": {
    "lang": {
      "default": "en",
      "description": "Language for subcategory `label` (ISO 639-1). Default \"en\". Supported: en, pl. Slugs language-agnostic.",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    },
    "q": {
      "description": "Substring search across subcategory slug + label (case-insensitive). Useful for partial discovery.",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "cursor": {
      "description": "Opaque pagination cursor from previous `meta.nextCursor`. Omit for page 1.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Page size (1-500, default 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "subcategories": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "slug",
          "label",
          "count"
        ],
        "additionalProperties": {}
      },
      "description": "Subcategories on this page with localized labels and per-subcategory counts."
    },
    "meta": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "total": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "language": {
          "type": "string"
        },
        "nextCursor": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "count",
        "total",
        "language",
        "nextCursor"
      ],
      "additionalProperties": {},
      "description": "Pagination metadata: count returned, total available, cursor for next page."
    }
  },
  "required": [
    "subcategories",
    "meta"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "lang": {
      "default": "en",
      "description": "Language for category `name` field (ISO 639-1). Default \"en\". Supported: en, pl. Slugs are language-agnostic.",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "categories": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "slug",
          "name"
        ],
        "additionalProperties": {}
      },
      "description": "All 24 top-level categories with localized names."
    },
    "meta": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "language": {
          "type": "string"
        }
      },
      "required": [
        "count",
        "language"
      ],
      "additionalProperties": {},
      "description": "Response metadata: how many categories returned and which language."
    }
  },
  "required": [
    "categories",
    "meta"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "lang": {
      "default": "en",
      "description": "Language for `displayName` of each supported language entry (ISO 639-1). Default \"en\". E.g. with `lang=pl` Polish returns as \"polski\", English as \"angielski\". Codes themselves are language-agnostic.",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "languages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "displayName"
        ],
        "additionalProperties": {}
      },
      "description": "Supported languages with localized display name and question count per language."
    },
    "meta": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "language": {
          "type": "string"
        }
      },
      "required": [
        "count",
        "language"
      ],
      "additionalProperties": {},
      "description": "Response metadata."
    }
  },
  "required": [
    "languages",
    "meta"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "lang": {
      "default": "en",
      "description": "Language for region `label` (ISO 639-1). Default \"en\". Supported: en, pl. Codes themselves language-agnostic.",
      "type": "string",
      "enum": [
        "en",
        "pl"
      ]
    },
    "q": {
      "description": "Substring search on region code + label (case-insensitive). E.g. `q=jew` returns `jewish` cultural code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "kind": {
      "description": "Filter by region type. `country` returns ISO 3166-1 alpha-2 codes (`us`, `pl`, `gb`...). `cultural` returns cultural/religious affinity codes (`jewish`, `christian-catholic`, `islam`...). Omit for both.",
      "type": "string",
      "enum": [
        "country",
        "cultural"
      ]
    },
    "cursor": {
      "description": "Opaque pagination cursor from previous `meta.nextCursor`. Omit for page 1.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Page size (1-500, default 100). Catalog has ~150 distinct codes per language.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "regions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "country",
              "cultural"
            ]
          },
          "label": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "code",
          "kind",
          "label",
          "count"
        ],
        "additionalProperties": {}
      },
      "description": "Region codes (cultural affinity) with localized labels, kind (country|cultural), and per-region counts."
    },
    "meta": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "total": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "language": {
          "type": "string"
        },
        "nextCursor": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "count",
        "total",
        "language",
        "nextCursor"
      ],
      "additionalProperties": {},
      "description": "Pagination metadata: count returned, total available, cursor for next page."
    }
  },
  "required": [
    "regions",
    "meta"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

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 on success: {ok:true, reportId}. On failure the result is marked isError:true with structuredContent {error, message} — error codes: invalid_input, not_found, rate_limit_exceeded (per-IP 5/min), internal_error.

{
  "type": "object",
  "properties": {
    "questionId": {
      "description": "Question UUID (v7) being reported. Highest-fidelity identifier — use when you have it. At least one of `questionId`, `questionText`, `questionUrl` is required.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "questionText": {
      "description": "Full or partial question text (10-2000 chars) when UUID is not available. Used by moderators to locate the record. Lower fidelity than `questionId`.",
      "type": "string",
      "minLength": 10,
      "maxLength": 2000
    },
    "questionUrl": {
      "description": "URL referencing the question (e.g. your app deep-link, screenshot host). Useful when question came from a downstream surface and the user clicks \"Report\" without raw text/ID access.",
      "type": "string",
      "maxLength": 500,
      "format": "uri"
    },
    "type": {
      "type": "string",
      "enum": [
        "translation",
        "factual",
        "inappropriate",
        "attribution",
        "other"
      ],
      "description": "Report category. `translation` = bad EN→PL or other lang translation. `factual` = incorrect answer / outdated fact. `inappropriate` = offensive content. `attribution` = missing/wrong source credit (CC-BY-SA § 3 violation). `other` = anything else (use `comment` to explain)."
    },
    "comment": {
      "description": "Free-text explanation of the issue (max 2000 chars). Strongly recommended — bare flag without context is hard to triage. Examples: \"Currency in answer was correct in 2018 but Argentina changed it in 2023\", \"Polish translation reads as gibberish\".",
      "type": "string",
      "maxLength": 2000
    },
    "reporterEmail": {
      "description": "Reporter email for follow-up (optional). Use when you have user consent — we may contact for clarification if the report is unclear.",
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    }
  },
  "required": [
    "type"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true,
      "description": "Always true on success; failures use isError, not this field."
    },
    "reportId": {
      "description": "UUID of the recorded report. Use for follow-up references.",
      "type": "string"
    }
  },
  "required": [
    "ok"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}