jackboxpartypack-gamepicker/docs/api/README.md

# Jackbox Game Picker API

## Overview

The API manages Jackbox Party Pack games, runs gaming sessions, tracks popularity via voting, picks games with weighted random selection, and notifies external systems via webhooks and WebSocket.

## Base URL

| Environment | Base URL | Notes |
|-------------|----------|-------|
| Local development | `http://localhost:5000` | Backend direct |
| Docker Compose | `http://localhost:3000/api` | Via Vite/Nginx proxy |

All REST endpoints are prefixed with `/api/` except `/health`.

## Authentication

1. **Login**: POST to `/api/auth/login` with JSON body:

   ```json
   { "key": "<admin-key>" }
   ```

   Returns a JWT token.

2. **Authorization**: Include the token in requests:
   ```
   Authorization: Bearer <token>
   ```

3. **Expiry**: Tokens expire in 24 hours.

### Public Endpoints (no auth required)

- `GET /api/games`
- `GET /api/games/packs`
- `GET /api/games/meta/packs`
- `GET /api/games/{id}`
- `GET /api/sessions`
- `GET /api/sessions/active`
- `GET /api/sessions/{id}`
- `GET /api/sessions/{id}/games`
- `GET /api/sessions/{id}/votes`
- `GET /api/sessions/{sessionId}/games/{sessionGameId}/status-live`
- `GET /api/votes`
- `GET /api/stats`
- `POST /api/pick`
- `GET /health`

All write and admin operations require authentication.

## Request/Response Format

- Request and response bodies use JSON. Set `Content-Type: application/json`.
- **Exceptions**:
  - `GET /api/games/export/csv` returns `text/csv`
  - `GET /api/sessions/{id}/export` returns `text/plain` or `application/json` depending on `format` query param

## Error Handling

All errors return:

```json
{ "error": "description" }
```

| Status | Meaning |
|--------|---------|
| 400 | Bad request / validation failure |
| 401 | No token provided |
| 403 | Invalid or expired token |
| 404 | Not found |
| 409 | Conflict (e.g. duplicate vote) |
| 500 | Server error |

Global error handler may include additional detail:

```json
{ "error": "Something went wrong!", "message": "<details>" }
```

## Boolean Fields

SQLite stores booleans as integers (0/1). In request bodies, pass JavaScript booleans (`true`/`false`); the API converts them. In responses, expect `0`/`1` for game and session fields. **Exception**: `Webhook.enabled` returns a JavaScript boolean.

## Pagination

Most list endpoints return full result sets. The exception is `GET /api/votes`, which supports pagination via `page` and `limit` query parameters (default: page 1, limit 50, max 100).

## Quick Reference

### Health

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/health` | No | Health check |

### Auth

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/auth/login` | No | Authenticate with admin key |
| POST | `/api/auth/verify` | Yes | Verify JWT token |

### Games

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/games` | No | List games with optional filters |
| POST | `/api/games` | Yes | Create a new game |
| GET | `/api/games/packs` | No | List all packs |
| GET | `/api/games/meta/packs` | No | List pack metadata |
| GET | `/api/games/export/csv` | Yes | Export games as CSV |
| POST | `/api/games/import/csv` | Yes | Import games from CSV |
| PATCH | `/api/games/packs/{name}/favor` | Yes | Update pack favor bias |
| PATCH | `/api/games/packs/{name}/toggle` | Yes | Enable or disable a pack |
| GET | `/api/games/{id}` | No | Get a game by ID |
| PUT | `/api/games/{id}` | Yes | Update a game |
| DELETE | `/api/games/{id}` | Yes | Delete a game |
| PATCH | `/api/games/{id}/toggle` | Yes | Toggle game enabled status |
| PATCH | `/api/games/{id}/favor` | Yes | Update game favor bias |

### Sessions

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/sessions` | No | List all sessions |
| POST | `/api/sessions` | Yes | Create a new session |
| GET | `/api/sessions/active` | No | Get the active session |
| GET | `/api/sessions/{id}` | No | Get a session by ID |
| DELETE | `/api/sessions/{id}` | Yes | Delete a session |
| POST | `/api/sessions/{id}/close` | Yes | Close a session |
| GET | `/api/sessions/{id}/games` | No | List games in a session |
| GET | `/api/sessions/{id}/votes` | No | Get per-game vote breakdown for a session |
| POST | `/api/sessions/{id}/games` | Yes | Add a game to a session |
| POST | `/api/sessions/{id}/chat-import` | Yes | Import chat log for vote processing |
| GET | `/api/sessions/{id}/export` | Yes | Export session |
| PATCH | `/api/sessions/{sessionId}/games/{sessionGameId}/status` | Yes | Update session game status |
| DELETE | `/api/sessions/{sessionId}/games/{sessionGameId}` | Yes | Remove game from session |
| PATCH | `/api/sessions/{sessionId}/games/{sessionGameId}/room-code` | Yes | Update room code for session game |
| POST | `/api/sessions/{sessionId}/games/{sessionGameId}/start-player-check` | Yes | Start room monitor for player count |
| POST | `/api/sessions/{sessionId}/games/{sessionGameId}/stop-player-check` | Yes | Stop room monitor |
| GET | `/api/sessions/{sessionId}/games/{sessionGameId}/status-live` | No | Get live game status from shard monitor |
| PATCH | `/api/sessions/{sessionId}/games/{sessionGameId}/player-count` | Yes | Update player count for session game |

### Picker

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/pick` | No | Pick a random game with optional filters |

### Stats

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/stats` | No | Get aggregate statistics |

### Votes

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/votes` | No | Paginated vote history with filtering |
| POST | `/api/votes/live` | Yes | Record a live vote (up/down) |

### Webhooks

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/webhooks` | Yes | List all webhooks |
| POST | `/api/webhooks` | Yes | Create a webhook |
| GET | `/api/webhooks/{id}` | Yes | Get a webhook by ID |
| PATCH | `/api/webhooks/{id}` | Yes | Update a webhook |
| DELETE | `/api/webhooks/{id}` | Yes | Delete a webhook |
| POST | `/api/webhooks/test/{id}` | Yes | Send test webhook |
| GET | `/api/webhooks/{id}/logs` | Yes | List webhook delivery logs |

## Documentation Links

- [OpenAPI Spec](openapi.yaml)
- **Endpoint docs**: [Auth](endpoints/auth.md), [Games](endpoints/games.md), [Sessions](endpoints/sessions.md), [Picker](endpoints/picker.md), [Stats](endpoints/stats.md), [Votes](endpoints/votes.md), [Webhooks](endpoints/webhooks.md)
- [WebSocket Protocol](websocket.md)
- **Guides**: [Getting Started](guides/getting-started.md), [Session Lifecycle](guides/session-lifecycle.md), [Voting & Popularity](guides/voting-and-popularity.md), [Webhooks & Events](guides/webhooks-and-events.md)