quizbase
Get API key
Skip to content
Command Palette
Search for a command to run...
QuizBase · Docs

FAQ#

Quick answers to the most common questions. Each heading is deep-linkable — share a URL like /docs/faq#is-there-a-real-free-tier.

Billing and keys#

Is there a real free tier?#

Yes — Free gives you the full API: every endpoint, all 50k+ questions, all 20+ languages, 500 requests/day, 10 burst/10s. No credit card. Pay only when traffic outgrows it — not when you ship to production.

What counts against my plan?#

Every request to /api/v1/* made with one of your API keys. Quota is per user account, shared across all your keys (up to 20 active). Excluded: health checks (/api/health) and anonymous bug reports (/api/v1/report, has its own per-IP limit).

Can I exceed my plan without being charged?#

No. If you hit either window — 10/10s burst or daily — we return 429 until it resets. No surprise overage; either upgrade or wait.

When does the spend cap actually take effect?#

Spend cap configuration and alerts (50% / 75% / 100%) ship alongside Stripe billing in a later phase. Until then, every plan is metered by request count only — there is no dollar-denominated cap to hit. The pricing page lists spend cap as a planned feature, not a currently active one. Free tier remains unaffected (request-count limits only, never bills).

Why is the quota per account, not per key?#

Keys are name + scope (“pk” vs “sk”) for organizing your apps — they’re not a multiplier. One license, one quota, twenty keys if you want to slice your traffic by app or environment. This keeps pricing honest: 1000 keys ≠ 1000× quota.

How do I rotate a key?#

Create a new key in the dashboard, deploy it alongside the old, then delete the old one. Old key works for 24h after rotation as a grace period.

Usage#

What’s the fastest way to start?#

Quickstart — signup, API key, first request in under 5 minutes.

Is there an OpenAPI spec?#

Yes — published at /openapi.json and rendered at /docs/api-reference. Use it to drive code generators (Postman, Bruno, openapi-typescript), or browse interactively from there.

Do you have webhooks?#

Not yet. The API is pull-only. If you need fresh data, use /v1/questions?updated_since=<timestamp> for delta sync.

Can I report a problem with a question?#

Yes — POST /api/v1/report (no API key required, rate-limited 5/min/IP). Pass { questionId, type: 'translation'|'factual'|'inappropriate'|'attribution'|'other', comment? }. We review reports and email you back if you include reporterEmail. See POST /v1/report.

Can I bulk-download the dataset?#

Yes — our public BY-SA enrichment dump is on github.com/maciejdzierzek/quizbase-dumps-byasa under CC-BY-SA-4.0. Regenerated manually around major content updates. See /data for full attribution.

How big is a typical response?#

/v1/questions/random?amount=10 returns ~6KB. /v1/questions?limit=100 returns ~60KB. /v1/stats is ~2KB (and cached for 5 min).

How do I check if QuizBase is up?#

Visit /status — redirects to our public status page (UptimeRobot). External monitoring runs 5 health checks every 5 minutes from outside Railway. If you’re seeing errors but the status page is green, use the “Report a problem” button in your dashboard (it attaches your request_id and breadcrumbs to a Sentry feedback) or email [email protected]. See /docs/support for the full triage map.

Content#

Where do questions come from?#

11 open-licensed sources, blended into one quiz-ready catalog:

  • OpenTDB — CC-BY-SA 4.0, community-curated trivia
  • OpenTriviaQA — MIT, academic dataset
  • MKQA — multilingual question-answer dataset, CC-BY 3.0
  • Mintaka — multilingual entity-centric questions, CC-BY 4.0
  • NQ-Open — Natural Questions Open, CC-BY-SA 3.0
  • KQA Pro — knowledge-base QA, CC-BY-SA 4.0
  • EntityQuestions — entity-centric, CC-BY 4.0
  • …and a few smaller datasets

attribution.source on every question tells you which one. Full catalog with licenses, counts, and links: /data.

How accurate are translations?#

Polish is machine-translated from the English source with per-domain rules (trivia tone, original-title preservation for films, deterministic mapping for booleans). Quality is production-grade for trivia but not guaranteed — always show attribution.source so users can flag problems via POST /v1/report. The translator field is "machine" for translated records.

What’s is_translation?#

We don’t expose is_translation as a boolean. Instead, check translationOf !== null — if it’s non-null, the question is a translation of an English source.

How often is content refreshed?#

At launch, refreshes are irregular — our focus is on performance, dataset quality, and adding more languages, not on a fixed import cadence. When we re-import or add new content, you can pull only the delta with updated_since instead of re-fetching the full catalog.

On the roadmap: a steady stream of new questions on our own permissive license (attribution-free) so apps that want fresh content without the CC-BY-SA chain have a clean path. We’ll publish a refresh schedule once that pipeline lands.

Can I contribute a question?#

Not yet — user-submitted content is on the post-launch roadmap. For now, report problems with existing questions and we’ll fix or remove.

Technical#

Is the API versioned?#

Yes — URL versioning. /v1/ is the current and only public version. We avoid breaking changes and add features additively. The product is new, so if a breaking change ever becomes unavoidable, we’ll consider a /v2/ (only worth the cost if /v1 is actively used) and announce it at least one month in advance with a migration note.

Do you support GraphQL?#

No. REST + clean JSON + OpenAPI spec covers every trivia-app use case without GraphQL’s tradeoffs.

What about CORS?#

Only /v1/report is open CORS (anonymous bug submission with per-IP rate-limit). Every other /api/v1/* endpoint requires an API key.

Authenticated endpoints (/v1/me, /v1/usage, /v1/questions/*, /v1/categories, /v1/stats, /v1/topics, etc.) ship Access-Control-Allow-Origin: * only when the request carries a qb_pk_* (publishable) key — those are designed to live in browser bundles. qb_sk_* (secret) keys never get CORS headers; browsers block them by design. Per-domain allowlists (Stripe-style) are post-launch — currently any origin can use a pk_* key. Full details on the Authentication page (CORS section).

Can I use this in a Cloudflare Worker / edge runtime?#

Yes. Standard fetch API, no Node-only code needed. (The MCP server, when it ships, will be Node-only.)

Do you support HTTP/2 or HTTP/3?#

HTTP/2 on Railway’s edge. HTTP/3 when Railway rolls it out.

Roadmap and support#

Where’s the changelog?#

/changelog — every shipped feature, dated, with links to PRs.

How do I report a bug?#

Support page has email and community channels.

Is there an SLA?#

Free tier — best effort. Paid tiers — see pricing page for uptime commitments.

Is the source code open?#

The server is closed. The OpenAPI spec, TypeScript SDK, and MCP server (when published) will be MIT-licensed on GitHub.

See also#