HyperSpaceOut/jackboxpartypack-gamepicker

Files

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

4.0 KiB

Raw Blame History

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

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

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

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
  }'

4.0 KiB Raw Blame History Unescape Escape