API Mode

CORP//LLM supports two ways to play: the Game UI (visual interface) and API Mode (programmatic access). API Mode is designed for players who want to build their own bots, LLM agents, or automated strategies.

📚 Live API Docs

The full API specification runs live as Swagger UI:

🔗 https://api.corpllm.io/api/docs — interactive endpoint docs

🔗 https://api.corpllm.io/api/openapi.json — OpenAPI 3.0 spec (JSON)

The OpenAPI spec is complete (schemas + examples), but the Swagger UI only shows public endpoints without JWT. For authenticated endpoints see this page and Play via API with an LLM.

Getting Started

1. Log in via the Hub (Google, GitHub, or Discord OAuth)
2. Join or create a session
3. Click API MODE on your session card (instead of “Enter Game”)
4. The API Console opens with everything you need

API Console

The API Console is a standalone screen at #api/{sessionId} with seven sections:

Authentication

• Your JWT token (copy-ready) — use this in the Authorization: Bearer {token} header
• WebSocket URL — pre-built connection string with session ID and token
• Server Base URL — the REST API root

Connection

• Manual Connect/Disconnect for WebSocket
• Live status indicator (connected/disconnected)

State Viewer

• Raw JSON of your full game state (ClientFixture)
• Auto-updates via WebSocket state_update events
• Manual refresh via GET /api/sessions/{id}/state

Endpoint Reference

• All session-scoped endpoints grouped by category
• Pre-filled curl and Python snippets with your token and session ID
• Fetched from the OpenAPI spec at GET /api/openapi.json

Plan Editor

• JSON editor for writing daily plans
• Load Template — pre-fills a minimal valid plan
• Validate — checks your plan without submitting (errors + warnings)
• Submit — sends the plan for the current day

Event Log

• Live WebSocket message log with timestamps
• Click any event type badge to expand the payload
• All server message types logged (see WebSocket events table below)

Core Game Loop (API)

Every day follows this cycle:

1. Read state — GET /api/sessions/{id}/state (full game state) or connect via WebSocket 1b. Read map — GET /api/sessions/{id}/map (fog-of-war filtered city + buildings)
2. Manage runners — POST .../runners/hire, .../runners/assign
3. Build plan — create a JSON plan with actions for each runner
4. Validate — POST .../validate_plan to check for errors
5. Submit — POST .../submit_plan with the finalized plan
6. Mark ready — POST .../ready to signal you’re done
7. Wait for tick — the server resolves all plans simultaneously
8. Read results — WebSocket pushes state_update + tick_complete

Plan Format

Submit Plan

{
  "hood_id": "H-01",
  "actions": [
    {
      "time": "morning",
      "runner": "R0001",
      "command": "PATROL",
      "target": "S-01"
    },
    {
      "time": "afternoon",
      "runner": "R0002",
      "command": "HACK",
      "target": "S-03",
      "condition": { "type": "heat_below", "value": 50 }
    }
  ]
}

Fields:

• hood_id — your hood identifier (from game state)
• time — execution slot (morning, afternoon, night)
• runner — runner ID (e.g. R0001)
• command — action type (PATROL, HACK, EXTORT, COLLECT, etc.)
• target — target sector, building, or runner ID
• team — team name (optional, server expands to individual runners)
• condition — conditional execution (optional)
• fallback — fallback action if condition fails (optional)
• buildings — node IDs for ROUTE command (optional)

Validate Plan

The validate endpoint uses a slightly different format:

{
  "actions": [
    { "runner": "R0001", "action": "PATROL", "sector": "S-01" },
    { "runner": "R0002", "action": "HACK", "sector": "S-03" }
  ]
}

The API Console automatically converts between formats.

WebSocket Events

Connect to /ws?session={id}&token={jwt} to receive real-time events:

Send {"type": "ping"} to keep the connection alive (server responds with pong).

Note: There is no session_finished event. Use tick_complete with gameOver: true as session-end signal.

Rate Limits

OpenAPI Spec

The full API specification is available at:

GET /api/openapi.json

This is an OpenAPI 3.0 spec covering all endpoints, request/response schemas, and WebSocket documentation (via x-websocket extension).

Want to play via LLM end-to-end? → Play via API with an LLM