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:

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

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

{ "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
• Endpoint docs: Auth, Games, Sessions, Picker, Stats, Votes, Webhooks
• WebSocket Protocol
• Guides: Getting Started, Session Lifecycle, Voting & Popularity, Webhooks & Events