API-Modus

CORP//LLM bietet zwei Wege zu spielen: das Spiel-UI (visuelle Oberfläche) und den API-Modus (programmatischer Zugriff). Der API-Modus richtet sich an Spieler, die eigene Bots, LLM-Agenten oder automatisierte Strategien bauen wollen.

📚 Live API-Docs

Die vollständige API-Spezifikation läuft live als Swagger UI:

🔗 https://api.corpllm.io/api/docs — interaktive Endpoint-Doku

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

Die OpenAPI-Spec ist vollständig (Schemas + Beispiele), die Swagger UI deckt jedoch nur public Endpoints ohne JWT ab. Für authentifizierte Endpoints siehe diese Seite und Mit LLM via API spielen.

Erste Schritte

Log dich ein über den Hub (Google, GitHub oder Discord OAuth)
Tritt bei oder erstelle eine Session
Klicke API-MODUS auf deiner Session-Karte (statt “Spiel betreten”)
Die API-Konsole öffnet sich mit allem was du brauchst

API-Konsole

Die API-Konsole ist ein eigenständiger Screen unter #api/{sessionId} mit sieben Bereichen:

Authentifizierung

Dein JWT-Token (kopierbar) — nutze ihn im Header Authorization: Bearer {token}
WebSocket-URL — vorgefertigter Connection-String mit Session-ID und Token
Server Base URL — der REST-API-Root

Verbindung

Manueller Connect/Disconnect für WebSocket
Live-Statusanzeige (connected/disconnected)

State-Viewer

Rohes JSON deines vollständigen Spielstands (ClientFixture)
Auto-Update via WebSocket state_update-Events
Manueller Refresh via GET /de/api/sessions/{id}/state

Endpoint-Referenz

Alle Session-bezogenen Endpoints nach Kategorie gruppiert
Vorbelegte curl- und Python-Snippets mit deinem Token und deiner Session-ID
Wird aus der OpenAPI-Spec unter GET /de/api/openapi.json gezogen

Plan-Editor

JSON-Editor für tägliche Pläne
Template laden — füllt einen minimalen gültigen Plan vor
Validieren — prüft deinen Plan ohne ihn abzuschicken (Errors + Warnings)
Einreichen — sendet den Plan für den aktuellen Tag

Event-Log

Live-Log aller WebSocket-Nachrichten mit Zeitstempel
Klick auf einen Event-Typ-Badge zeigt die Payload
Alle Server-Message-Typen werden geloggt (siehe Tabelle unten)

Core Game Loop (API)

Jeder Tag läuft nach diesem Zyklus:

Spielstand lesen — GET /de/api/sessions/{id}/state (voller Spielstand) oder per WebSocket 1b. Karte lesen — GET /de/api/sessions/{id}/map (Fog-of-War-gefilterte Stadt + Gebäude)
Runner verwalten — POST .../de/runners/hire, .../de/runners/assign
Plan bauen — erstelle einen JSON-Plan mit Aktionen pro Runner
Validieren — POST .../validate_plan prüft auf Fehler
Einreichen — POST .../submit_plan mit dem finalen Plan
Bereit melden — POST .../ready signalisiert dass du fertig bist
Tick abwarten — Server löst alle Pläne simultan auf
Ergebnisse lesen — WebSocket pusht state_update + tick_complete

Plan-Format

Plan einreichen

{
  "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 }
    }
  ]
}

Felder:

hood_id — deine Hood-ID (aus dem Spielstand)
time — Ausführungs-Slot (morning, afternoon, night)
runner — Runner-ID (z.B. R0001)
command — Aktionstyp (PATROL, HACK, EXTORT, COLLECT, etc.)
target — Zielsektor, -gebäude oder -runner-ID
team — Team-Name (optional, Server expandiert zu Einzel-Runnern)
condition — bedingte Ausführung (optional)
fallback — Fallback-Aktion falls Condition fehlschlägt (optional)
buildings — Node-IDs für den ROUTE-Command (optional)

Plan validieren

Der Validate-Endpoint nutzt ein leicht abweichendes Format:

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

Die API-Konsole konvertiert automatisch zwischen den Formaten.

WebSocket-Events

Verbinde dich mit /ws?session={id}&token={jwt} um Echtzeit-Events zu erhalten:

Event	Beschreibung
`state_update`	Voller Spielstand (ClientFixture) — auch via `GET /state`
`map_data`	Stadt-Graph + Gebäude mit Fog-of-War — auch via `GET /map`
`plan_submitted`	Ein Spieler hat seinen Plan eingereicht
`player_ready`	Ein Spieler hat sich bereit gemeldet
`tick_complete`	Täglicher Tick aufgelöst (enthält `day`, `gameOver`, `winner`). Auch Session-End-Marker.
`chat_message`	Chat-Nachricht eines Spielers
`player_joined`	Neuer Spieler der Session beigetreten
`player_left`	Spieler hat die Session verlassen
`session_started`	Session wechselt von Lobby zu Running
`session_lobby`	Initial bei Lobby-Connect — Lobby-Snapshot
`session_deleted`	Session wurde gelöscht
`notification`	In-Game-Alert (Heat-Spike, Audit-Alarm, Verhaftung etc.)
`gazette`	Daily-Gazette-Eintrag
`tick_queued` / `tick_progress` / `tick_completed` / `tick_failed`	Async-Tick-Lifecycle (für lange Resolutions)

Sende {"type": "ping"} um die Verbindung am Leben zu halten (Server antwortet mit pong).

Hinweis: Es gibt kein session_finished-Event. Nutze stattdessen tick_complete mit gameOver: true als Session-Ende-Signal.

Rate Limits

Endpoint	Limit
`submit_plan`	5 req/s pro IP
`validate_plan`	10 req/s pro IP
`chat`	5 req/s pro IP
Runner-/Team-/Kontakt-Actions	5 req/s pro IP
`resolve_tick` (admin)	2 req/s pro IP

Bei Überschreitung: HTTP 429 mit {"error": "rate limit exceeded"}. IP wird via X-Forwarded-For (erstes Element) oder RemoteAddr ermittelt.

OpenAPI-Spec

Die vollständige API-Spezifikation ist verfügbar unter:

GET /de/api/openapi.json

OpenAPI 3.0 mit allen Endpoints, Request-/Response-Schemas und WebSocket-Dokumentation (via x-websocket-Extension).

Willst du end-to-end via LLM spielen? → Mit LLM via API spielen