REST API Reference

Direct HTTP API for room management.

Base URL

https://watchtower-api.watchtower-host.workers.dev

Authentication

All requests require:

Authorization: Bearer wt_live_your_api_key
X-Player-ID: unique-player-identifier

Rooms API

Create Room

POST/v1/rooms

Create a new room. You become the host.

Response

{
  "code": "ABCD",
  "wsUrl": "wss://watchtower-api.watchtower-host.workers.dev/v1/rooms/ABCD/ws"
}

Get Room Info

GET/v1/rooms/:code

Get room info without joining.

Response

{
  "gameId": "my-game",
  "hostId": "player-123",
  "createdAt": 1706400000000,
  "playerCount": 3,
  "players": [
    { "id": "player-123", "joinedAt": 1706400000000 },
    { "id": "player-456", "joinedAt": 1706400100000 }
  ]
}

Join Room (HTTP)

POST/v1/rooms/:code/join

Join a room via HTTP (for initial join before WebSocket).

Response

{
  "success": true,
  "gameId": "my-game",
  "hostId": "player-123",
  "players": [...]
}

Join Room (WebSocket)

WS/v1/rooms/:code/ws?playerId=...&apiKey=...

Upgrade to WebSocket for real-time communication. Pass apiKey as query param (WebSocket can't send headers).

Error Responses

Code	Meaning
`400`	Bad request (missing params, invalid JSON)
`401`	Unauthorized (missing/invalid API key)
`404`	Not found (room code)
`500`	Server error

cURL Examples

# Create room
curl -X POST https://watchtower-api.watchtower-host.workers.dev/v1/rooms \
  -H "Authorization: Bearer wt_live_xxx" \
  -H "X-Player-ID: player-123"

# Get room info
curl https://watchtower-api.watchtower-host.workers.dev/v1/rooms/ABCD \
  -H "Authorization: Bearer wt_live_xxx" \
  -H "X-Player-ID: player-123"