API DOCS

Everything the streamer menu can do, a bot or plugin can do too: through a REST API, a live event stream (SSE), or an MCP server that an LLM can use as tools. All three call the same game actions.

Base URL: the game server, http://localhost:2087 on the streamer's PC (port from PORT).

The browser version (play.subspacebrawl.com) has no API: no REST, event stream or MCP server (a browser tab can't serve one). Use the desktop app for bots and plugins.

Versions #

The API is versioned on its own, separately from the game (game 0.9.x until the Steam launch = 1.0.0):

• API version (now 1.1.0): GET /api/v1/version → { "game": "0.9.0", "api": "1.1.0" }; the MCP server reports it too. Major = the /api/vN path: a breaking change gets /api/v2 (v1 keeps working for a while). Minor = something new (a route, a field, an MCP tool, an event). Patch = a fix or a docs correction.
• Everything below documents the current version; each change gets a line in the changelog.

Changelog #

• 1.1.0: GET /version; ability ram (old name boost still accepted) and mine; fields (POST /field, MCP set_field); scripts on game events; PATCH /bots/:login; boss damage board; seasons; laser skins.
• 1.0.0: first documented API: game, menus, pilots and effects, overlay, redeems, scripts, events, MCP.

Auth #

1. Open the streamer menu (/admin), connect Twitch, then API & MCP → Make new API key.
2. Copy the key (sbk_…). It's shown once; only its hash is stored. Making a new key replaces the old one.
3. Send it on every request: Authorization: Bearer sbk_…

Wrong or missing key → 401. Bad input → 400 { "error": "…" }. Anything else failing → 500 { "error": "…" }.

Keep the key secret: it can change every setting and run the show.

REST API (/api/v1) #

Request and response bodies are JSON.

Game #

Menus #

The game starts on its title screen. Menu pages show on every overlay (desktop and vertical) at once.

round.phase is menu, lobby or playing; round.overlay.menu is the open page (or null).

Pilots and effects #

Effect ids: calamity:random, calamity:meteorShower, calamity:iceStorm (Ice Shower; the id kept its old name), calamity:thunderStorm, calamity:blackHole, calamity:radiationLeak, calamity:blizzard, nuke, mines (mine supply: +3 mine charges, over the max), emp, grow, bounty (input = target name), trail (input = style: rainbow, fire, neon, sparkler, galaxy, stars, hearts, confetti, snow, bubbles, notes, smoke, pixels, emotes; Halloween: pumpkins, ghosts, bats, toxic, scythe; Christmas: bells, candycanes, gingerbread, ornaments; usb; halloween / christmas = a random one of those; or an emoji; or emote:<id>), shield (shield skin, input = the same themes), explosion (death explosion, input = the same themes; the pilot's missiles and mines blow up in it too), laser (laser skin for the pilot's shots, input = rainbow, fire, plasma, hearts, carrots, snowballs, candycanes, pumpkins, bubbles, notes, stars, pixels; or an emoji; or emote:<id>), missiles. Unknown input = a random one; each lasts trailMinutes. missiles = +3 missile charges, over the max. Effects with needsPilot need a pilot who is flying right now.

Overlay #

Screens: game, leaderboard (today / week / month boards).

Channel point redeems #

Unlinked rewards still work by keywords in their title ("Spawn Calamity", "Drop Mines", "EMP", "Shield Skin", "Laser Skin"…). The streamer menu has the same thing as a searchable list.

Scripts (owner only) #

The streamer's own scripts (the game's SCRIPTS page): JavaScript, TypeScript, Python or Lua, run when a channel point reward is redeemed, a chat command is typed or a game event happens (round end, kill, boss defeated…). Only the API key or the streamer's own session reaches these; the extension's token gets 403. Secret values go in and never come back out of any route.

language: js, ts, python, lua. trigger: { "type": "command", "command": "hydrate" } (for !hydrate), { "type": "reward", "rewardId": "…", "rewardTitle": "…" }, { "type": "event", "event": "round.end" } (any name in the events table below except relay / extension; { "type": "roundEnd" } / { "type": "roundStart" } are short for round.end / round.start) or { "type": "none" } (test runs only).

A script's event: reward / command runs get { type, trigger, user, displayName, userId, platform, reward, command, input, bits }. Game-event runs get that event's fields (as in the events table) plus type (the event name), trigger (event, or test) and at, except these two, reshaped for scripts:

