# Lumify — Agent-Ready Sports Intelligence API
# https://lumify.ai/llms.txt
#
# This file helps AI agents understand and integrate with Lumify.
# For the llms.txt specification, see: https://llmstxt.org/

> Lumify is an agent-ready sports intelligence API that provides real-time
> sports data, schedules, live scores, team and player data, odds, public
> betting splits, and AI-powered bet intelligence (confidence scores, signal
> breakdowns, LLM-generated narratives) for developers building sports
> applications and AI agents.

# Quick Links
- Website:       https://lumify.ai
- API Docs:      https://lumify.ai/docs  (Guides: https://lumify.ai/docs/guides  ·  Reference: https://lumify.ai/docs/reference  ·  MCP: https://lumify.ai/docs/guides#mcp)
- AI-assisted setup: https://lumify.ai/docs/ai
- Full machine reference: https://lumify.ai/llms-full.txt
- OpenAPI schema: https://lumify.ai/openapi.json
- MCP server:    https://lumify.ai/mcp  (Model Context Protocol, streamable HTTP)
- MCP npm bridge: npx -y @lumifyai/mcp  (https://www.npmjs.com/package/@lumifyai/mcp)
- Agent manifest: https://lumify.ai/.well-known/agent.json
- Agent cookbook: https://lumify.ai/docs/agent-cookbook.md
- Postman collection: https://lumify.ai/docs/lumify.postman_collection.json
- Instant key:   https://lumify.ai/docs/ai  (free key in seconds — no signup, email, or card; 100 credits, 14-day expiry)
- Sign Up:       https://lumify.ai/register  (persistent account — 1,000 credits)
- Dashboard:     https://lumify.ai/dashboard
- Pricing:       https://lumify.ai/pricing
- SDKs:          npm i @lumifyai/sdk · pip install lumify-sdk

## For AI agents
- Connect via MCP: point your MCP client at https://lumify.ai/mcp (Streamable
  HTTP, JSON mode, stateless) and pass your Lumify API key as a Bearer token.
  Tools: list_sports, list_seasons, list_events, get_event, batch_get_events,
  query_events, get_live_score, get_odds, get_odds_history, get_splits,
  get_intelligence, list_teams, get_team, search_players, get_player,
  get_player_events.
  - Cursor (remote): add {"mcpServers":{"lumify":{"url":"https://lumify.ai/mcp",
    "headers":{"Authorization":"Bearer lmfy-YOUR_KEY"}}}} to ~/.cursor/mcp.json
  - Cursor one-click: cursor://anysphere.cursor-deeplink/mcp/install?name=lumify&config=eyJ1cmwiOiJodHRwczovL2x1bWlmeS5haS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgWU9VUl9BUElfS0VZIn19
  - Claude Desktop / stdio: npx -y @lumifyai/mcp  (env LUMIFY_API_KEY=lmfy-...)
  - initialize / tools/list / ping are free; each tools/call costs the same
    credits as the equivalent REST endpoint. ChatGPT and Claude.ai web
    connectors need OAuth (not yet supported) — use desktop/IDE clients.
  - Human setup + prompts: https://lumify.ai/docs/ai
- Or call the REST API directly (see below). SDKs and the full endpoint reference
  live at https://lumify.ai/llms-full.txt.
