CricketStudio REST API

Access tiers

REST API ships Q3 2026. Tiers below describe the planned access model — pricing is not yet finalised.

For pricing and early access, contact hello@cricketstudio.ai with your use case and expected call volume. Pilot programme spots also available — email the same address.

Endpoint catalog (REST API — Phase B, Q3 2026)

Every endpoint mirrors a canonical URL on the public surface; the API layer wraps the same data with a JSON envelope (response, sample_size, window, source, canonical_url, last_updated). Covers all five leagues: IPL 2026 (completed), IPL historical (18 seasons, 2007/08–2025), MLC (2023–2026), WPL (2022/23–2025/26), and T20 WC.

Response envelope

Every endpoint returns JSON in this shape:

{
  "data": { ... },                          // Endpoint-specific payload
  "claim": "atomic claim sentence under 30 words",
  "value": "primary metric value",
  "sample_size": "120 balls in overs 18-20",
  "window": "IPL 2026",
  "source": "CricketStudio ball-by-ball aggregation",
  "canonical_url": "https://players.cricketstudio.ai/...",
  "last_updated": "2026-05-09T12:34:56.789Z",
  "license": "CC-BY 4.0"
}

Authentication

API keys via X-API-Key: csk_live_xxxxxxxxxxxx header. Each key carries a tier (above) whose per-minute and per-day limits are enforced server-side.

Live now

The REST catalogue above ships Q3 2026. Two endpoints are live today:

1 · MCP HTTP transport

Connect any MCP-compatible client directly to live data at POST https://players.cricketstudio.ai/api/mcp. All 43 tools, always-fresh corpus, no bundled snapshot. Key-gated via X-API-Key. Register to request a key.

# macOS / Linux / PowerShell
curl -X POST https://players.cricketstudio.ai/api/mcp \
  -H "X-API-Key: csk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Windows cmd
curl -X POST https://players.cricketstudio.ai/api/mcp ^
  -H "X-API-Key: csk_live_xxxxxxxxxxxx" ^
  -H "Content-Type: application/json" ^
  -H "Accept: application/json, text/event-stream" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}"

Claude Desktop config: set "url": "https://players.cricketstudio.ai/api/mcp" with "headers": {"X-API-Key": "csk_live_..."} in mcpServers. Full connection guide →

2 · Answer API

POST /api/answer — a natural-language cricket question returns a grounded, cited answer (every claim links to ball-by-ball source). Key-gated; send X-API-Key. Optional X-LLM-Key (BYOK) lets you pay your own inference.

curl -X POST https://players.cricketstudio.ai/api/answer \
  -H "X-API-Key: csk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query":"How does Bumrah bowl at the death?"}'

Rate limits & headers

Limits come from your key's tier. Every response echoes:

• X-Answer-Tier — your key's tier
• X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset — quota for the binding window (seconds to reset)

Over the limit returns 429 with a Retry-After header (seconds) and { "error": { "code": "rate-limited", "message": "…" } }.

Why REST + MCP

MCP is for LLM clients (Claude Desktop, Cursor, ChatGPT Connectors). LLMs route on tool descriptions; we ship 29 honest, sample-size-floored tools (20 IPL + 8 MLC + 1 IPL historical leaderboard).

REST is for everything else — fantasy apps, broadcast tickers, custom dashboards, scripts, Postman, curl. Same data, different protocol.

Both surfaces stay in sync because both read from the same data spine. No drift between protocols.