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.

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 (48 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. Returns session_id, join_code, host_token. Free users are limited to one game at a time — creating a new one hides the previous.
• 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 N matching bank questions into a session round. Reusable agent shortcut for filling a round from the curated catalogue.
• 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.
• 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, lands on /host with the form pre-filled, and presses 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.