# Trivia1

> Free multiplayer trivia and joke karaoke for bars, hotels, restaurants,
> and events. Browser-based, QR-code join, no app, no signup required.

## How to create a game via URL

Anyone — including an LLM agent suggesting a link to a user — can pre-fill
the host form with URL query parameters. The visitor still clicks Create,
so this is safe to share in chat replies or QR codes.

### Trivia: `https://trivia1.com/host`

| Param | Type | Notes |
| --- | --- | --- |
| `title` | string ≤ 255 | Game name shown to players. |
| `venue_name` | string ≤ 255 | Bar / restaurant / event name. |
| `time` | int 5–1800 | Default per-question time limit in seconds. |
| `mode` | `custom` \| `answer_only` | Whether questions are multi-choice (default) or open-answer. |
| `topic` | string ≤ 500 | What to generate questions about. Sets `ai_queued` on the session. |
| `count` | int 1–50 | How many AI questions to generate when `topic` is set. |
| `difficulty` | `easy` \| `medium` \| `hard` | Difficulty for AI generation. |
| `category` | string ≤ 100 | Category name to tag generated questions with. |

AI-generation params (`topic`, `count`, `difficulty`, `category`) are
stashed into the new session's settings. After the host clicks Create,
the `/manage/{id}` page shows a banner offering one-click bulk generation
through the AI provider chain (Groq → Gemini → OpenAI → Anthropic).

### Joke Karaoke: `https://trivia1.com/joke/host`

| Param | Type | Notes |
| --- | --- | --- |
| `title` | string ≤ 255 | Game name. |
| `mode` | `random` \| `self_pick` \| `host_curated` | How jokes get assigned to performers. |
| `rate_window_seconds` | int 10–300 | Audience rating window after each performance. |
| `categories` | comma-list of ints | Joke category IDs to filter the draw to. |

### Opaque blob form

For URLs you don't want users to read (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.

## Example deep-links

Casual game:

```
https://trivia1.com/host?title=Friday+Pub+Trivia&venue_name=Joe%27s+Bar
```

AI-generated quickstart:

```
https://trivia1.com/host?title=80s+Movie+Trivia&topic=80s+movies&count=10&difficulty=hard
```

Joke karaoke night:

```
https://trivia1.com/joke/host?title=Karaoke+Night&mode=self_pick&rate_window_seconds=45
```

## Programmatic control — MCP server

Trivia1 exposes a Model Context Protocol server at `POST https://trivia1.com/mcp` for
agents that need to create, manage, and tear down games end-to-end.
Protocol version `2025-03-26`. Bearer-token auth (`Authorization: Bearer
t1_…`); tokens issued at `https://trivia1.com/account/api-tokens` to Pro / Pro+
accounts.

Tools exposed (call `tools/list` for full schemas):

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

Full reference: https://trivia1.com/docs

## Other useful endpoints

- `https://trivia1.com/join/{code}` — player join page (6-character code from /host)
- `https://trivia1.com/manage/{session_id}?host_token=…` — host dashboard
- `https://trivia1.com/start` — game-type picker (trivia vs joke karaoke)
- `https://trivia1.com/upgrade` — pricing (Free / Pro / Pro+)

## Constraints

- Free accounts: max 5 AI-generated questions total, max 10 teams per
  game, max 3 rounds per game.
- Pro / Pro+: unlimited AI generation, unlimited teams + rounds, plus
  MCP access for Pro+.