Everything you need to know about the Lumify Sports Intelligence API — from your first API call to production scale.
Learn what Lumify is, how it works, and why it's built for AI agents.
Lumify is a real-time sports intelligence API designed for AI agents and autonomous systems. It delivers structured, explainable data — including live scores, player signals, market intelligence, and change attribution — in a format that agents can reason over and act on without additional processing.
Unlike traditional sports data feeds designed for dashboards and displays, every Lumify response includes confidence scores, rationale, and change signals that make it native to agentic workflows.
Most sports data APIs return raw numbers. Lumify returns intelligence — structured data enriched with rationale, confidence scoring, and change attribution that tells an agent not just what happened, but what it means and how certain the system is.
Key differences:
Schedules, live scores, and odds: NFL, NBA, MLB, NHL, NCAA Football, NCAA Basketball, ATP/WTA tennis, and soccer (MLS, Premier League, La Liga, Serie A, Bundesliga, Ligue 1, UEFA Champions League).
Bet intelligence is a smaller set: MLB, tennis, MLS, NFL, and NCAA Football use the probability customer surface. NBA, NHL, NCAA Basketball, and non-MLS club soccer (Premier League, La Liga, Serie A, Bundesliga, Ligue 1, UEFA Champions League) have full schedules, live scores, and odds today, without an intelligence object yet.
Coverage table: API reference — sports coverage. Intelligence fields: /docs/reference#event-intelligence.
Agent-ready means the API is designed specifically for consumption by AI agents, LLM pipelines, and autonomous systems — not human eyes on a dashboard.
This includes: structured JSON with consistent schemas, confidence scores on every signal, natural-language rationale fields, change-detection webhooks, and predictable credit costs per call that make it easy to budget agentic workloads.
Most odds APIs optimize for market breadth alone. Lumify optimizes for agent usability — a hosted, metered MCP server, no-signup trial keys, free pre-call cost estimates, and structured intelligence (confidence, rationale, attribution) on top of the raw odds.
Lumify covers 9 sportsbooks rather than 85–200+ — trading some market breadth for a self-serve, agent-native integration path.
Everything you need to make your first API call.
Sign up for a free account at lumify.ai/register. Once your account is created, navigate to API Keys in the sidebar and click Create key. Your key is shown once — copy it immediately.
Free Tier accounts receive 1,000 credits that never expire, with no credit card required.
All requests require a Bearer token header:
Authorization: Bearer lmfy-xxxxxx.your_key_here
Then hit any endpoint — for example, a live match lookup costs 1 credit and returns a structured response within ~200ms. The API reference has curl examples for every endpoint.
Yes — npm install @lumifyai/sdk for TypeScript/JavaScript, and pip install lumify-sdk for Python.
The REST API itself works with any HTTP client too, and is simple enough to integrate directly in under 10 minutes. The API Docs include examples in curl, Python, and Node.
The Free Tier gives you:
No credit card is required. Your credits don't expire, so you can explore at your own pace — when you're ready to scale beyond the free credits, upgrade to a paid plan. A rolling 24-hour spend cap applies to the free tier as an anti-abuse safeguard.
Separately, a no-signup instant trial key (100 credits, 14-day expiry) is available from /docs/ai for agents that need a key without creating an account.
Yes — Lumify can run in your own environment for organizations that need to keep data on-premises or in a private cloud. The full setup guide, including required services and configuration, is at docs/getting-started/self-hosting.md.
Most customers use the hosted lumify.ai API instead — self-hosting is typically an Enterprise conversation. Contact us if you're evaluating it.
Yes — a live sports scoreboard tutorial with an open-source demo is at lumify.ai/use-cases/live-scoreboard, with the full code on GitHub. It's a quick way to see live scores, odds, and webhooks working together end to end before you write your own integration.
Authentication, request format, and integration patterns.
All API requests are authenticated via a Bearer token in the Authorization header:
Authorization: Bearer lmfy-xxxxxx.your_key_here
Keys are scoped to your account and can be revoked at any time from the API Keys page. Never share your key or commit it to source control.
All responses are JSON. The exact shape depends on the endpoint — for example:
GET /v1/events → { events: [...], total, next_after_id }GET /v1/events/{id}/intelligence → { available, has_recommend, match_overview, rationale, bets: [...] }. Each bet uses one of two shapes: most sports include confidence_score, tier, bets[].rationale, and attribution, while MLS/MLB/tennis include probability, fair_price, and edge instead — branch on which of probability / confidence_score is presentEvery response includes rate-limit headers (X-RateLimit-*) and credit headers (X-Credits-Used, X-Credits-Remaining when the balance is resolvable). Usage history is also available in your dashboard. See the API reference for the full schema of each endpoint.
Full API documentation with curl, Python, and JavaScript examples is at /docs, with the complete endpoint contract at /docs/reference. An auto-generated OpenAPI schema is served at /openapi.json, and a ready-to-import Postman collection is available for download.
Yes. The REST API works from any environment that can make HTTPS requests — AWS Lambda, Vercel Edge Functions, Cloudflare Workers, Google Cloud Functions, etc.
Keep your API key in environment variables / secrets, not in client-side code — calls should always go through your own backend or edge function, never directly from a user's browser. Contact us if your integration has a use case that needs direct browser access.
Yes. Lumify runs a hosted MCP server at https://lumify.ai/mcp exposing 22 tools — event schedules and live scores, odds and line-movement history, NFL/NCAAF/NBA/NCAAB/NHL/MLB player props, NFL team totals, betting splits, bet intelligence, a moneyline EV scan (Beta), stats, team/player/season lookups, and a free pre-call cost estimator — so agents in Cursor, Claude, and other MCP clients can query Lumify directly without writing REST calls.
Install in Cursor with one click from the MCP guide, or run npx -y @lumifyai/mcp for Claude Desktop and other stdio clients. See the AI-assisted setup guide for prompts and context files. Only tool calls are metered — discovery and connection are free.
ChatGPT and Claude.ai's built-in web connectors require OAuth, which isn't supported yet — use a desktop or IDE MCP client (Cursor, Claude Desktop, VS Code) in the meantime.
Both. For push-based updates, register a webhook with POST /v1/webhooks — supply a public HTTPS URL and, optionally, which event types to receive (score, status, line_move, intelligence; defaults to score and status). Every delivery is signed with a Lumify-Signature header so you can verify authenticity.
For pull-based streaming, GET /v1/events/{id}/stream opens a Server-Sent Events connection that pushes score and status changes as they happen. Each API key can hold up to 5 concurrent streams, and a single connection closes automatically after 5 minutes — the server sends an event: reconnect frame first so you know to open a fresh connection (both SDKs' stream helpers do this for you automatically).
Transient failures — HTTP 5xx, 429, or a timeout — are retried automatically with exponential backoff (30 seconds, then 5 minutes, 30 minutes, 2 hours, and 6 hours). Each attempt is recorded; retries are linked via parent_delivery_id.
Inspect history with GET /v1/webhooks/{id}/deliveries (filters: success, given_up, event_type). When retries are exhausted, given_up is true. Permanent client errors (most 4xx) are not retried. See the delivery history reference.
Every error on /v1/*, /mcp, and /api/agent/* returns the same JSON envelope, so agents can parse failures deterministically:
{ "error": { "code": "not_found", "message": "Event not found.", "status": 404, "doc_url": "https://lumify.ai/docs/reference#error-codes" }, "detail": "Event not found." }
error.code is a stable, machine-readable slug (e.g. rate_limit_exceeded, validation_error, unauthorized) — switch on that rather than parsing message, which is meant for humans. detail is kept as a backward-compatible mirror of message for older integrations.
Yes. Once an agent has any key (e.g. an instant trial key), it can provision more keys and top up credits entirely on its own via POST /api/agent/keys and POST /api/agent/credits/topup — no browser sign-up flow required. GET /api/agent/credits and GET /api/agent/credit-packs let it check balance and available packs first.
This is meant for autonomous or long-running agent workloads that need to manage their own access and spend without a human in the loop.
Yes — POST /v1/query (MCP query_events) accepts a plain-language request like "live nfl games today" and returns matching events plus interpreted filters, an equivalent_request, and any unrecognized_terms.
It's rule-based, not an LLM — so results are deterministic, and ambiguous terms are surfaced rather than guessed at. It costs the same 1 credit as GET /v1/events.
Yes — published packages exist for LangChain (langchain-lumify), LlamaIndex (llamaindex-lumify), CrewAI (crewai-lumify), and n8n (n8n-nodes-lumify), alongside the core JS and Python SDKs. OpenCode can connect via the remote MCP server directly from opencode.json.
All of them wrap the same hosted API and MCP server, so behavior and credit costs are identical to calling Lumify directly.
Yes. /capabilities.json lists every capability with its status, data mode, freshness, and explicit limitations — useful for an agent deciding what to call before spending credits. /.well-known/agent.json and /.well-known/mcp/server-card.json provide short discovery manifests for agent frameworks that support them.
Data freshness, sports coverage, and what's included in each response.
Live scores refresh approximately every minute during active games. Odds and betting splits are ingested roughly every 10 minutes. Bet intelligence is recomputed on a ~30-minute cadence (with a validator pass shortly after).
Completed events are stable once finalized. Use the updated_at and intelligence_updated_at timestamps in responses to detect when data last changed.
Odds and line history cover Pinnacle (default sharp/reference book), FanDuel, DraftKings, BetMGM, Caesars, Bet365, Circa, Hard Rock, and BetOnline.
Use bookmaker=pinnacle (default), a comma-separated list, or bookmaker=all — all of these cost 1 credit. Public betting splits use the same bookmaker slugs as odds (bookmakers[].bookmaker, e.g. draftkings) and cover DraftKings, Circa, FanDuel, BetMGM, and Caesars for MLB/NBA/NHL/NFL.
A standard event response includes:
Specific fields vary by sport and endpoint. See the API reference for full schemas.
On the points model (NCAA Football), each bet is scored across sport-specific signals. Earned points are normalized against the maximum available points (coverage), then adjusted by a Deep Research validator pass. The result is confidence_score (0.0–1.0).
Tiers: very_high (≥ 0.85), strong (0.70–0.84), moderate (0.55–0.69), avoid (< 0.55). Per-signal scores and rationale ship on every points-model response. Signal keys and max points: API reference — signal catalog.
MLB, tennis, MLS, NFL, and NCAA Football return a vig-stripped probability and fair_price, plus Price fields (fair, edges_by_book, best) for line-shopping. Soccer moneyline outcomes in a market sum to 1. edge / tier / has_recommend stay null/false until Edge is published — a market-derived probability has no honest edge against the price it came from. best.edge is a price gap, not a claim-ladder +EV badge. Moneyline ev (Beta) re-packages a positive gap as ev_pct + Kelly for display — scan a sport with GET /v1/intelligence/ev (MCP list_ev).
Walkthrough: /docs/understanding-odds. Fields: probability customer fields. Scan: /docs/reference#intelligence-ev.
Yes. Completed events — final scores, per-period breakdowns, and captured odds — are retained and queryable through the standard endpoints using date filters (?from/?to), up to a 90-day range per request. Historical queries are billed at the same credit rate as live queries.
For large or multi-season bulk historical access, contact us about an Enterprise plan and volume pricing.
Our Terms of Service govern acceptable use of the API, but redistribution and resale rights aren't a one-size-fits-all answer — they depend on your use case and plan. If you're building a product that displays or resells Lumify data to your own end users, contact us to discuss licensing terms before you launch.
Yes — GET /v1/events/{id}/player-props (MCP get_player_props) covers NFL, NCAA Football, NBA, NCAA Basketball, NHL, and MLB today; other sports return HTTP 400. It joins persisted sportsbook prop lines to this-event live player-box stats, so in-progress props show current value, pct_of_line, and a live result (over / under / push / in_progress) that finalizes automatically once the game ends.
Costs 1 credit when lines exist; available:false is free. Full market catalog: lumify.ai/docs/player-props.
How the credit system works and what to expect on your bill.
Credits are the unit of consumption on Lumify. One successful request costs 1 credit — including compound calls that inline odds or intelligence (include_odds / include_intelligence) and multi-bookmaker odds (bookmaker=all).
Failed requests (4xx/5xx) never consume credits — and neither do odds or intelligence calls that return available: false (the market or analysis isn't ready yet). You're only charged once there's real data in the response. Your plan allocates a monthly credit budget that resets on your billing anniversary.
Current public plans (see Pricing):
One standard request costs 1 credit. Auto-recharge credit packs (optional, on Growth and similar plans) are a separate $30 / 1,000-credit pack.
Yes — and estimating is always free. POST /v1/estimate (MCP tool estimate_cost) returns a min/max credit range for one or more planned calls without executing them. Costs are ranges because standalone odds, intelligence, stats, and splits are free until that data is ingested. Compound includes on an event call do not add extra credits.
See GET /v1/estimate/tools for supported tool names, or the estimate reference. Both SDKs expose client.estimate.cost(...).
One credit = one successful API request. Inlining odds or intelligence on an event call, or requesting multiple bookmakers, does not add extra credits.
Failed requests (4xx/5xx) do not consume credits. You can review exactly what was consumed on your usage dashboard.
Free Tier: the 1,000 starter credits never expire and are not on a monthly reset.
Growth (and other monthly plans): included credits reset on your billing anniversary — unused credits do not roll over.
Pay As You Go: there is no monthly credit allotment; you only pay for what you use.
If you regularly leave Growth credits unused, Pay As You Go may be a better fit. If you consistently hit a monthly cap, upgrade or switch to metered PAYG.
Once your credit balance is exhausted, API requests are rejected with a 402 Payment Required response (error.code of insufficient_credits) until you add credits or upgrade. Free Tier credits themselves never expire.
To avoid interruptions, upgrade to a higher tier or switch to Pay As You Go, which is metered and continues serving requests without a monthly credit cap.
Yes, you can change your plan at any time from the Billing page.
Request limits, latency expectations, and what happens when you exceed them.
Rate limits are enforced per API key on a sliding 60-second window:
Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response so you can track consumption in real time.
Requests that exceed your rate limit receive a 429 Too Many Requests response with a Retry-After header indicating when the window resets.
No credits are consumed for rate-limited requests. We recommend implementing exponential backoff in your client for resilience.
Median response time is under 200ms for live data endpoints. Market intelligence endpoints that involve additional computation typically respond within 500ms.
Response times are monitored continuously on our end. If you're seeing unexpected latency, contact us and we'll investigate.
How we protect your data and credentials.
API keys are never stored in plaintext. Validation uses a one-way SHA-256 hash, and a separately encrypted copy is retained only for account-recovery purposes — it is never logged, displayed, or exposed after the key is created.
If you lose a key, revoke it immediately from the API Keys page and generate a new one.
Yes. All API traffic is encrypted via TLS 1.2+. Data at rest is encrypted using AES-256. We do not store your query content beyond what is needed for credit metering and rate limiting.
Lumify infrastructure runs on Google Cloud Platform. Enterprise customers can request dedicated deployments in specific regions.
If you need to complete a security questionnaire or compliance review as part of your evaluation, contact us — we're happy to work through it directly.
How to get help when you need it.
Use the Contact page and select Technical support as the subject. Include your API key prefix (not the full key), the endpoint, and an example request/response.
Growth and Enterprise customers have access to a dedicated support channel with a guaranteed response SLA.
Our target uptime is 99.9% for all paid plans. Formal SLA guarantees with credit remedies are available on Enterprise plans.
We don't yet have a public status page — if you suspect an outage or degraded service, contact us directly and we'll respond quickly.
The fastest way to reach us is via the Contact page. We read every message and respond within one business day.
For enterprise inquiries, partnership opportunities, or press requests, select the relevant subject from the contact form and we'll route you to the right person.