• round.end: { mode, modeName, result, winnerTeam ("Red"… or null), winners: [row], players: [row] (results order, winners first), bitLeaders: [{ name, bits }], startedAt, endedAt, durationSeconds }; row = { place, name, login (null: bot), bot, team (name or null), won, kills, deaths, assists, friendlyKills, damage, lastShots }.
• round.start: { mode, modeName, pilots (count), teams: [names], roster: [{ name, login, bot, team }], field, fieldName }.

Busy events (kill can fire many times a second) don't pile up: a script that already has a run waiting skips the newer event; at most 3 scripts run at once and 30 wait (more are dropped with a console warning). Output kind: log, error or say. Each run is its own sandboxed process (10 s, 256 MB); see the SCRIPTS section of the game's docs.

Twitch connect (owner only, like scripts) #

State shape #

{
  "round": {
    "mode": "dogfight", "phase": "playing", "remaining": 412000,
    "scores": [12, 9], "reserves": [0, 0], "fleetSize": 30,
    "result": null, "lobby": null, "calamities": [], "bounties": [], "season": "halloween", "field": "earth",
    "stats": null, "overlay": { "announcement": null, "screen": "game" },
    "bosses": [{ "name": "Leviathan", "phase": "fighting", "hp": "Good", "shield": "up", "rage": 1 }]
  },
  "pilots": [
    {
      "id": "chat:bob", "name": "bob", "team": 0, "bot": false, "alive": true,
      "hp": 100, "kills": 3, "deaths": 1, "assists": 2, "damage": 0, "lives": null, "missiles": 1, "mines": 1, "ship": "…"
    }
  ],
  "settings": { "mode": "dogfight", "…": "…" }
}

Modes: dogfight (Factions), reserves (Fleet Reserves), ffa, ffaReserves, boss (every pilot against a boss, shared lives). A saved supernova (removed) loads as boss. A boss's HP is never a number anywhere: Good / Fair / Low (the thirds). A pilot's damage (and dmg in round stats) = what their hits on bosses and boss craft were worth this round (raw hits, shields and all, nothing for a raised dome): pilots' numbers, never the boss's HP. Calamities run in boss rounds too (bosses aren't pulled, pushed or hurt by them). phase is lobby between rounds, playing during one. field is where the round is fought (Fields.ts id; in a lobby the next round's, already rolled when the setting is random; also lobby.field). A pilot's ship is its ship's key : spaceShips_001.png…spaceShips_008.png for the 8 originals, a name like lancer or valkyrie for the newer ones.

Settings #

Out-of-range numbers are clamped; unknown values keep the old setting.

Events (GET /api/v1/events) #

Server-Sent Events: one event: <type> + data: <json> per game event, and a : ping comment every 25 s. Every event has type and at (ms timestamp).

// Node 18+: no library needed
const res = await fetch('http://localhost:2087/api/v1/events', {
  headers: { Authorization: `Bearer ${process.env.SPACE_API_KEY}` },
});
const decoder = new TextDecoder();
for await (const chunk of res.body) {
  for (const line of decoder.decode(chunk).split('\n')) {
    if (line.startsWith('data: ')) {
      console.log(JSON.parse(line.slice(6)));
    }
  }
}

(A real client should buffer partial lines across chunks; any SSE library does.)

MCP server (/mcp) #

Streamable HTTP, stateless, same API key. Tools:

Claude Code:

claude mcp add --transport http space-battle http://localhost:2087/mcp \
  --header "Authorization: Bearer sbk_…"

Any MCP client config:

{
  "mcpServers": {
    "space-battle": {
      "type": "http",
      "url": "http://localhost:2087/mcp",
      "headers": { "Authorization": "Bearer sbk_…" }
    }
  }
}

The MCP server only answers calls; for live events a bot reads /api/v1/events alongside it.

Writing a plugin #

A plugin is any program that listens to events and calls the API. Example: hype the top killer and show the boards at the end of every round.

const BASE = 'http://localhost:2087/api/v1';
const headers = {
  Authorization: `Bearer ${process.env.SPACE_API_KEY}`,
  'Content-Type': 'application/json',
};
const post = (path, body) => fetch(`${BASE}${path}`, {
  method: 'POST',
  headers,
  body: JSON.stringify(body),
});

function onEvent(event) {
  if (event.type === 'round.end' && event.stats?.length) {
    post('/overlay/announce', { text: `MVP: ${event.stats[0].name}`, color: '#ffd400', seconds: 8 });
    post('/overlay/screen', { screen: 'leaderboard', seconds: 12 });
  }
  if (event.type === 'kill' && event.friendly) {
    post('/bounties', { target: event.killer, by: 'the fleet' });
  }
}

Plug onEvent into the SSE reader above. An LLM bot works the same way: feed it events, give it the MCP tools.