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:
Lumify covers NFL, NBA, MLB, NHL, NCAA Football, NCAA Basketball, ATP/WTA tennis, and soccer — the FIFA World Cup plus club leagues MLS, Premier League, La Liga, Serie A, Bundesliga, Ligue 1, and UEFA Champions League, with schedules, live scores, and odds across all of them.
Full bet intelligence (confidence scoring, rationale, and change attribution) is currently available for MLB, NFL, NCAA Football, ATP/WTA tennis, and FIFA World Cup soccer. NBA, NHL, NCAA Basketball, and club soccer have live data and odds today, with the full intelligence layer coming to those next.
Contact us if you need coverage for a specific league or sport not listed.
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.
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.
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.
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, analyst_take, bets: [...] }, where each bet includes confidence_score, tier, rationale, and attributionRate-limit headers (X-RateLimit-*) are on every response. Credit usage is tracked in your dashboard rather than returned in the response body. 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 16 tools — event schedules and live scores, odds and line-movement history, betting splits, bet intelligence, and team/player/season lookups — 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.
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 — reconnect to keep watching a long game.
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.
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 30 minutes, and bet intelligence is recomputed on a similar ~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.
A standard event response includes:
Specific fields vary by sport and endpoint. See the API reference for full schemas.
Confidence scores (0.0–1.0) come from a weighted, sport-specific signal model. Each bet is scored across multiple signals (e.g. for MLB: starting pitching, bullpen, lineup/OPS, park & weather, market odds, recent form, splits, research alignment). The earned points are normalized against the maximum available points (coverage), then adjusted by a Deep Research validator pass.
Scores map to tiers: very_high (≥ 0.85), strong (0.70–0.84), moderate (0.55–0.69), and avoid (< 0.55). Per-signal breakdowns and a human-readable rationale are included in every intelligence response.
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.
How the credit system works and what to expect on your bill.
Credits are the unit of consumption on Lumify. Most API calls cost 1 credit. A few endpoints can cost more when you request extra data in a single call:
GET /v1/events/{id}?include_odds=true or ?include_intelligence=true — +1 credit eachbookmaker=all or a comma-separated list) — 2 creditsFailed 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.
One credit = one successful standard API call. Compound calls that bundle extra data (embedding odds or intelligence, or requesting multiple bookmakers) cost more, as described above.
Failed requests (4xx/5xx) do not consume credits. You can review exactly what was consumed on your usage dashboard.
No. Credits reset on your billing anniversary each month. Unused credits do not roll over.
If you regularly have leftover credits, consider a smaller plan. If you're consistently hitting your limit, upgrade to a higher tier or switch to Pay As You Go, which is metered and never blocks on a monthly credit cap.
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. Lumify stores only a SHA-256 hash of each key for validation. The plaintext key is shown exactly once at creation time — we cannot retrieve it after that.
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 in the us-west1 region. Enterprise customers can request dedicated deployments in alternate 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.