Skip to content

README.md

Latest commit

 

History

History
124 lines (93 loc) · 3.41 KB

README.md

File metadata and controls

124 lines (93 loc) · 3.41 KB

API Reference

This project exposes a FastAPI application for controlling simulations, running benchmarks, and streaming realtime events.

Base URLs

OpenAPI / Docs

When docs are not gated:

  • Swagger UI: /docs
  • ReDoc: /redoc
  • OpenAPI JSON: /openapi.json

Docs gating:

  • In protected environments (staging/production), the app factory disables /docs, /redoc, and /openapi.json.
  • In development, you can still enable gating with AUTH_ENABLED=true and AUTH_PROTECT_DOCS=true.

Authentication (JWT)

The API supports RS256 JWT verification when enabled.

Enable auth:

  • AUTH_ENABLED=true
  • Provide at least one public key via AUTH_JWT_PUBLIC_KEY, AUTH_JWT_PUBLIC_KEYS, or AUTH_JWT_PUBLIC_KEY_FILE

Development bypass:

  • AUTH_TEST_BYPASS=true (intended for local/testing only)

Important notes:

  • Health endpoints are intended to remain unprotected.
  • If AUTH_ENABLED=true and no public key is configured, the app fails fast at startup.

Core Endpoints (High Level)

This list is intentionally high-level; use Swagger/OpenAPI for the canonical schema.

  • Health:
    • GET /health
    • GET /api/v1/health
  • Simulation:
    • POST /api/v1/simulation/...
    • GET /api/v1/simulation/...
  • Experiments:
    • GET /api/v1/experiments
    • POST /api/v1/experiments
  • Agents:
    • GET /api/v1/agents
  • Scenarios:
    • GET /api/v1/scenarios
  • Leaderboard:
    • GET /api/v1/leaderboard
    • Public snapshot routes under /api/v1/public/...
  • Benchmarks:
    • Routes are mounted under /api/v1/benchmarks/...
  • Metrics (Prometheus-style):
    • GET /api/metrics
  • Golden Masters:
    • Routes are mounted under /api/v1/golden/...
  • War Games (experimental):
    • Routes are mounted under /api/v1/wargames/... (see note below)

Realtime WebSocket

Endpoints:

  • ws://HOST:PORT/ws/realtime
  • Back-compat alias: ws://HOST:PORT/ws/events

Typical usage:

  1. Connect to /ws/realtime
  2. Subscribe to topics (JSON frames)
  3. Receive events as the simulation runs

Notes On “War Games”

The codebase includes a /api/v1/wargames route group (src/fba_bench_api/api/routes/wargames.py). Treat it as experimental until it is fully aligned with the production service wiring.

See: docs/api/extra_endpoints.md

Error Format

Most errors follow FastAPI conventions:

  • {"detail": "..."}
  • Validation errors use the standard 422 response body.

Examples

Health:

curl -sS http://localhost:8080/api/v1/health

Health (Windows PowerShell):

curl.exe -sS http://localhost:8080/api/v1/health

Fetch OpenAPI (when not gated):

curl -sS http://localhost:8000/openapi.json > openapi.json

Docs Site JSON Snapshots

The static docs site references JSON snapshot files under docs/api/:

  • docs/api/leaderboard.json
  • docs/api/leaderboard_agentic.json
  • docs/api/top10.json
  • docs/api/top10_agentic.json
  • docs/api/live.json

Additional snapshot files may be generated by workflows/scripts depending on which benchmark modes are published.

These files are generated by workflows/scripts (for example generate_github_pages.py, scripts/batch_runner.py, scripts/sim_theater_demo.py) and should not be treated as hand-maintained documentation.

See also:

  • docs/api/routes_catalog.md
  • docs/api/extra_endpoints.md