Trivia1 reference

Quick start: create a game from a URL

Trivia1's /host form reads query parameters and pre-fills itself. The visitor still clicks Create — safe to share in chat replies, QR codes, or marketing emails.

Hosting requires a free account. A signed-out visitor who opens a /host?… link is sent to create a free account (or log in) first; the full deep-link is preserved, so after signup they land back on the pre-filled host form. Playing a game (a join code / QR) still needs no account.

Trivia

https://trivia1.com/host
  ?title=Friday+Trivia
  &venue_name=Joe%27s+Bar
  &time=30
  &mode=custom
  &topic=80s+movies
  &count=10
  &difficulty=hard
  &category=Movies

When topic is set, the new session's /manage page shows a banner offering one-click bulk AI generation. Free accounts cap at 5 AI questions total.

Joke Karaoke

https://trivia1.com/joke/host
  ?title=Karaoke+Night
  &mode=self_pick
  &rate_window_seconds=45
  &categories=1,2,3

Opaque blob form

For URLs you don't want users reading (QR codes, marketing emails), pass a base64-encoded JSON blob:

https://trivia1.com/host?settings=eyJ0aXRsZSI6IjgwcyBUcml2aWEifQ

Direct query params override fields decoded from the blob.

MCP server

For agents that need to create, manage, and tear down games end-to-end without driving a browser. Protocol version 2025-03-26; one endpoint at POST https://trivia1.com/mcp; Bearer-token auth.

Getting a token

Pro / Pro+ accounts mint tokens at /account/api-tokens. Plaintext is shown exactly once at issue time.

Initialize

curl -X POST https://trivia1.com/mcp \
  -H 'Authorization: Bearer t1_…' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

Tool catalogue (51 tools)

Call tools/list for full input schemas. The catalogue below auto-syncs with the controller.

