# Jackbox Ecast API Reverse Engineering — Design

**Date:** 2026-03-20
**Goal:** Produce comprehensive documentation of the Jackbox ecast API (REST + WebSocket) through live traffic analysis.
**Deliverable:** `docs/jackbox-ecast-api.md`

## Scope

### In Scope

1. **Ecast REST API** — All discoverable endpoints at `ecast.jackboxgames.com`, including undocumented paths, multiple API versions, and different HTTP methods.

2. **Ecast WebSocket Protocol** — Full bidirectional message protocol between `jackbox.tv` and ecast servers: connection handshake, all opcodes/message types, entity model, and state transitions through the complete game lifecycle.

3. **Player & Room Management** — Join/leave detection, real-time player count, max players, lobby lock/game start signals, game completion signals, player and game stats/results.

### Out of Scope

- Kosmi integration (chrome extension)
- This application's own API
- Game-specific mechanics (drawing, voting within Drawful 2) unless they reveal useful metadata

## Approach

**Primary: REST probing + browser console WebSocket interception (Approach A)**
**Fallback: Puppeteer + CDP automated capture script (Approach B)**

### Phase 1 — REST API Probing

- Probe known endpoint `GET /api/v2/rooms/{code}` and document full response
- Discover new paths: `/players`, `/audience`, `/state`, etc.
- Try API versions `v1`, `v3`
- Check for discovery endpoints (`/api`, `/swagger`, `/openapi`, `/health`)
- Try different HTTP methods (POST, PUT, OPTIONS)
- Document all response schemas, headers, status codes

### Phase 2 — WebSocket Interception

- Navigate to `jackbox.tv` in browser
- Inject WebSocket interceptor (monkey-patch `WebSocket`) before joining room
- Join as player — capture full connection lifecycle
- Join as audience — capture audience-specific messages
- If injection races with connection, reload page after patching

### Phase 3 — Game Lifecycle Capture

Walk through entire Drawful 2 lifecycle with interceptor running:
- Lobby: join/leave messages, player list updates
- Game start: lock signal, round info
- Gameplay: state transitions, metadata
- Game end: results, stats, disconnection sequence
- Multiple players to observe multi-player messages

### Fallback (Approach B)

If browser console interception is unreliable, write a Node.js script using Puppeteer + CDP `Network.webSocketFrame*` events for automated structured capture.

## Documentation Structure

The deliverable (`docs/jackbox-ecast-api.md`) will contain:

1. **Overview** — What ecast is, base URLs, architecture
2. **REST API Reference** — Each endpoint with method, URL, params, response schema, notes
3. **WebSocket Protocol Reference** — Connection details, message format, message catalog (all opcodes), entity model
4. **Game Lifecycle** — Sequence diagram of message flow from room creation through completion
5. **Player & Room Management** — Answers to specific questions (join/leave detection, player count, max players, lock/start, completion, stats) with supporting evidence
6. **Appendix: Raw Captures** — Sanitized example payloads