Sports API Built for AI Agents

Why agents

Most sports APIs assume a human reads a docs site and hard-codes paths. Agents need:

• Self-describing tools — MCP tools/list + OpenAPI
• Budgetable calls — free estimate_cost / POST /v1/estimate before spend
• Citeable judgment — probability, fair price, Price overlay — not vibes from a line
• One ID space — schedule → score → odds → intelligence without remapping teams

Schemas

Responses are typed JSON with stable field names. Sport-specific payloads (e.g. /stats) are discriminated — soccer/MLB/tennis/NFL/NCAAF/NBA/NCAAB/NHL do not share leftover fields across sports (college football/basketball reuse their pro sibling field catalogs but stay league-scoped). SDKs generate models from OpenAPI; MCP tools declare input schemas on tools/list.

Discovery for autonomous clients: /.well-known/agent.json, /llms.txt, and /openapi.json.

Tool use

A typical agent turn maps cleanly onto Lumify tools:

1. estimate_cost — dry-run credit cost (free)
2. list_events — find fixtures (sport/status/date filters)
3. get_odds / get_live_score — market or score state
4. get_intelligence — structured rationale the model can quote; main-line ev (Beta)
5. list_ev — sport-level main-line EV scan (soccer, MLB, tennis, NFL, NCAAF; market=h2h|spreads|totals)
6. list_forecasts — daily board of forecasted wagers, a model prediction not a beat-the-market claim; player props plus high-confidence main-line picks (moneyline, spread, total)

Every successful tool call reports credits used (_meta.credits_used over MCP; X-Credits-Used over REST). available: false responses are free.

MCP

Hosted Streamable-HTTP MCP at https://lumify.ai/mcp — 28 tools, Bearer auth, no local install for remote clients. Browser GET /mcp returns protocol JSON; the human/SEO landing is /sports-mcp-server.

{
  "mcpServers": {
    "lumify": {
      "url": "https://lumify.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Full client recipes (Cursor one-click, Claude Desktop stdio bridge, VS Code): /docs/guides#mcp. Human onboarding + prompts: /docs/ai.

OpenAPI

Human landing: /docs/openapi. Machine schema: /openapi.json (Swagger /api/docs · ReDoc /api/redoc). Use the JSON to codegen clients, validate tool args, or ground an agent that prefers OpenAPI over MCP. Endpoint dump for LLMs: /openapi-llms.txt.

Predictive intelligence

GET /v1/events/{id}/intelligence (MCP: get_intelligence) returns the predictive surface on the same fixtures: probability, fair_price, Price overlay, and main-line bets[].ev (Beta). Live for MLB, tennis, soccer (MLS + big-five), NFL, and NCAAF. Scan a sport with GET /v1/intelligence/ev / list_ev.

Raw aggregates without scoring live on /stats (Data layer). Agents that must show their work should prefer intelligence + cite fields, not invent analysis from odds alone.

Latency & freshness

API responses are typically fast enough for interactive agents (~hundreds of ms). Data freshness differs by layer: scores ~1 minute, odds ~10 minutes. That fits research, alerts, and pre-game agents — not HFT. Historical list queries are capped at 90 days per request.

Example agent loop

Estimate → list recommended MLB games → pull intelligence for the first hit:

# 1) Free estimate
curl -s -X POST https://lumify.ai/v1/estimate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"calls":[{"tool":"list_events","arguments":{"sport":"mlb","status":"scheduled"}}]}'

# 2) List
curl -s "https://lumify.ai/v1/events?sport=mlb&status=scheduled&limit=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3) Intelligence for one event
curl -s https://lumify.ai/v1/events/EVENT_ID/intelligence \
  -H "Authorization: Bearer YOUR_API_KEY"

from lumify import Lumify

client = Lumify(api_key="YOUR_API_KEY")

# Free: budget before spend
client.estimate.cost([{
    "tool": "list_events",
    "arguments": {
        "sport": "mlb",
        "status": "scheduled",
    },
}])

page = client.events.list(
    sport="mlb",
    status="scheduled",
    limit=3,
)
event_id = page["events"][0]["id"]
intel = client.events.intelligence(event_id)
# Cite intel fields in the agent reply — do not invent rationale
print(event_id, intel)

import { Lumify } from "@lumifyai/sdk";

const client = new Lumify({ apiKey: "YOUR_API_KEY" });

await client.estimate.cost([{
  tool: "list_events",
  arguments: {
    sport: "mlb",
    status: "scheduled",
  },
}]);

const { events } = await client.events.list({
  sport: "mlb",
  status: "scheduled",
  limit: 3,
});
const intel = await client.events.intelligence(events[0].id);
console.log(events[0].id, intel);

More recipes: agent cookbook · LangChain / LlamaIndex / CrewAI / n8n packages on public registries.

Pricing for agents

Instant trial: 100 credits / 14 days, no signup. Free Tier: 1,000 credits that never expire. Details: /pricing.