docs: comprehensive API documentation from source code

Replace existing docs with fresh documentation built entirely from source code analysis. OpenAPI 3.1 spec as source of truth, plus human-readable Markdown with curl examples, response samples, and workflow guides. - OpenAPI 3.1 spec covering all 42 endpoints (validated against source) - 7 endpoint reference docs (auth, games, sessions, picker, stats, votes, webhooks) - WebSocket protocol documentation (auth, subscriptions, 4 event types) - 4 guide documents (getting started, session lifecycle, voting, webhooks) - API README with overview, auth docs, and quick reference table - Old docs archived to docs/archive/ Made-with: Cursor
2026-03-15 16:44:53 -04:00
parent 505c335d20
commit 8ba32e128c
25 changed files with 6546 additions and 0 deletions
--- a/docs/api/guides/getting-started.md
+++ b/docs/api/guides/getting-started.md
@@ -0,0 +1,316 @@
+# Getting Started
+
+A narrative walkthrough of the minimum viable integration path. Use this guide to go from zero to a completed game night session using the Jackbox Game Picker API.
+
+**Prerequisites:** API running locally (`http://localhost:5000`), admin key set via `ADMIN_KEY` environment variable.
+
+---
+
+## 1. Health Check
+
+Verify the API is running before anything else. The health endpoint requires no authentication.
+
+**Why:** Quick sanity check. If this fails, nothing else will work.
+
+```bash
+curl http://localhost:5000/health
+```
+
+**Sample response (200 OK):**
+
+```json
+{
+  "status": "ok",
+  "message": "Jackbox Game Picker API is running"
+}
+```
+
+---
+
+## 2. Authenticate
+
+Exchange your admin key for a JWT. You'll use this token for all write operations (creating sessions, adding games, closing sessions).
+
+**Why:** Creating sessions, adding games to them, and closing sessions require authentication. The picker and game listings are public, but session management is not.
+
+See [Auth endpoints](../endpoints/auth.md) for full details.
+
+```bash
+TOKEN=$(curl -s -X POST http://localhost:5000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"key": "your-admin-key"}' | jq -r '.token')
+```
+
+Or capture the full response:
+
+```bash
+curl -X POST http://localhost:5000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"key": "your-admin-key"}'
+```
+
+**Sample response (200 OK):**
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJ0aW1lc3RhbXAiOjE3MTAwMDAwMDAwLCJpYXQiOjE3MTAwMDAwMDB9.abc123",
+  "message": "Authentication successful",
+  "expiresIn": "24h"
+}
+```
+
+Store `token` in `$TOKEN` for the remaining steps. Tokens expire after 24 hours.
+
+---
+
+## 3. Browse Games
+
+List available games. Use query parameters to narrow the catalog—for example, `playerCount` filters to games that support that many players.
+
+**Why:** Know what's in the catalog before you pick. Filtering by player count ensures you only see games you can actually play.
+
+See [Games endpoints](../endpoints/games.md) for all filters.
+
+```bash
+curl "http://localhost:5000/api/games?playerCount=6"
+```
+
+**Sample response (200 OK):**
+
+```json
+[
+  {
+    "id": 1,
+    "pack_name": "Jackbox Party Pack 7",
+    "title": "Quiplash 3",
+    "min_players": 3,
+    "max_players": 8,
+    "length_minutes": 15,
+    "has_audience": 1,
+    "family_friendly": 0,
+    "game_type": "Writing",
+    "secondary_type": null,
+    "play_count": 0,
+    "popularity_score": 0,
+    "enabled": 1,
+    "favor_bias": 0,
+    "created_at": "2024-01-15T12:00:00.000Z"
+  },
+  {
+    "id": 2,
+    "pack_name": "Jackbox Party Pack 7",
+    "title": "The Devils and the Details",
+    "min_players": 3,
+    "max_players": 7,
+    "length_minutes": 25,
+    "has_audience": 1,
+    "family_friendly": 0,
+    "game_type": "Strategy",
+    "secondary_type": null,
+    "play_count": 0,
+    "popularity_score": 0,
+    "enabled": 1,
+    "favor_bias": 0,
+    "created_at": "2024-01-15T12:00:00.000Z"
+  }
+]
+```
+
+---
+
+## 4. Pick a Game
+
+Get a weighted random game based on your filters. The picker considers favor/disfavor bias and can avoid recently played games when a session is provided.
+
+**Why:** Instead of manually choosing, let the API pick a game that fits your player count, length, and other preferences. Use the same filters you used to browse.
+
+See [Picker endpoint](../endpoints/picker.md) for all options.
+
+```bash
+curl -X POST http://localhost:5000/api/pick \
+  -H "Content-Type: application/json" \
+  -d '{"playerCount": 6}'
+```
+
+**Sample response (200 OK):**
+
+```json
+{
+  "game": {
+    "id": 1,
+    "pack_name": "Jackbox Party Pack 7",
+    "title": "Quiplash 3",
+    "min_players": 3,
+    "max_players": 8,
+    "length_minutes": 15,
+    "has_audience": 1,
+    "family_friendly": 0,
+    "game_type": "Writing",
+    "secondary_type": null,
+    "play_count": 0,
+    "popularity_score": 0,
+    "enabled": 1,
+    "favor_bias": 0,
+    "created_at": "2024-01-15T12:00:00.000Z"
+  },
+  "poolSize": 12,
+  "totalEnabled": 17
+}
+```
+
+Save the `game.id` (e.g. `1`) — you'll use it when adding the game to the session.
+
+---
+
+## 5. Start a Session
+
+Create a new gaming session. Only one session can be active at a time. Use notes to label the night (e.g., "Friday game night").
+
+**Why:** Sessions track which games you played, when, and support voting and room monitoring. Starting a session marks the beginning of your game night.
+
+See [Sessions endpoints](../endpoints/sessions.md) for full details.
+
+```bash
+curl -X POST http://localhost:5000/api/sessions \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"notes": "Friday game night"}'
+```
+
+**Sample response (201 Created):**
+
+```json
+{
+  "id": 5,
+  "notes": "Friday game night",
+  "is_active": 1,
+  "created_at": "2026-03-15T19:00:00.000Z",
+  "closed_at": null
+}
+```
+
+Save the `id` (e.g. `5`) — you'll use it to add games and close the session.
+
+---
+
+## 6. Add the Picked Game
+
+Add the game you picked (step 4) to the session you created (step 5). You can optionally pass a room code once the game is running.
+
+**Why:** Adding a game to the session records that you played it, increments play counts, and enables voting and room monitoring. Use `game_id` from the pick response.
+
+```bash
+curl -X POST "http://localhost:5000/api/sessions/5/games" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"game_id": 1, "room_code": "ABCD"}'
+```
+
+Replace `5` with your session ID and `1` with the `game.id` from the pick response.
+
+**Sample response (201 Created):**
+
+```json
+{
+  "id": 14,
+  "session_id": 5,
+  "game_id": 1,
+  "manually_added": 0,
+  "status": "playing",
+  "room_code": "ABCD",
+  "played_at": "2026-03-15T20:30:00.000Z",
+  "pack_name": "Jackbox Party Pack 7",
+  "title": "Quiplash 3",
+  "game_type": "Writing",
+  "min_players": 3,
+  "max_players": 8
+}
+```
+
+---
+
+## 7. Close the Session
+
+When the game night is over, close the session. Any games still marked `playing` are automatically marked `played`.
+
+**Why:** Closing the session finalizes it, frees the "active session" slot for the next night, and triggers any end-of-session webhooks or WebSocket events.
+
+```bash
+curl -X POST "http://localhost:5000/api/sessions/5/close" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"notes": "Great session!"}'
+```
+
+Replace `5` with your session ID.
+
+**Sample response (200 OK):**
+
+```json
+{
+  "id": 5,
+  "notes": "Great session!",
+  "is_active": 0,
+  "created_at": "2026-03-15T19:00:00.000Z",
+  "closed_at": "2026-03-15T23:30:00.000Z",
+  "games_played": 1
+}
+```
+
+---
+
+## Quick Reference
+
+| Step | Endpoint | Auth |
+|------|----------|------|
+| 1 | `GET /health` | No |
+| 2 | `POST /api/auth/login` | No |
+| 3 | `GET /api/games?playerCount=6` | No |
+| 4 | `POST /api/pick` | No |
+| 5 | `POST /api/sessions` | Bearer |
+| 6 | `POST /api/sessions/{id}/games` | Bearer |
+| 7 | `POST /api/sessions/{id}/close` | Bearer |
+
+---
+
+## Full Copy-Paste Flow
+
+```bash
+# 1. Health check
+curl http://localhost:5000/health
+
+# 2. Get token (replace with your actual admin key)
+TOKEN=$(curl -s -X POST http://localhost:5000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"key": "your-admin-key"}' | jq -r '.token')
+
+# 3. Browse games for 6 players
+curl "http://localhost:5000/api/games?playerCount=6"
+
+# 4. Pick a game for 6 players
+PICK=$(curl -s -X POST http://localhost:5000/api/pick \
+  -H "Content-Type: application/json" \
+  -d '{"playerCount": 6}')
+GAME_ID=$(echo $PICK | jq -r '.game.id')
+
+# 5. Start session
+SESSION=$(curl -s -X POST http://localhost:5000/api/sessions \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"notes": "Friday game night"}')
+SESSION_ID=$(echo $SESSION | jq -r '.id')
+
+# 6. Add picked game to session
+curl -X POST "http://localhost:5000/api/sessions/$SESSION_ID/games" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"game_id\": $GAME_ID, \"room_code\": \"ABCD\"}"
+
+# 7. Close session when done
+curl -X POST "http://localhost:5000/api/sessions/$SESSION_ID/close" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"notes": "Great session!"}'
+```
+
+This assumes `jq` is installed for JSON parsing. Without it, extract IDs manually from the JSON responses.