Conventions & limits#

Every BSD API follows the same conventions. Learn them once and every endpoint on this site behaves the same way.

Base URL#

All APIs live under one host:

https://sports.bzzoiro.com

Pagination#

List endpoints are paginated with limit and offset. Default page size is 50, maximum 200 (the Odds API caps at 50).

GET /api/v2/events/?limit=50&offset=50   # items 51–100

{
  "count": 408,
  "next": "https://sports.bzzoiro.com/api/v2/events/?limit=50&offset=100",
  "previous": "https://sports.bzzoiro.com/api/v2/events/?limit=50",
  "results": [ ... ]
}

Dates and times#

• Timestamps are ISO 8601 in UTC: 2026-08-02T14:00:00+00:00.
• Date filters take YYYY-MM-DD: ?date_from=2026-08-01&date_to=2026-08-07.
• The football v1 API accepts a tz parameter to shift datetimes; v2 always returns UTC — convert client-side.

Status values#

Odds format#

All odds everywhere are decimal (e.g. 1.85). null means the market is not priced yet. Implied probabilities, where provided, are 0–1 floats.

IDs#

Use BSD numeric ids (id fields) for everything — they are stable and work across REST, MCP, WebSockets and the Image API. Never guess ids: resolve them through list/search endpoints first.

Error shape#

Every API error is JSON with the same envelope:

{ "error": true, "status": 404, "detail": "Not found." }

Rate limits#

There is no per-account quota — but there is a per-IP burst limit of 10 requests/second (burst 110) on all API paths. Exceeding it returns 429. If you need sustained high throughput, spread requests out or cache responses on your side; hot list endpoints are already cheap to poll (see below).

WebSocket connections are not rate-limited but each socket may hold at most 10 concurrent subscriptions.

Caching#

• Hot football endpoints (/api/v2/events/, /leagues/, /teams/, /tournaments/) are edge-cached for ~5 seconds. The X-Cache-Status response header tells you whether you got HIT, MISS or STALE.
• Live-score endpoints are server-cached 10–30 s; reference data (players, rankings, tournaments) about 5 minutes.
• Images are cached aggressively (up to 30 days) — see Image API.

Poll live lists no more often than every 10 s; for true real-time data use the WebSockets instead of polling.