Authentication
Every data endpoint requires a first-party API key sent as a Bearer token:
Authorization: Bearer bfx_live_...Keys start with bfx_live_. The plaintext is shown exactly once at mint time
— only a hash is stored server-side, so a lost key must be replaced, not
recovered.
Getting a key
Section titled “Getting a key”- Sign up at betflux.ai. Access is currently invite-based; join the Discord to request an invite.
- Subscribe to a plan at betflux.ai/account/billing.
- Mint keys at betflux.ai/account/api-keys.
Keys can be revoked from the same page. Revocation propagates to the edge within a few minutes — it is not instantaneous.
What needs a key
Section titled “What needs a key”| Endpoint | Payload | Auth |
|---|---|---|
GET /v1/games/{game_id}/{dataset} |
Parquet file (the datasets) | key |
GET /v1/games, /v1/games/{game_id} |
JSON (game discovery) | key |
GET /v1/leagues, /v1/teams, /v1/players |
JSON (reference) | key |
GET /v1/me |
JSON (key introspection) | key |
GET /v1/datasets, /v1/datasets/{name}/schema |
JSON (dataset discovery) | none |
/docs, /v1/openapi.json, /llms.txt, /health |
— | none |
| Tier | Requests / min | Active keys | Notes |
|---|---|---|---|
| DEMO | 30 | shared demo access | Pinned to a fixed sample month of history |
| BETA | 120 | 3 | Free during the beta |
| STARTER | 300 | 3 | |
| PRO | 1000 | 10 |
Monthly row quotas are still being finalized for the paid tiers — see Rate limits & quotas.
Checking a key: GET /v1/me
Section titled “Checking a key: GET /v1/me”GET /v1/me introspects the calling key — tier, rate limit, and quota usage:
curl -s "https://api.betflux.ai/v1/me" \ -H "Authorization: Bearer $BETFLUX_API_KEY"It requires a valid key but is deliberately not quota-gated: it works
even when your monthly quota is exhausted, and reading it never consumes
rows. betflux keys check uses it to print your tier, rate limit, usage,
and reset date.
Auth failures
Section titled “Auth failures”All errors are RFC 9457 problem+json;
dispatch on the problem type URI, not the title or status alone — 403 in
particular has two meanings.
| Status | Problem type |
Meaning | What to do |
|---|---|---|---|
401 |
invalid-key |
Missing, malformed, or unknown key | Check the header and the key value; detail says what’s wrong |
402 |
subscription-required |
Key is valid but has no active subscription | Subscribe (or renew) at the body’s upgrade_url (account/billing) |
403 |
key-disabled |
Key was revoked or suspended | Mint a new key |
403 |
history-restricted |
The requested game is older than your plan’s history window | Fetch newer games, or upgrade |