docs/API.md

REST API — read-only integration (Phase 3b)

The REST API exposes the same read-only handlers as the MCP server (services/mcp_handlers.py). OpenAPI documentation is auto-generated at /docs.

Install & run

pip install -r requirements.txt
pip install -r requirements-api.txt
python api_server.py
# default: http://127.0.0.1:8765

Or with uvicorn directly:

uvicorn api_server:app --host 127.0.0.1 --port 8765

Authentication (optional)

Set FORECASTER_API_KEY in the environment to require the X-API-Key header on every request. When unset, the API is open (local development only).

export FORECASTER_API_KEY=your-secret-here
curl -H "X-API-Key: your-secret-here" http://127.0.0.1:8765/v1/scoreboard

Never commit API keys. Prefer environment variables over config.yaml.

Rate limiting

Configured in config.yaml → api.rate_limit_per_minute (default: 60). In-memory per-IP sliding window; single-process only.

Endpoints

Method	Path	Description
GET	/health	Liveness + auth mode
GET	/v1/scoreboard	Brier calibration scoreboard
GET	/v1/ood	OOD assessment (scenario_json, n_bootstrap query params)
POST	/v1/ood	OOD with JSON body { "scenario": {...}, "n_bootstrap": 50 }
GET	/v1/jobs/search	Job hybrid RAG search (query params)
POST	/v1/jobs/search	Job search with JSON body
GET	/v1/predictions/open	Open predictions (limit query param)
GET	/v1/predictions/{id}/contribute	Blind target for crowd submit (no agent prior)
POST	/v1/predictions/{id}/contributions	Submit crowd forecast + argument + evidence
GET	/v1/predictions/{id}/crowd	Crowd aggregate (requires contributor_id who has submitted)
GET	/docs	Swagger UI
GET	/openapi.json	OpenAPI 3 schema

Examples

# Calibration scoreboard
curl http://127.0.0.1:8765/v1/scoreboard

# OOD (fast bootstrap for dev)
curl "http://127.0.0.1:8765/v1/ood?n_bootstrap=5"

# Job search
curl "http://127.0.0.1:8765/v1/jobs/search?query=risk%20analyst&industry=Finance&limit=5"

# Open predictions
curl "http://127.0.0.1:8765/v1/predictions/open?limit=10"

POST scenario override:

curl -X POST http://127.0.0.1:8765/v1/ood \
  -H "Content-Type: application/json" \
  -d '{"scenario": {"augmentation_ratio": 0.9, "diffusion_years": 3}, "n_bootstrap": 10}'

Scenario variables

Optional overrides merge onto evolution.CURRENT_AI_SCENARIO:

• augmentation_ratio, demand_elasticity, oring_leverage, skill_distance
• diffusion_years, absorbing_sector, productivity_capture, task_frontier_open

Crowd contributions (Phase 2)

Anti-anchoring flow:

1. GET /v1/predictions/{id}/contribute — returns statement + resolution criteria only
2. POST /v1/predictions/{id}/contributions — submit; response includes your gate decision, not the aggregate
3. GET /v1/predictions/{id}/crowd?contributor_id=... — aggregate visible only after you have submitted

# 1. Blind target (no agent confidence/rationale)
curl http://127.0.0.1:8765/v1/predictions/{id}/contribute

# 2. Submit
curl -X POST http://127.0.0.1:8765/v1/predictions/{id}/contributions \
  -H "Content-Type: application/json" \
  -d '{
    "contributor_id": "alice",
    "probability": 0.35,
    "argument": "Because grid constraints bind however budgets are announced therefore spend lags.",
    "evidence_urls": ["https://example.com/report"]
  }'

# 3. View aggregate (only after submitting as alice)
curl "http://127.0.0.1:8765/v1/predictions/{id}/crowd?contributor_id=alice"

One submission per contributor_id per prediction. Gate thresholds in config.yaml → crowd.

---

• HR-1: tests/test_api.py uses FastAPI TestClient — no live server
• HR-5: No write endpoints (no forecast generation, no publish)
• HR-8: Commercial API hosting requires BUSL commercial license

Tests

python -m pytest tests/test_api.py -v

MCP parity

REST	MCP tool
GET /v1/scoreboard	get_calibration_scoreboard
GET/POST /v1/ood	get_ood_assessment
GET/POST /v1/jobs/search	search_jobs
GET /v1/predictions/open	list_open_predictions

See also MCP.md.