Using the API

The hub exposes a RESTful, resource-oriented API under /api/v1. It is described by an OpenAPI 3.1 spec that the hub generates itself, and that spec drives the full interactive reference.

The reference is the source of truth

The API Reference is generated by the hub from its OpenAPI spec and is the canonical, always-up-to-date description of every endpoint, parameter, and response shape. Any hub serves the same interactive docs at /docs and the raw spec at /openapi.json (and /openapi.yaml). The summary below is just an orientation.

Resource groups

Group	What it covers	Key paths
Health	Liveness + a quick status summary. Always open.	GET /healthz
Incentives	Current per-region incentives for a platform.	GET /api/v1/platforms/{platform}/incentives
Live stream (SSE)	The push channel the dashboard uses.	GET /api/v1/platforms/{platform}/incentives/stream
Coverage	Agent coverage per region for a platform.	GET /api/v1/platforms/{platform}/coverage
History	Per-region time series for the zoomable graph.	GET /api/v1/platforms/{platform}/regions/{region}/history
Activity	Latest raw readings + recent change points.	GET /api/v1/platforms/{platform}/regions/{region}/activity
Forecast	Next-24h hourly forecast per region.	GET /api/v1/platforms/{platform}/regions/{region}/forecast
Agent ingest	Assignment + readings (per-agent token auth).	GET /api/v1/agent/assignment, POST /api/v1/agent/readings
Auth	Sessions, login, setup, 2FA.	/api/v1/auth/*
Admin	Manage agents, data, users.	/api/v1/admin/*

{platform} is one of Windows, EGS, or GRDK. Region ids look like eu-central-1 or us-east-1. See the reference for exact parameters and the full response schemas.

Authentication

• Read endpoints are public when REQUIRE_AUTH is off. When it's on they need a session or an API key.
• Admin endpoints always need an admin session or an admin's API key.
• Agent ingest (/api/v1/agent/*) uses a per-agent bearer token and is exempt from the site gate.

Examples

Incentives (polling)

Programmatic clients should poll the JSON incentives endpoint rather than open the stream:

curl https://bpincentives.com/api/v1/platforms/Windows/incentives

It returns the per-region survivor/killer bonuses, freshness flags, and the platform's overall status. Agent coverage is a separate endpoint (.../coverage). (With REQUIRE_AUTH on, add -H "Authorization: Bearer bpi_...".)

History

# last 24h by default
curl "https://bpincentives.com/api/v1/platforms/Windows/regions/eu-central-1/history"

# explicit window in epoch milliseconds
curl "https://bpincentives.com/api/v1/platforms/Windows/regions/eu-central-1/history?from=1719500000000&to=1719586400000"

History comes back at a resolution that adapts to the window: small ranges return raw points (one per measurement), wider ones return bucketed points (the last value per bucket, never an average). The span is clamped to the retention window.

Polling vs stream

• The SSE stream is for browsers: it pushes the current incentives the instant an accepted reading changes the platform, de-duplicates unchanged payloads, and the browser auto-reconnects with backoff.
• Programmatic clients should poll the JSON incentives endpoint above on their own schedule. It returns the same payload as the stream.

See How it works for the streaming model and Forecasting model for the forecast endpoint's output.