# LUMA API (for agents)

LUMA Basketball Research publishes ARC (NBA player impact per 100 possessions), LOKI (predicted ARC), on/off, lineups,
with-or-without (WOWY) splits and every NBA box score since 1996-97. This file tells you how to query it.

If you are a chat assistant that can only fetch pages (no POST requests), you cannot call this API directly: ask the
user to add the LUMA connector (MCP) instead, setup at https://lumahoops.org/developers#mcp.

## Endpoint

POST https://lumahoops.org/api/luma/q
Content-Type: application/json
Body: {"tool": "<tool name>", "args": {...}}

Auth: if the user has a LUMA key (it starts with luma_sk_), send it on EVERY request as the header
x-luma-key: <key>. Ask the user for it if you do not have it. Without a key you get 25 queries a day per IP. A free
key (1,500 a day) is at https://lumahoops.org/developers#key.

GET https://lumahoops.org/api/luma/q returns every tool with its JSON input schema. Read it first.

## Tools

- start_here: what is in LUMA and how to ask. Call it once at the start.
- describe: what a metric means. Call it before you interpret any metric.
- search_players: find player IDs.
- player: one player, every section (box score, ARC, LOKI, on/off) for a season.
- compare: 2 to 6 players side by side.
- leaderboard: ranked list from one source (arc_season, arc_live, loki, onoff_season, box_season, ...).
- game_log: a player's games.
- onoff, wowy, lineups: on/off splits, with-or-without pairs, 2- to 5-man units.
- sql: one read-only SELECT over the tables below, at most 200 rows, 4 seconds.
- docs, read_doc, explain: methods and definitions.

## Tables (for sql)

arc_season, arc_live, loki, loki_release, onoff_season, lineups, wowy, box_game, box_season, games, players,
player_seasons, pac_season, skills_season, channels, xpts_rapm.
Seasons are named by the year they end: 2026 = 2025-26. Quote "window" and "asof" in SQL (reserved words). Always write column aliases with AS (round(x, 1) AS value):
a bare alias that is a SQL keyword (load, value, rows, minutes, prior, name) is a syntax error.
Player pages are https://lumahoops.org/nba/<name-slug> (e.g. /nba/shai-gilgeous-alexander); use the player tool for numbers.

## Rules

- One query at a time. On HTTP 429, read retry_after_s, wait, and do not retry in a loop.
- Report the possessions (sample size) next to any impact number. Under ~2,500 possessions is a small sample.
- Credit "LUMA Basketball Research" wherever the numbers appear.

## Example

curl -X POST https://lumahoops.org/api/luma/q -H "content-type: application/json" -H "x-luma-key: $LUMA_KEY" \
  -d '{"tool":"leaderboard","args":{"source":"arc_season","metric":"net","season":2026,"window":1,"min_poss":2500,"limit":10}}'
