Skip to content

quick-start.md

Latest commit

 

History

History
executable file
·
136 lines (111 loc) · 5.46 KB

quick-start.md

File metadata and controls

executable file
·
136 lines (111 loc) · 5.46 KB
Raw

Quick Start Guide

Make your first Lumify Sports Intelligence API call in under 5 minutes.

Lumify is an agent-ready sports intelligence API. It returns structured schedules, live scores, odds, betting splits, and AI-generated bet intelligence (confidence scores, signal breakdowns, and narratives) across multiple sports.

1. Create Your Account

  1. Sign up at lumify.ai/register
  2. Verify your email address
  3. Your Free Tier account includes 1,000 credits that never expire — no credit card required

2. Create an API Key

  1. Log in and open the API Keys dashboard
  2. Click Create key
  3. Copy the key immediately — it is shown only once

Keys use the format lmfy-xxxxxx.yyyyyyyy… and are passed as a Bearer token on every request.

3. Make Your First Call

All /v1/* endpoints require the Authorization: Bearer header and return JSON.

List today's scheduled MLB games

curl "https://lumify.ai/v1/events?sport=mlb&status=scheduled" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "events": [
    {
      "id": 9199,
      "name": "Atlanta Braves @ San Diego Padres",
      "sport": "mlb",
      "league": "mlb",
      "status": "scheduled",
      "starts_at": "2026-06-23 23:40:00",
      "venue": { "id": 42, "name": "Petco Park", "city": "San Diego" }
    }
  ],
  "total": 1,
  "next_after_id": null
}

Fetch bet intelligence for an event

curl "https://lumify.ai/v1/events/9199/intelligence" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (abbreviated):

{
  "event_id": 9199,
  "available": true,
  "has_recommend": true,
  "analyst_take": "Sharp money has moved toward San Diego through the morning...",
  "bets": [
    {
      "bet_type": "ML_P1",
      "player_name": "San Diego Padres",
      "tier": "moderate",
      "confidence_score": 0.611,
      "rationale": ["Strong Starting Pitching Edge (20/25)", "Deep Research supports this bet (+3.1pp)"],
      "attribution": ["pitching_edge", "deep_research"]
    }
  ]
}

bets[] has two shapes — branch, don't assume. The example above is the points model, returned for MLB, tennis, NFL, NCAAF, FIFA World Cup soccer, and club soccer leagues other than MLS. MLS returns the probability model instead: each bet carries a calibrated probability, a vig-free fair_price, and the components behind them (p_market, p_model, blend_w, edge, sufficiency, drivers) — and no confidence_score, coverage, signals, or validator.

Detect the shape by checking which of probability / confidence_score is present. Full per-field definitions for both shapes: API reference.

4. Explore the Endpoints

Endpoint Purpose
GET /v1/sports Supported sports, leagues, and current seasons
GET /v1/events Paginated, filterable event list
GET /v1/events/{id} Full event detail (optionally ?include_odds=true, ?include_intelligence=true)
GET /v1/events/{id}/score Lightweight live-score snapshot
GET /v1/events/{id}/odds Current moneyline, spread, and total lines
GET /v1/events/{id}/odds/history Line movement history
GET /v1/events/{id}/splits Public betting splits (bets % vs handle %) — MLB, NBA, NHL, NFL only; not tennis/soccer/NCAAF
GET /v1/events/{id}/stats Raw team/match stats — form, H2H, rates, standings (Data layer; soccer only)
GET /v1/events/{id}/intelligence Per-bet analysis — two shapes: probability/fair price (MLS) or confidence score/signals (all other sports)
GET /v1/players Player/team lookup
GET /v1/players/{id} Player or team profile
GET /v1/players/{id}/events Player/team schedule and results

5. Credits & Rate Limits

  • Each API call costs 1 credit. Compound calls add credits: include_odds=true adds +1 credit for a single book (default Pinnacle) or +2 credits for bookmaker=all / a comma-separated list; include_intelligence=true adds +1 credit. Standalone multi-bookmaker odds (bookmaker=all or a list) also cost 2 credits.
  • Failed requests (4xx/5xx) do not consume credits.
  • Rate limits are enforced per API key on a sliding 60-second window. Every response includes X-RateLimit-* headers so you can throttle proactively. Exceeding the limit returns 429 Too Many Requests with a retry_after value.

Next Steps

  • API Reference — full endpoint documentation with curl, Python, and JavaScript examples
  • Pricing — plans and credit allowances
  • FAQ — data coverage, billing, and integration questions

Troubleshooting

Issue Solution
401 Unauthorized Check the key is correct, active, and passed as Authorization: Bearer lmfy-…
402 Payment Required Credits exhausted or daily free-tier cap hit — switch on error.code (insufficient_credits, daily_credit_cap_exceeded) and follow upgrade_url / topup_url. daily_credit_cap_exceeded includes resets_at (rolling 24h window)
429 Too Many Requests You exceeded your plan's rate limit — back off and retry after the window resets
available: false on intelligence/odds The pipeline has not computed data for this event yet — poll again shortly

Need help? Contact support@lumify.ai