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

1.8 KiB

Raw Blame History

Stats Endpoints

Aggregate statistics about the game library, sessions, and popularity.

Endpoint Summary

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

GET /api/stats

Return aggregate statistics: game counts, pack count, session counts, total games played, most-played games, and top-rated games.

Authentication

None.

Response

200 OK

{
  "games": { "count": 89 },
  "gamesEnabled": { "count": 75 },
  "packs": { "count": 9 },
  "sessions": { "count": 12 },
  "activeSessions": { "count": 1 },
  "totalGamesPlayed": { "count": 156 },
  "mostPlayedGames": [
    {
      "id": 42,
      "title": "Quiplash 3",
      "pack_name": "Jackbox Party Pack 7",
      "play_count": 15,
      "popularity_score": 8,
      "upvotes": 10,
      "downvotes": 2
    }
  ],
  "topRatedGames": [
    {
      "id": 42,
      "title": "Quiplash 3",
      "pack_name": "Jackbox Party Pack 7",
      "play_count": 15,
      "popularity_score": 8,
      "upvotes": 10,
      "downvotes": 2
    }
  ]
}

Field	Description
games.count	Total number of games in the library
gamesEnabled.count	Number of enabled games
packs.count	Number of distinct packs
sessions.count	Total sessions (all time)
activeSessions.count	Sessions with `is_active = 1`
totalGamesPlayed.count	Total game plays across all sessions
mostPlayedGames	Top 10 games by `play_count` DESC (only games with `play_count` > 0)
topRatedGames	Top 10 games by `popularity_score` DESC (only games with `popularity_score` > 0)

Error Responses

Status	Body	When
500	`{ "error": "..." }`	Server error

Example

curl "http://localhost:5000/api/stats"

1.8 KiB Raw Blame History