API Reference

BotPyle has two communication interfaces: an HTTP API for bot registration and a WebSocket relay for real-time video and control.

Bot Registration API

POST /register_bot

Called by bot firmware on startup. Creates or updates a bot record.

Request Body (JSON): 
{
    "email": "owner@example.com",   // Owner's registered email
    "mac_address": "AA:BB:CC:DD:EE:FF"  // Bot's MAC address (unique ID)
}
Response (JSON): 
{
    "id": 1,
    "user_id": 1,
    "name": "owner's bot",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "streaming_port": 8090,
    "status": "online",
    ...
}

The streaming_port tells the bot which port to connect its WebSocket to for the relay.

WebSocket Relay Protocol

The relay server bridges the bot's video stream to the pilot's browser and the pilot's gamepad input back to the bot.

Connection
// Bot connects to:
ws://botpyle.com:{streaming_port}

// Browser connects to same port via streamer.js
// The relay auto-detects which is the bot (binary frames)
// and which is the browser (text frames).
Bot → Browser (Video)
  • Bot sends binary WebSocket frames containing JPEG-encoded images
  • Recommended resolution: 320×240 or 640×480
  • Recommended quality: 40–60 (JPEG quality parameter)
  • Target frame rate: 10–30 fps depending on bandwidth
Browser → Bot (Controls)
  • Browser sends text WebSocket frames containing JSON gamepad data
  • Sent at ~30 fps (matching the browser's requestAnimationFrame)
Gamepad Data Format:
{
    "axes": [0.0, -0.75, 0.1, 0.0],  // [leftX, leftY, rightX, rightY]
    "buttons": [0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    // 1 = pressed, 0 = released
    // Index matches Standard Gamepad API
}

Authentication

  • Bot registration — no authentication required (identified by owner email + MAC address)
  • WebSocket relay — no authentication on the WebSocket itself (secured by port assignment)
  • Web app — standard Laravel session auth (login, register, OAuth)

Rate Limits

  • Bot registration: 10 requests/minute per IP
  • WebSocket: no rate limit (streaming requires high throughput)
  • Web API: Laravel default throttle (60 requests/minute)