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.

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