REST & WebSocket API

Forven runs a local FastAPI server. The desktop UI talks to it over HTTP on 127.0.0.1, and the same API is available to you for scripting, integrations, and diagnostics. This page is the developer reference: the base URL, how authentication works, the endpoint catalog grouped by router, the /ws/live WebSocket feed, and the deprecated routes scheduled for removal.

This is a local-first API. By default it binds to loopback only, the keys live on your machine, and nothing is exposed to the internet. If you only use the desktop app you never touch this directly — but everything the app does, you can do over HTTP.

Base URL

The server listens on http://127.0.0.1:8003 by default. Two settings change that, both via environment variables:

• FORVEN_PORT — the listen port (default 8003). A startup guard detects port collisions.
• FORVEN_BIND_HOST — the bind address (default 127.0.0.1, loopback only). Set this for LAN or dev access.

A DNS-rebinding guard rejects unexpected Host headers; the allowed set (FORVEN_ALLOWED_HOSTS) defaults to 127.0.0.1, localhost, [::1], and testserver. Browser calls are constrained by CORS — FORVEN_CORS_ORIGINS defaults to the local SvelteKit dev origins (http://127.0.0.1:5173, http://localhost:5173).

Almost every route is mounted under the /api prefix. The WebSocket feed and the /verdict/* routes are the notable exceptions.

Authentication

Forven has two keys with different privilege levels. Both are read from request headers and configured through environment variables.

How the two layers stack

1. ApiKeyMiddleware runs before route dispatch and checks FORVEN_API_KEY on all requests except /api/health, /api/webhooks/*, /api/shutdown, and OPTIONS. A mismatch returns 401 as a plain JSON response.
2. require_operator_access is a FastAPI dependency applied at the router level on operator-gated routers. It validates FORVEN_OPERATOR_KEY and returns 401 if the key is missing or invalid, 503 if no operator key is configured at all.

In the endpoint catalog below, "operator-gated" means the whole router carries require_operator_access — every route in it needs the operator key.

Enforcement and the dev default

If FORVEN_API_KEY is unset, the API runs unauthenticated and logs a warning. That is acceptable for a loopback-only dev session; it is not acceptable for anything exposed.

Set FORVEN_AUTH_REQUIRED=true to make this a hard guarantee. When it is true, the server refuses to start unless both FORVEN_API_KEY and FORVEN_OPERATOR_KEY are set. Packaged builds use this to enforce authentication; the default is false for local development.

# Authenticated request to a baseline endpoint
$h = @{ "x-api-key" = $env:FORVEN_API_KEY }
Invoke-RestMethod -Uri "http://127.0.0.1:8003/api/health" -Headers $h

# Operator-gated endpoint needs both keys
$h = @{
  "x-api-key"      = $env:FORVEN_API_KEY
  "x-operator-key" = $env:FORVEN_OPERATOR_KEY
}
Invoke-RestMethod -Uri "http://127.0.0.1:8003/api/strategies" -Headers $h

Routes that skip auth by design

A handful of routes are intentionally auth-exempt:

• GET /api/health — liveness check, no auth.
• POST /api/shutdown — graceful shutdown, 127.0.0.1/::1 only, used by the Tauri shell to stop uvicorn. Returns 202.
• /api/webhooks/* — exempt from key auth but HMAC-checked; dev-only (disabled in packaged builds).
• The diagnostics, health-status, skills, deepdive, and sandbox-scan reads are exposed without operator gating as a frontend contract — see the catalog notes.

Endpoint catalog

The API surface is large — well over a hundred routes across more than two dozen routers. Rather than list every one, the tables below group them by router with representative endpoints. The pattern within a router is consistent: GET to read, POST/PUT/PATCH to mutate, DELETE to remove.

System, status & control plane

See Operations for the UI over these, and the scheduler page for the job catalog.

Strategies & lifecycle

The real pipeline stages are quick_screen → research_only → paper → live. (The marketing site calls the paper stage a "candidate"; the API uses paper.) Transitions respect a forward-only DAG — you cannot move a strategy backward from paper to research_only.

See the pipeline for what each stage means and promotion gates for the checks between them.

Backtesting, gauntlet & verdict

The verdict engine runs the same robustness battery as the gauntlet: sample_size, statistical_significance, walk_forward, monte_carlo, param_jitter, cost_stress, and regime_split. Stale workflows are recovered at startup (a step is considered stale after one minute of no progress).

Trading & emergency controls

Paper trading

The paper service is global, not per-strategy — starting it stops any prior session. Paper sessions never auto-promote to live; you advance them through /api/lifecycle/transition. See paper trading.

Agents, model policy & approvals

Agents never place trades or task each other directly. See agents and the approval queue; model routing is covered under models & providers.

Brain, routines & memory

Operator-created routines run without an approval; brain-authored routines go through the approval queue. See the brain, scheduled routines, and the memory bank.

MCP servers & tool grants

The full setup is covered on the MCP server page.

Bot factory

Bots marked running are re-spawned at startup, with a monitor thread handling heartbeat and restart. See the bot factory.

Hypotheses

Spawn limits (per-run and rolling-window) prevent exhaustion — POST /api/backtesting/strategies returns 422 when a limit is hit. See hypothesis-driven research.

Data, notifications & diagnostics

See managing market data, notifications, and health monitoring.

Settings, profile & sandbox

The sandbox is disabled by default; only /scan (pure AST, no execution) is always available. Everything that spawns a subprocess returns 503 until you enable it under Settings → Sandbox. The deepdive chat is server-sent events, not WebSocket; see deep-dive strategy chat.

WebSocket live feed

The live feed streams price ticks, order fills, indicator updates, and regime changes to connected clients. There are two equivalent routes:

• ws://127.0.0.1:8003/api/ws/live — the primary endpoint.
• ws://127.0.0.1:8003/ws/live — an alias for the same handler.

Both are backed by the same websocket_endpoint. Use the feed to drive live charts and dashboard widgets instead of polling the trade endpoints.

# Quick check that the WebSocket route is reachable (requires the wscat npm package)
wscat --connect "ws://127.0.0.1:8003/ws/live"

Response and error conventions

A few behaviours are worth knowing before you script against the API:

• 202 Accepted means queued work. POST /api/brain/chat returns a task_id; poll GET /api/brain/chat/{task_id}, which keeps returning 202 while the task runs.
• 502 from force-close signals a possible still-open position — re-verify, never assume.
• 503 means a capability is disabled (sandbox) or unconfigured (operator key) rather than broken.
• 422 from strategy creation usually means a hypothesis spawn limit was reached.
• The strategies router serializes with ORJSONResponse for large payloads; the response shape is plain JSON either way.
• A rate limiter (SlowAPI) is installed when available; if it cannot load, it fails open as a no-op.

Legacy API & sunset

Older integrations used /api/forven/* paths. A compatibility middleware rewrites every /api/forven/* request to /api/* before routing, so the legacy paths still work today but are marked deprecated. They are scheduled for removal on June 30, 2026.

Migrate by dropping the forven segment: /api/forven/strategies becomes /api/strategies. No other change is required.

Caveats

• Operator key is the real gate. Most useful routes are operator-gated; a baseline FORVEN_API_KEY alone will hit 401/503 on them.
• Unauthenticated by default in dev. With no key set the API is open. Set FORVEN_AUTH_REQUIRED=true (and both keys) before binding to anything other than loopback.
• Loopback-bound by design. Changing FORVEN_BIND_HOST widens exposure; pair it with authentication.
• Some reads are intentionally ungated (diagnostics, health, skills, sandbox scan) as a frontend contract — do not treat their availability as a sign that all routes are open.
• The simulation and Regime Lab routers are optional and return 404 unless explicitly enabled.

Forven is a research tool. The endpoints here surface a disciplined validation process; results are not predictive and nothing here is financial advice.

Related

• Environment variables — every key, port, and safety flag this API reads.
• MCP server — connect MCP clients to the tools the agents use.
• CLI reference — the scriptable command-line path to the same lab.
• Going live safely — the checklist before the trading endpoints touch real capital.