Web API v1 Contract

Base path: /api/v1

Versioning and deprecation policy

• Current version: v1
• Every HTTP response includes header: X-Cracktrader-API-Version: v1
• Deprecations are announced in API metadata (GET /api/v1/meta) and use standard headers on affected endpoints:
• Deprecation
• Sunset
• Link
• Minimum deprecation notice window: 90 days before removal.

Standard error envelope

{
  "error": {
    "code": "RUN_ALREADY_ACTIVE",
    "message": "run already in progress",
    "details": {}
  }
}

Core endpoints

• GET /health
• Response: status, api_version, checks, metrics, timestamp
• GET /status
• Response: run lifecycle fields (run_id, status, mode, timing, pnl/value/cash, errors)
• GET /status/detailed
• Response: /status + recent_orders, recent_trades, positions, equity_curve, performance_metrics, health
• GET /results
• Response: run_id, config, status, start_time, end_time, orders, trades, positions, equity_curve, performance_metrics, final_value, error

Run lifecycle endpoints

• POST /run/backtest
• Body:
  • strategy_name (string)
  • strategy_params (object)
  • symbols (array[string])
  • timeframe (string)
  • start_date (string|null)
  • end_date (string|null)
  • initial_cash (number)
  • exchange (string)
• POST /run/live
• Body:
  • strategy_name (string)
  • strategy_params (object)
  • symbols (array[string])
  • timeframe (string)
  • exchange (string)
  • exchange_config (object)
  • mode (paper | live)
• POST /run/stop
• DELETE /run/reset

Run response schema (POST /run/backtest, POST /run/live, POST /run/stop, DELETE /run/reset)

{
  "run_id": "abc123def456",
  "status": "running",
  "message": "backtest started"
}

Capabilities for UI forms

• GET /strategies
• GET /exchanges

Realtime stream

• WS /api/v1/ws/status
• Event schema:

{
  "type": "status_update",
  "payload": { "status": "running", "run_id": "abc123def456" },
  "timestamp": "2026-02-26T00:00:00Z"
}

Local UI shell

• GET /ui
• Local-first dashboard for run control and monitoring.
• Uses GET /api/v1/health, GET /api/v1/status, GET /api/v1/results, GET /api/v1/strategies, GET /api/v1/exchanges, POST /api/v1/run/backtest, POST /api/v1/run/live, POST /api/v1/run/stop, DELETE /api/v1/run/reset, and WS /api/v1/ws/status.

Security model (v1)

• Local-only trusted-host model by default (auth is deferred).
• Bind to loopback unless an authenticated proxy is added.
• Auth/session integration should be added at the HTTP edge without changing core run-control contracts.

Parent tracking

• This contract supports Web UI parent issue #5 and fulfills contract hardening scope in #6.