8ba32e128c
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
121 lines
4.0 KiB
Markdown
121 lines
4.0 KiB
Markdown
# Picker Endpoints
|
||
|
||
Weighted random game selection. Picks from enabled games matching your filters, with favor bias affecting probability. Avoids recently played games within a session.
|
||
|
||
## Endpoint Summary
|
||
|
||
| Method | Path | Auth | Description |
|
||
|--------|------|------|-------------|
|
||
| POST | `/api/pick` | No | Pick a random game with filters and repeat avoidance |
|
||
|
||
---
|
||
|
||
## POST /api/pick
|
||
|
||
Select a game using weighted random selection. Filters to only enabled games, applies favor/disfavor bias to influence probability, and optionally excludes recently played games when a session is provided.
|
||
|
||
### Authentication
|
||
|
||
None.
|
||
|
||
### Request Body
|
||
|
||
All fields optional. Provide only the filters you want to apply.
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| playerCount | integer | No | Filter games where `min_players ≤ count ≤ max_players` |
|
||
| drawing | string | No | `"only"` = Drawing type only, `"exclude"` = exclude Drawing type |
|
||
| length | string | No | `"short"` (≤15 min or NULL), `"medium"` (16–25 min), `"long"` (>25 min) |
|
||
| familyFriendly | boolean | No | Filter by family-friendly rating |
|
||
| sessionId | integer | No | Session ID for repeat avoidance |
|
||
| excludePlayed | boolean | No | When `true`, exclude ALL games played in session. Default: exclude last 2 only |
|
||
|
||
```json
|
||
{
|
||
"playerCount": 6,
|
||
"drawing": "exclude",
|
||
"length": "short",
|
||
"familyFriendly": true,
|
||
"sessionId": 3,
|
||
"excludePlayed": false
|
||
}
|
||
```
|
||
|
||
### Filters
|
||
|
||
- **Enabled games only:** Only games with `enabled = 1` are considered.
|
||
- **playerCount:** Filters games where `min_players ≤ playerCount ≤ max_players`.
|
||
- **drawing:** `"only"` = games with `game_type = 'Drawing'`; `"exclude"` = games that are not Drawing type.
|
||
- **length:** `"short"` = ≤15 min (includes NULL); `"medium"` = 16–25 min; `"long"` = >25 min.
|
||
- **familyFriendly:** `true` or `false` filters by `family_friendly`.
|
||
|
||
### Weighted Selection
|
||
|
||
- **Game favor_bias:** `1` = 3× weight, `0` = 1× weight, `-1` = 0.2× weight.
|
||
- **Pack favor_bias:** `1` = 2× weight, `0` = 1× weight, `-1` = 0.3× weight.
|
||
- Game and pack biases multiply together.
|
||
|
||
### Repeat Avoidance (with sessionId)
|
||
|
||
- **Default (`excludePlayed: false`):** Excludes the last 2 played games in the session.
|
||
- **With `excludePlayed: true`:** Excludes ALL games played in the session.
|
||
|
||
### Response
|
||
|
||
**200 OK**
|
||
|
||
```json
|
||
{
|
||
"game": {
|
||
"id": 42,
|
||
"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": 15,
|
||
"totalEnabled": 17
|
||
}
|
||
```
|
||
|
||
| Field | Description |
|
||
|-------|-------------|
|
||
| game | Full game object for the selected game |
|
||
| poolSize | Number of games in the eligible pool after filters |
|
||
| totalEnabled | Approximate total enabled games (includes excluded when sessionId provided) |
|
||
|
||
### Error Responses
|
||
|
||
| Status | Body | When |
|
||
|--------|------|------|
|
||
| 404 | `{ "error": "No games match the current filters", "suggestion": "Try adjusting your filters or enabling more games" }` | No games match the filters |
|
||
| 404 | `{ "error": "All eligible games have been played in this session", "suggestion": "Enable more games or adjust your filters", "recentlyPlayed": [1, 5, 12] }` | All eligible games already played in session (when `excludePlayed: true`) |
|
||
| 404 | `{ "error": "All eligible games have been played recently", "suggestion": "Enable more games or adjust your filters", "recentlyPlayed": [1, 5] }` | Last 2 games are the only matches (when `excludePlayed: false`) |
|
||
| 500 | `{ "error": "..." }` | Server error |
|
||
|
||
### Example
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:5000/api/pick" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"playerCount": 6,
|
||
"drawing": "exclude",
|
||
"length": "short",
|
||
"familyFriendly": true,
|
||
"sessionId": 3,
|
||
"excludePlayed": false
|
||
}'
|
||
```
|