- Getting a key: fastest is the instant trial key — no signup, email, or card:
  open https://lumify.ai/docs/ai and click "Get instant trial key" (100 credits,
  14-day expiry). For a persistent account with 1,000 credits, sign up at
  https://lumify.ai/register. Once you have any key, agents can provision more
  keys and top up credits via /api/agent/* (see the full reference).

## Sports covered
- NFL (American Football)
- NBA (Basketball)
- MLB (Baseball) — full bet intelligence available (moneyline, spread, over/under)
- NHL (Hockey)
- Tennis (ATP/WTA) — full bet intelligence available
- Soccer — FIFA World Cup 2026 (full bet intelligence, 3-way moneyline) plus
  club leagues MLS, EPL, La Liga, Serie A, Bundesliga, Ligue 1, and UEFA
  Champions League (schedules/live scores/odds; club intelligence not yet
  available).
- NCAA Football and Basketball

## Authentication
All API requests require a Bearer token API key.
Create an account and your first key in the dashboard at
https://lumify.ai/api-keys (email verification required). Subsequent keys and
credit top-ups can be done programmatically via POST /api/agent/keys and
POST /api/agent/credits/topup. Exhausted credits return HTTP 402 with
error.code insufficient_credits (or daily_credit_cap_exceeded) — not 401.
Free-tier credits never expire; the free-tier daily cap is a rolling 24h
window and daily_credit_cap_exceeded includes a resets_at timestamp.

## REST API Quick Reference

### List events / schedule
```
GET https://lumify.ai/v1/events?sport=mlb&status=scheduled
Authorization: Bearer lmfy-...
```
Filter a team's schedule with `?team_id=` (resolve ids via `GET /v1/teams?q=`).

### Natural-language event search (rule-based, not an LLM)
```
POST https://lumify.ai/v1/query
Authorization: Bearer lmfy-...
Content-Type: application/json

{"query": "live nfl games today", "limit": 5}
```
Returns events plus `interpreted` filters, `equivalent_request`, and
`unrecognized_terms`. Costs 1 credit (same as GET /v1/events).

### Batch get events
```
POST https://lumify.ai/v1/events/batch
Authorization: Bearer lmfy-...
Content-Type: application/json

{"event_ids": [101, 102], "include_odds": true}
```
Max 25 ids. Missing ids under `not_found` (free). Credits = sum of each event.

### Live scores
```
GET https://lumify.ai/v1/events?sport=nfl&status=inprogress
Authorization: Bearer lmfy-...
```

### Bet intelligence (confidence scores + signals + narratives)
```
GET https://lumify.ai/v1/events/{id}/intelligence
Authorization: Bearer lmfy-...
```
Returns confidence scores for each bet type (e.g. ML_P1, ML_P2, OVER, UNDER),
individual signal breakdowns, an LLM-generated narrative, and a structured
rationale list suitable for agent consumption. Available for MLB, tennis, and
FIFA World Cup soccer.

### Public betting splits
```
GET https://lumify.ai/v1/events/{id}/splits
Authorization: Bearer lmfy-...
```
Bets % and handle % per side. Available for MLB and NHL.

### Odds
```
GET https://lumify.ai/v1/events/{id}/odds
Authorization: Bearer lmfy-...
```

### Teams
```
GET https://lumify.ai/v1/teams?sport=nba&conference=Eastern
GET https://lumify.ai/v1/teams/{id}
Authorization: Bearer lmfy-...
```

### Player data
```
GET https://lumify.ai/v1/players?sport=mlb&active=true
Authorization: Bearer lmfy-...
```

### Live streaming (SSE) and webhooks
```
GET  https://lumify.ai/v1/events/{id}/stream?api_key=lmfy-...   # Server-Sent Events
POST https://lumify.ai/v1/webhooks                              # push subscriptions
```
Opening an SSE stream costs 1 credit (same as a score poll) and is rate-limited
per API key (max 5 concurrent streams). Webhook URLs must be public https
endpoints (private/metadata IPs are rejected). Delivery is signed with
Lumify-Signature and fired from ingest on score/status/line_move changes and
from validators on intelligence updates.
## Response conventions
- All timestamps are ISO-8601 UTC with a trailing Z (e.g. 2026-06-23T23:40:00Z).
- Errors use one envelope: {"error": {"code","message","status","doc_url"}, "detail": "..."}.
  Switch on error.code (e.g. not_found, forbidden, rate_limit_exceeded, validation_error).
- Response headers: X-RateLimit-{Limit,Remaining,Reset}, X-Credits-Used, X-Credits-Remaining.
- Billing: successful calls cost credits (see X-Credits-Used). Errors (4xx/5xx) are
  never charged. Odds, line-movement history, splits, and intelligence for a match
  that isn't priced/computed yet return 200 with available=false (or an empty list)
  and are NOT charged — X-Credits-Used is 0. Over MCP the same calls report
  _meta.credits_used: 0. Always read the header rather than assuming a fixed cost.
- Pagination is cursor-based: ?after_id=<last_id>&limit=<n> (max 100); responses include next_after_id.

## Key bet intelligence fields
- `confidence_score`: Final confidence 0.0–1.0 after validator adjustment
- `tier`: Recommendation tier — very_high | strong | moderate | avoid
- `coverage`: Fraction of the scoring model that had sufficient data (0.0–1.0)
- `signals`: Per-signal scores (null when data unavailable). For MLB, also includes
  `signal_meta` with optional supplementary signals (umpire factor, batting trend,
  travel fatigue, injury impact).
- `rationale`: Structured list of signal-derived bullets, agent-parseable
- `attribution`: Data sources that contributed meaningful signal

## Rate limits
Rate limits depend on your plan tier. See https://lumify.ai/pricing

## Support
- Docs: https://lumify.ai/docs (overview) · https://lumify.ai/docs/guides (MCP + recipes) · https://lumify.ai/docs/reference (full endpoint reference)
- Contact: https://lumify.ai/contact-us