API Reference

Auth

Send your API key as an HTTP Bearer token. Keys start with obk_.

curl https://www.oddsbridge.app/api/v1/events \
  -H "Authorization: Bearer obk_your_key_here"

Rate limits

Per-minute throttle plus a daily ceiling. Both reset on their own clock. Every response includes the headers below — read them and back off when Remaining-Minute approaches zero.

During private beta all tiers are free of charge — pricing activates once we ship the self-serve dashboard.

Endpoints

Response shape

{
  "data": [ ... ],
  "meta": {
    "total": 332,
    "limit": 100,
    "offset": 0,
    "rateLimit": {
      "limitMinute":     "60",
      "remainingMinute": "59",
      "remainingDay":    "99"
    }
  }
}

Errors: { "error": { "code": "...", "message": "..." } } with HTTP 4xx/5xx. Common codes: missing_bearer, invalid_key, rate_limited, not_found.

Python quick-start

No SDK to install yet — the public surface is plain REST + SSE, so the standard library is enough.

import os, json, urllib.request

BASE = "https://www.oddsbridge.app/api/v1"
KEY  = os.environ["ODDSBRIDGE_KEY"]   # obk_...

def get(path, **params):
    qs = "&".join(f"{k}={v}" for k, v in params.items() if v is not None)
    req = urllib.request.Request(
        f"{BASE}/{path}" + (f"?{qs}" if qs else ""),
        headers={"Authorization": f"Bearer {KEY}"},
    )
    with urllib.request.urlopen(req, timeout=10) as r:
        return json.load(r)

# 1. Pull every cross-platform arb ≥ 2% with executable verdict
hits = get("arbs", min_edge=2, executable_only="true", limit=50)
for h in hits["data"]:
    print(f"+{h['profitMarginPct']}%  {h['eventTitle']}  ({h['eventSlug']})")

# 2. Stream new arbs over SSE (uses sseclient-py if you want a nicer API)
import urllib.request as _u
req = _u.Request(f"{BASE}/stream",
                 headers={"Authorization": f"Bearer {KEY}"})
with _u.urlopen(req) as r:
    for line in r:
        line = line.decode("utf-8", "replace").strip()
        if line.startswith("event: arb"):
            data_line = next(r).decode("utf-8", "replace").strip()
            if data_line.startswith("data: "):
                evt = json.loads(data_line[6:])
                print("ARB", evt["event"]["title"], evt["profitMarginPct"], "%")

# 3. Register a webhook alert that fires on > 3% NFL arbs
import urllib.request, json
req = urllib.request.Request(
    f"{BASE}/alerts",
    method="POST",
    headers={
        "Authorization": f"Bearer {KEY}",
        "Content-Type":  "application/json",
    },
    data=json.dumps({
        "name": "NFL ≥ 3%",
        "filters": {"minEdgePct": 3, "sport": "american_football",
                    "minLiquidity": True, "executableOnly": True},
        "webhook": {"url": os.environ["MY_DISCORD_WEBHOOK"], "kind": "discord"},
    }).encode("utf-8"),
)
with urllib.request.urlopen(req) as r:
    print(json.load(r))

A native pip install oddsbridge wrapper ships once a few customers ask for it.