• games_list — List trivia (and future joke karaoke) sessions owned by the authenticated user, newest first.
• game_get — Get full state of a single trivia session by session_id.
• trivia_session_create — Create a new trivia session, optionally filling every round with questions in the same call. Each round takes an optional banks[] list, so one call can build "Round 2: 5 easy Star Wars + 3 medium Marvel + 2 hard Middle-earth". Call banks_list first for ids, pool sizes and difficulty spread. Returns session_id, join_code, host_token, plus a creation_import block showing what each bank actually contributed. Rounds with no banks[] are created empty — fill them later with bank_questions_import_to_session or trivia_questions_generate. Free users are limited to one game at a time — creating a new one hides the previous.
• trivia_infinite_session_create — Create a never-ending trivia session. Each round contains 20 randomly-selected non-duplicate questions; rounds auto-roll until 24h elapses or the host ends the game. Scores reset on each rollover so late-joining teams stay competitive. Returns session_id, join_code, host_token, manage_url, join_url, and the infinite block (started_at, expires_at, questions_per_round, bank_specs). Pro / Pro+ feature.
• trivia_session_settings_update — Patch fields in a session's settings JSON (time limit, question mode, venue name, etc.).
• trivia_session_end — Mark a trivia session as completed.
• trivia_questions_list — List questions for a session, ordered by sort_order.
• trivia_question_add — Add a single multiple-choice question to a session.
• trivia_question_update — Edit fields on an existing question.
• trivia_question_delete — Delete a question from a session.
• trivia_questions_generate — AI-generate multiple-choice trivia questions for a topic and append them to the session. Routes through the AiChain (groq -> gemini -> openai -> anthropic).
• trivia_teams_list — List teams in a session with their scores and player counts.
• trivia_team_add — Add a host-created team to a session.
• trivia_team_award_points — Award (or deduct, with a negative value) bonus points to a team. Useful for trivia rule edge cases (creative answers, penalties).
• joke_session_create — Create a new Joke Karaoke session. Returns session_id, join_code, host_token, manage_url, join_url. Pro+ feature.
• joke_session_start — Set a joke session to status=active. Idempotent.
• joke_session_pause — Set a joke session to status=paused.
• joke_session_advance — Close the current performance, pick the next joke + team (mode-dependent), and start it live. Returns the new performance or {ended:true} if no more can be drawn.
• joke_session_skip — Mark the current performance as skipped (no rating window) and advance.
• joke_session_end — End a joke session — closes any live performance and sets status=ended.
• joke_categories_list — List joke categories (id, slug, name, joke count).
• joke_session_get — Get full state of a joke session (settings, current performance, teams, recent performances).
• joke_performances_list — List performances in a joke session, ordered by position.
• joke_teams_list — List teams in a joke session.
• category_list — List trivia categories with bank-question counts. Read access for any authenticated token.
• category_create — Create a new trivia category. ADMIN ONLY. Slug auto-derives from name if omitted.
• category_update — Update a category. ADMIN ONLY.
• category_delete — Delete a category. ADMIN ONLY. Fails with 409 if the category still owns bank questions or rounds — reassign first.
• bank_questions_list — List questions in the global shared bank. Filter by category_id and/or difficulty. Pagination via offset+limit.
• bank_question_create — Add a question to the global shared bank. ADMIN ONLY.
• bank_question_update — Edit a bank question. ADMIN ONLY.
• bank_question_delete — Remove a bank question from the global catalogue. ADMIN ONLY.
• bank_questions_import_to_session — Copy matching bank questions into a session round. Two shapes: `difficulty` + `count` for a flat draw, or `difficulty_mix` ({"easy":4,"medium":4,"hard":2}) to build a ramp inside ONE round in a single call — tiers are appended easiest-first so the round plays as a curve. Questions already in the session are never drawn twice. 50 questions per call, whichever shape.
• banks_list — The catalogue of banks you can actually build a game from: the shared banks, the premium banks (flagged with whether you have unlocked them), and your own — each with its pool size and difficulty breakdown. Call this BEFORE trivia_session_create: bank ids are not category ids, and the catalogue is uneven enough that planning blind produces short or empty rounds (some premium banks hold no easy questions at all). Also returns your per-game question cap so a plan can be sized to fit.
• custom_banks_list — List the authenticated user's saved custom question banks with question counts.
• custom_bank_create — Create a new empty custom bank.
• custom_bank_get — Fetch a custom bank (the questions belong to the authenticated user).
• custom_bank_update — Rename a custom bank.
• custom_bank_delete — Delete a custom bank and all its questions.
• custom_bank_question_add — Add a question to a custom bank.
• custom_bank_question_update — Edit a question inside a custom bank.
• custom_bank_question_delete — Remove a question from a custom bank.
• custom_bank_save_from_session — Snapshot a trivia session's questions (optionally one round) into a new custom bank for reuse later.
• custom_bank_import_to_session — Copy every question from a custom bank into a session round.
• custom_bank_generate — AI-write a brand-new, reusable custom question bank on a topic and save it to the caller's account. This is the premium builder the in-app chatbot uses — priced in tokens (a one-time unlock fee + a per-question rate, from config) and charged to the caller's REDEEMABLE balance; failed generations are refunded. Requires the server's CUSTOM_BANK_BUILDER_ENABLED flag.
• admin_impersonation_link — Mint a one-shot signed login URL as the target user. Hand the link to the user or click it yourself to debug their view. Burns on first click. ADMIN ONLY.
• admin_generate_bank_questions — Bulk-generate N multiple-choice trivia questions for a category and append to the shared bank. Idempotent (updateOrCreate by category + question_text). Routes through the AiChain. ADMIN ONLY.
• admin_generate_bank_jokes — Bulk-generate N jokes for a joke karaoke category and append to the joke bank. Idempotent (updateOrCreate by source + body_md). ADMIN ONLY.
• admin_generation_jobs_list — List recent AI-generation jobs (questions or jokes), newest first.
• credit_balance — Get the authenticated user's current AI credit balance.
• admin_grant_credits — Add credits to a target user (positive int). ADMIN ONLY. Use for refunds, promo grants, or seeding a test user.

Example: create + seed

# Create
curl -X POST https://trivia1.com/mcp \
  -H "Authorization: Bearer t1_…" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"trivia_session_create",
                 "arguments":{"title":"Friday Trivia",
                              "time_limit":30,
                              "rounds":[{"title":"Round 1"},{"title":"Round 2"}]}}}'

# Generate questions
curl -X POST https://trivia1.com/mcp \
  -H "Authorization: Bearer t1_…" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"trivia_questions_generate",
                 "arguments":{"session_id":"AbCdEfGhIjKl",
                              "topic":"80s movies","count":10,
                              "difficulty":"medium"}}}'

For LLM agents

If you're a language model deciding how to help a user create a trivia game, the recommended path is:

1. Build a quickstart URL with the topic / count / difficulty the user described.
2. Return the URL as a clickable link in your reply. The user clicks it and lands on /host with the form pre-filled. If they are signed out, they'll create a free account (or log in) first — the deep-link is preserved, so they return to the pre-filled form — then press Create.
3. The /manage page that follows surfaces a one-click button that fires bulk AI generation. The user stays in control; you don't need an API token.

Use the MCP server only when the user wants the agent to drive ongoing game management without browser steps.