Guides

Track live odds movement

Two ways to watch a line move without hammering /v1/events/{id}/odds/history on a tight poll loop:

• Push (recommended): create a webhook subscription with event_types: ["line_move"] and a sport or event_id — you'll get one delivery per event per ingest cycle when a main line's point changes or its price moves by at least 5¢. Transient delivery failures retry automatically; inspect delivery history if a callback looks stuck.
• Pull: poll odds history every few minutes and diff against the last recorded_at you've seen. History is not cached, so every call reflects the latest ingest.

# Subscribe once — deliveries arrive at your endpoint from then on
curl -X POST https://lumify.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/lumify", "event_types": ["line_move"], "sport": "nfl"}'

Pull a full event intelligence report in one call

Fetch schedule, odds, and bet intelligence together instead of three separate round trips:

curl "https://lumify.ai/v1/events/4812?include_odds=true&include_intelligence=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

This is still 1 credit and saves two round trips versus separate event, odds, and intelligence calls. See Get an event for the full parameter reference.

Read a forecasted prop wager

Scan the daily board, then join live box progress on the same player × market. How + field catalog: /docs/forecasts.

1. Call list_forecasts (or GET /v1/intelligence/forecasts) with a sport — MLB, NFL, NCAAF, NBA, NCAAB, NHL, or tennis. Rank is conviction.
2. Take event_id and call get_event if you need kickoff, status, or participants.
3. Call get_player_props on that event and match player_id + market for live current, pct_of_line, and settleable.

# 1. Daily board (selected:true rows only)
curl "https://lumify.ai/v1/intelligence/forecasts?sport=mlb" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Live progress for the same event
curl "https://lumify.ai/v1/events/9199/player-props" \
  -H "Authorization: Bearer YOUR_API_KEY"

Grade a free-text slip

Paste a sentence such as Mets over 5 runs yesterday or Chiefs −3.5 last night. Lumify never guesses a player, team, or event — collisions stay on candidates. The public /grade sheet is 20 free grades a day; an agent should call POST /v1/grade/slip or MCP grade_slip.

Build a live sports scoreboard

Discover in-progress games with GET /v1/events?status=inprogress, stream score updates over SSE, and render a live board — with a cloneable open-source demo.

Model Context Protocol (MCP)

Lumify runs a hosted MCP server so AI agents can call the entire sports-intelligence API as native tools — no wrapper code required.

Any MCP-compatible client connects by pointing at https://lumify.ai/mcp and passing your Lumify API key as a Bearer token. The server is fully self-describing — a client's tools/list call returns the current tool catalogue with input schemas. You can inspect the discovery document with a browser GET to /mcp (JSON). Tool calls use POST only — Lumify does not offer a GET Server-Sent Events stream on this URL. Some clients briefly probe with Accept: text/event-stream and receive 405 Allow: POST; that is expected transport negotiation, then they continue over POST JSON (streamable HTTP).

Get an API key first → AI-assisted setup guide →

The one-click install opens Cursor with a placeholder key — replace YOUR_API_KEY with a key from your dashboard before approving.

Connect from Cursor

Recommended (remote): add Lumify to ~/.cursor/mcp.json (or a project-local .cursor/mcp.json):

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

Stdio bridge (optional): if you prefer a local process, use the published @lumifyai/mcp package:

{
  "mcpServers": {
    "lumify": {
      "command": "npx",
      "args": ["-y", "@lumifyai/mcp"],
      "env": { "LUMIFY_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Connect from Claude Desktop

Claude Desktop speaks stdio. Prefer the official bridge package:

{
  "mcpServers": {
    "lumify": {
      "command": "npx",
      "args": ["-y", "@lumifyai/mcp"],
      "env": { "LUMIFY_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Alternatively, bridge with mcp-remote:

{
  "mcpServers": {
    "lumify": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://lumify.ai/mcp",
        "--header", "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Connect from VS Code / Copilot

Add a server entry under mcp.servers in your VS Code settings (or .vscode/mcp.json):

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

Available tools

Each tool maps 1:1 to a REST endpoint and returns identical data. Credit cost mirrors the equivalent REST call.

Billing

The MCP handshake is free: initialize, tools/list, and ping never cost credits. Only tools/call is metered, at the same rate as the matching REST endpoint. Each result reports its cost under _meta.credits_used. Calls that return no usable data because it isn't available yet — odds, line history, splits, or intelligence for a match that hasn't been priced/computed — are free (_meta.credits_used: 0).

Cookbook & Postman

Deeper, copy-paste-ready references for building on Lumify:

Build an MCP betting-splits agent

Give an LLM agent read access to public betting splits with no REST wrapper code — connect to the hosted MCP server and call its tools directly:

1. Connect Cursor, Claude Desktop, or any MCP client to https://lumify.ai/mcp with your API key as the Bearer token (see the MCP section for client configs).
2. Call the list_events tool filtered by sport/date to find event IDs.
3. Call the get_splits tool per event ID — the agent reasons over bets%/handle% directly, no JSON parsing code required.

Provision API access programmatically

Let an agent onboard itself — mint a key, check its balance, and top up credits — without a human touching the dashboard:

# 1. Mint a key (needs an existing session or key to bootstrap)
curl -X POST https://lumify.ai/api/agent/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "agent-worker-1"}'

# 2. Check balance before a big batch of calls
curl https://lumify.ai/api/agent/credits \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Top up if running low
curl -X POST https://lumify.ai/api/agent/credits/topup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pack_id": 1}'

Full parameter and error reference: Manage API keys and Credits & credit packs.