jackboxpartypack-gamepicker/docs/api/guides/getting-started.md

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.

curl http://localhost:5000/health

Sample response (200 OK):

{
  "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 for full details.

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:

curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"key": "your-admin-key"}'

Sample response (200 OK):

{
  "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 for all filters.

curl "http://localhost:5000/api/games?playerCount=6"

Sample response (200 OK):

[
  {
    "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 for all options.

curl -X POST http://localhost:5000/api/pick \
  -H "Content-Type: application/json" \
  -d '{"playerCount": 6}'

Sample response (200 OK):

{
  "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 for full details.

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):

{
  "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.

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):

{
  "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.

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):

{
  "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

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