> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akaramarkets.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> A low-latency feed of live match state

## What this feed is

The Live Match Feed is a low-latency stream of live game events, reported in real time by trained scouts watching each game.

A scout watches the game and reports simple events: a three-pointer is in the air, a penalty was awarded, the batter put the ball in play. Each report updates a small running picture of the game, which is broadcast to every connected consumer with the full updated snapshot attached.

<Note>
  Covers **soccer** (FIFA World Cup group stage), **baseball** (MLB), and **basketball** (NBA, WNBA). The consumer reads are session-addressed under `/api` (the server resolves each session's sport); each sport's event vocabulary and state shape are documented in the [Sports overview](/sports/overview). This site documents the consumer (read-only) API.
</Note>

<Warning>
  The previous SmartSurfacer Scout Feed API docs have been deprecated and replaced by this site. If you were consuming the Scout Feed API, please migrate to this feed — contact us for assistance.
</Warning>

## Why it's fast

Official game data is logged after the play is reviewed and recorded. A scout reports the same fact seconds earlier, so a consumer reacts sooner. For example:

| Sport      | Event             | What it signals               | When it arrives                               |
| ---------- | ----------------- | ----------------------------- | --------------------------------------------- |
| Basketball | `3pt_attempt`     | A three-pointer is in the air | While the ball is in flight — before it lands |
| Basketball | `to_the_line`     | Free throws are coming        | The foul call — before any shot is taken      |
| Soccer     | `penalty_awarded` | A penalty is given            | The whistle — long before the kick            |
| Soccer     | `var_review`      | The referee is reviewing      | The moment the ref signals a review           |
| Baseball   | `contact`         | The batter makes contact      | Off the bat — before the play resolves        |

## What the feed provides

The feed is a **read-only data stream**. It provides:

* **A live WebSocket** that pushes every scout report as a frame carrying the triggering event *and* the full state snapshot. A dropped frame leaves you at most one event stale — the next frame fully re-syncs you.
* **A history backfill** endpoint so a consumer connecting mid-game replays the full tape immediately.
* **A state snapshot** on every frame, carrying the derived score and the sport's live game state.
* **A liveness advisory** (`scout_status`) so you can tell a quiet game from a disconnected scout.

## Getting started

The typical integration:

1. `GET /api/history/{session}` — backfill the event tape
2. Open `wss://.../api/subscribe/{session}` — receive live frames
3. On each frame, append the event to your tape and replace your snapshot with `frame.state`

Start with the [Quickstart](/quickstart).

## Staying current

The wire can change — field shapes, event types, and behaviour evolve. Every change is recorded on the
[Changelog](/changelog), and every breaking change bumps the `contractVersion` carried on the WebSocket
hello frame and on every `/history` response. Versions count
independently per sport, so the schema identity is the pair (`sport`, `contractVersion`) — pin your
integration to a known pair and assert on both, so a mismatch fails loudly instead of mis-parsing silently. Changes ship immediately on merge; watch the changelog (we
also reach out directly for breaking changes).

## Base URL

```text theme={null}
https://mm.akaramarkets.com
```

The consumer reads are top-level under `/api` — `WS /api/subscribe/{session}`, `GET /api/history/{session}`, `GET /api/health/{session}`, and `GET /api/sessions` — the session id alone is the address, and the server resolves its sport. The ungated service liveness probe is `GET /health`. All endpoints and WebSocket paths in this documentation are relative to this base. See the [Sports overview](/sports/overview) for the sports covered.