Sports API

The API returns the sports enabled for this client (key and display name), the published events for one sport, and one event plus its odds. It does not scrape providers and does not wait for a new upstream update before responding.

Result information, when the feed provides it, is on market status in the event-odds response. There is no separate settlement endpoint.

Sport keys are lowercase and must match exactly. Cricket is not cricket. Supported keys are cricket, football, tennis, horse-racing, and greyhound-racing. A client only receives the subset its policy allows.

sport

A key from GET /api/v1/sports, used as {sport}.

event ID

The event gmid, a positive integer used as {eventId}.

odds

The odds array on the single-event response. There is no separate odds URL.

There are no query parameters on these routes. GET /metrics is an operator endpoint and is not part of this client API.

Event odds are the odds array from GET /api/v1/{sport}/events/{eventId}. Markets are not reshaped. After a few internal fields are removed, each element is the upstream market object. Identify a market by gtype and marketName.

Prices are decimal. size is the available stake at that price, as provided upstream. Other gtype values may appear. Parse unknown markets defensively.

marketName

Market display name.

marketId

Market identifier.

gtype

Market type.

status

Market status, including a settled state when the feed sends one.

runners[].selectionId

Selection id. It may be a string or a number.

runners[].runnerName

Selection name.

runners[].status

Selection status.

runners[].ex.availableToBack

Back prices as { price, size }.

runners[].ex.availableToLay

Lay prices as { price, size }.

Bookmaker (match1) prices may also include price1. Fancy markets use section instead of runners. Each section entry has a name (nat), a status (gstatus), and an odds ladder.

There is no result or settlement endpoint in this version. Settlement state is on the same event-odds response. Market status, and selection status where present, reflects the current upstream state.

• Each response is the catalog or odds cached at request time.
• The API does not wait for a new upstream update.
• There is no push feed, no hard real-time guarantee, and no published freshness window.
• A later poll may return the same payload if upstream has not changed.
• Poll GET /api/v1/{sport}/events/{eventId} while the event is in use, at the frequency the UI needs. Reuse HTTP connections.

These provider-only fields are removed before the response is sent. Do not depend on them. Additional public fields may appear later; ignore unused keys.

/api/v1/sports and both event routes share the caller's sportsbook limit. Health is not rate limited. API-key accounts are limited per customer. Legacy IP clients are limited per public IP. The request count and window are per client and are not a fixed public contract.

HTTP 429 uses rate_limited and a Retry-After header with the seconds remaining in the current window. Rejected requests still count.

• AuthenticationAPI keys, CIDR allow-lists, and legacy IP access.
• ErrorsThe shared error document and every sports code.

1. Call GET /api/v1/sports and choose a key.
2. Call GET /api/v1/{sport}/events.
3. Take an event gmid.
4. Call GET /api/v1/{sport}/events/{eventId} and read odds.
5. Poll that URL while the event is in use.

const base = "https://api.hzura.com/api/v1";
const headers = {
  Authorization: "Bearer YOUR_API_KEY",
  Accept: "application/json",
};

const sports = await fetch(`${base}/sports`, { headers }).then((r) => r.json());
const sportKey = sports.sports[0].key;

const events = await fetch(`${base}/${sportKey}/events`, { headers }).then((r) => r.json());
const eventId = events[0].gmid;

const response = await fetch(`${base}/${sportKey}/events/${eventId}`, { headers });
const data = await response.json();

On success, data.event_id is the event id, data.event is the catalog object, and data.odds is the market list. The API playground can exercise the same reads. Production calls still require an API key, when one was issued, and a calling IP that matches the configured CIDR.