Optional Sports Analysis API

The analytics proxy is optional. It is available only on deployments that enable the analytics upstream, and its production availability must be confirmed with SportQuanta. The fixed REST reference and MCP catalog do not advertise these optional proxy routes.

On an enabled deployment with the default /analytics prefix, the sports analysis entry points are:

Route	Planning
`POST /analytics/v1/sports/analyze`	Uses structured task/entity/market hints to select a supported analysis.
`POST /analytics/v1/sports/analyze/reason`	Server plans from the question and available hints; requires a query.

The gateway forwards to the analysis service with workspace-token auth and the REST quota/rate-limit chain. Because these are POST requests, the token requires api.write. Analysis capabilities and configured leagues/models can vary by deployment.

Request

Both routes share a JSON request contract. session_id and turn_id are required nonempty strings. query is optional for structured analysis and required by the reason route; question is a backward-compatible alias.

Field	Meaning
`request_id`	Optional caller request identifier.
`session_id`, `turn_id`	Required session/turn identifiers.
`language`, `timezone`	Defaults `ko` and `Asia/Seoul`. Specify both for another locale.
`query`	Completed user question.
`task_hint`, `sport_hint`, `league_hint`	Optional routing hints; semantic support is checked later.
`date_context`	Optional `user_local_date` (YYYY-MM-DD) and `requested_date`.
`entities`	Entity mentions with optional `type`, `id`, `name`. Prefer resolved IDs when available.
`markets`	Market mentions with required `type`, optional `side` and numeric `line`.
`concepts`	Requested concept strings.
`constraints`	Supported options including `recent_games` (1–60), `max_results` (1–20), `require_odds`, `require_confirmed_lineup`, season hints, or leaderboard options.
`output`	`mode`, optional language, `include_sources`, `include_debug`.

Output modes are voice_compact (default), voice_detailed, screen_table, and debug_full. Source/debug inclusion defaults to false. Unknown request fields are stripped rather than becoming new query capabilities.

curl "https://api.sportquanta.com/analytics/v1/sports/analyze/reason" \
  -H "Authorization: Bearer $SPORTQUANTA_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "session_id": "session_example",
    "turn_id": "turn_1",
    "query": "Show this seasons home run leaders",
    "league_hint": "mlb",
    "language": "en",
    "timezone": "America/New_York",
    "output": { "mode": "screen_table", "include_sources": true }
  }'

Evidence response

The analysis service returns an evidence pack directly, rather than the REST data envelope. It includes request_id, status, answer_type, language, summary, confidence, items, facts, caveats, freshness, and sources, with optional error/debug context. Items can carry entity IDs, stats, recent games, supporting/risk factors, and data-quality markers. Inspect status even on HTTP 200: values are success, needs_clarification, no_data, or error. Entity ambiguity can include candidates; a lack of data should remain a lack of data rather than an invented numeric answer. Structural request validation returns HTTP 400 with the upstream’s invalid_request shape; gateway auth/quota failures use the normal REST error envelope. Planning can take longer than a simple REST read. Use a client timeout suited to the enabled deployment and preserve the evidence pack’s caveats, source context, and data-quality fields when presenting its answer.

Get Started

Core Concepts

Data & Integration

Agents

Optional Sports Analysis API

Request

Evidence response

​Request

​Evidence response

Request

Evidence response