API reference

Endpoints

Endpoint Details

GET /api/health

Returns server health status and which API keys are available from environment variables.

Response:

{
  "ok": true,
  "timestamp": "2026-01-15T10:30:00.000Z",
  "keysPresent": ["google", "openai"],
  "envKeys": ["google"]
}

GET /api/providers

Returns the status of all known providers — whether they have keys configured and whether those keys came from environment variables.

Response:

{
  "google": { "hasKey": true, "isEnv": true },
  "openai": { "hasKey": false, "isEnv": false },
  "anthropic": { "hasKey": true, "isEnv": false }
}

POST /api/test-key

Validates an API key by making a lightweight request to the provider.

Request:

{
  "providerId": "openai",
  "apiKey": "sk-proj-..."
}

Response:

{ "ok": true }

GET /api/models/:providerId

Lists available models for a provider. Currently supported: openai, google, groq, mistral, openrouter.

Response:

{
  "data": [
    { "id": "gpt-4o", "name": "GPT-4o" },
    { "id": "gpt-4o-mini", "name": "GPT-4o Mini" }
  ]
}

POST /api/keys

Stores or clears an API key on the server side.

Request:

{
  "providerId": "anthropic",
  "key": "sk-ant-..."
}

To clear a key, send null or empty string as the key.

POST /api/compute/v1

The primary generation endpoint. Accepts a structured prompt and returns either raw text or a parsed JSON object.

Request:

{
  "prompt": { "system": "...", "user": "..." },
  "modelId": "gemini-3.7-flash",
  "providerId": "google",
  "options": { "temperature": 0.7, "maxTokens": 4096 },
  "apiKey": "optional-client-key"
}

The prompt can also include a schema field for structured output, or messages array for multi-turn conversation.

Fallback behavior: If the primary provider fails, the server tries the server-side key, then falls back to Google Gemini if available. If all external calls fail, it activates the built-in local synthesis engine for architect requests.

POST /api/agent/compile-stream

Streaming endpoint for the Agent Architect. Returns Server-Sent Events (SSE) with progressive stages:

1. stage event — intent analysis
2. partial event — manifest metadata
3. partial event — identity & soul
4. partial event — operational rules
5. partial event — domain skills
6. complete event — final specification

Response format:

event: stage
data: {"stage":"intent","label":"Parsing intent...","progress":15}

event: partial
data: {"stage":"manifest","label":"Drafting manifest...","progress":35,"data":{...}}

event: complete
data: {"stage":"done","progress":100,"object":{...}}

data: [DONE]

POST /api/stream

General-purpose streaming generation endpoint. Returns SSE chunks of generated text.

Response format:

data: {"chunk":"Hello"}

data: {"chunk":" world"}

data: [DONE]

Environment Variable Mapping

The server maps environment variables to provider IDs. Multiple env var names are checked per provider:

Keys from environment variables are used as fallbacks when client-side keys are not provided or fail validation.

Default Models

When no model ID is specified, the server defaults to: