API Overview - b1e55ed

Base URL

http://localhost:5050/api/v1/

All endpoints except:

require a bearer token. b1e55ed refuses to start if api.auth_token is empty unless B1E55ED_INSECURE_OK=1 is set.

# config/user.yaml
api:
  auth_token: "your-secret-token"

export B1E55ED_API__AUTH_TOKEN="your-secret-token"

curl \
  -H "Authorization: Bearer your-secret-token" \
  http://localhost:5050/api/v1/brain/status

Most b1e55ed API errors use a stable machine-readable structure:

{
  "error": {
    "code": "auth.invalid_token",
    "message": "Bearer token is invalid"
  }
}

Some endpoints may also return FastAPI default errors:

{"detail": "..."}

Rate limiting is not currently enforced at the API layer.

Be reasonable anyway (especially for SSE reconnect loops and polling). Treat the API as if a soft limit exists.

Group	What it’s for	Key endpoints
Health	Liveness + basic DB size/uptime	`GET /health`
Brain	Regime/kill-switch state + run cycles	`GET /brain/status`, `POST /brain/run`
Signals	Read or submit signals	`GET /signals`, `POST /signals/submit`
Events / SSE	Real-time stream of events	`GET /events/stream`
Positions	Open positions view	`GET /positions`, `GET /positions/{id}`
Producers	Producer registry + health	`GET /producers/`, `GET /producers/status`, `POST /producers/register`
Contributors	Registry + scoring + attestations	`GET /contributors/`, `POST /contributors/register`, `GET /contributors/leaderboard`
Karma / Treasury	Treasury state + settlement projections	`GET /treasury` (plus `/karma/*`)
Oracle	Public provenance projection	`GET /oracle/producers/{producer_id}/provenance`

curl -s http://localhost:5050/api/v1/health | jq

export TOKEN="your-secret-token"
curl -s \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:5050/api/v1/brain/status | jq