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 — confidence, signals, rationale — 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 do not share leftover fields. 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

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 — 18 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.

Confidence & rationale

GET /v1/events/{id}/intelligence (MCP: get_intelligence) returns sport-aware judgment on top of the same fixtures:

• Points model — confidence_score, signals, narrative / rationale / attribution (most sports)
• Probability model — calibrated probability / fair_price components (e.g. MLS) — different shape; do not assume one schema

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 ~30 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","has_recommend":true}}]}'

# 2) List
curl -s "https://lumify.ai/v1/events?sport=mlb&status=scheduled&has_recommend=true&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",
        "has_recommend": True,
    },
}])

page = client.events.list(
    sport="mlb",
    status="scheduled",
    has_recommend=True,
    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",
    has_recommend: true,
  },
}]);

const { events } = await client.events.list({
  sport: "mlb",
  status: "scheduled",
  hasRecommend: true,
  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.