API reference
The Fanzava API lets your own systems read a hub’s competitions, fixtures, tips and leaderboards, send tips on a participant’s behalf, invite participants, and manage the hub’s webhooks. Every request is authenticated with a hub API key, and access is a paid capability: read-only from Growth, full read and write from Pro.
Authentication
Section titled “Authentication”The credential model is live and enforced today, so it is documented ahead of the endpoints. API authentication covers issuing a hub API key, presenting it, the full scope vocabulary, and the per-plan rate ceilings.
In short:
- Requests go to
https://api.fanzava.com, and every route that acts on a hub names the hub in its path. - A key is issued in your hub and sent on every request. It carries scopes, and a scope decides what the key can reach.
- A key only ever reaches routes on an allowlist. Any other route refuses a key with
403 API_KEY_ROUTE_NOT_ALLOWED(“This endpoint cannot be called with an API key”), whatever scopes the key carries.
What a key can reach today
Section titled “What a key can reach today”The allowlist groups by scope. Today it covers:
| Area | Read | Write |
|---|---|---|
| Competitions | Competitions, their fixtures, rounds, prizes, statistics and prize ledger | The prize ledger only: defining prizes and managing allocations |
| Tips | A fixture’s tips, a participant’s tips and tip history, joker and confidence status | Submitting and changing tips, jokers, confidence, draw nominations, bracket picks and race tips |
| Leaderboards | Competition and hub leaderboards, accuracy and statistics | |
| Achievements | Achievements, progress, history and leaderboards | Triggering achievement checks |
| Hub | The hub’s settings and theme | |
| Members | Pending invitations | Sending invitations and importing a CSV file of participants |
| Webhooks | Webhooks, their health and delivery history | Creating, updating and deleting webhooks, retrying deliveries, rotating secrets and sending tests |
Creating competitions, entering fixtures and changing hub settings are not available to an API key. Do them in the hub’s admin dashboard.
On a plan with read-only access, write scopes on a key are removed when the key is used, so a stored write scope does nothing until the hub moves to Pro or above. See What your plan allows.