Reference

REST API

The FastAPI server runs in-process with the bot and exposes versioned endpoints under /api/v1. Authentication uses HMAC-SHA256 signed session tokens, and no secrets are ever sent to the KSP client.

Base URL

By default the server listens on port 5022. The mod builds the base URL from its serverProtocol, serverHost and serverPort settings.

{serverProtocol}://{serverHost}:{serverPort}/api/v1

Authentication

Linking exchanges a one-time 6-digit code for a 30-day signed session token. That token is sent on every authenticated request; the server’s signing secret never leaves the bot.

Authenticated request

GET /api/v1/contracts
Authorization: Bearer <session-token>

Two-step auth flow

See api_auth.py: generate a code (10-minute TTL in Firestore), then validate it to issue the signed token.

Endpoints

The table below shows representative endpoints grouped by purpose. Auth column indicates whether a valid session token is required.

Method	Endpoint	Description	Auth
POST	`/api/v1/link/validate` Exchange a 6-digit code for a signed session token.	Exchange a 6-digit code for a signed session token.	Public
GET	`/api/v1/me` Return the linked member's profile and balance.	Return the linked member's profile and balance.	Token
GET	`/api/v1/contracts` List contracts available to the player.	List contracts available to the player.	Token
POST	`/api/v1/contracts/{id}/accept` Accept a contract and inject it in-game.	Accept a contract and inject it in-game.	Token
POST	`/api/v1/contracts/{id}/submit` Submit vessel telemetry for verification.	Submit vessel telemetry for verification.	Token
GET	`/api/v1/missions/weekly` Fetch the current week's missions and their types.	Fetch the current week's missions and their types.	Token

Illustrative surface

These routes show the API’s shape and conventions. The definitive contract is the code in api_server.py.

Mission classification

When the mod asks for weekly missions, the server returns each one tagged as a craft_build or active_vessel objective. That classification is produced once per week (by Gemini, or a keyword fallback) and cached in Firestore.

Example response

{
  "week": "2026-W25",
  "missions": [
    { "id": "m1", "type": "craft_build",   "text": "Build a reusable SSTO." },
    { "id": "m2", "type": "active_vessel",  "text": "Land a rover on Duna." }
  ]
}

PreviousMod Settings File