# V2 Public API Binding

## Scope

The public V2 HTTP surface now lives in the Oshun web shell instead of a
standalone V2 web stack:

- App-local handlers: `apps/oshun/web/api/v2/`
- Next.js route adapters: `apps/oshun/web/src/app/api/v2/`
- Canonical OpenAPI 3.1 spec: `libs/openapi/v2/companion.yaml`
- Runtime spec route: `GET /api/v2/openapi`

## Endpoints

The first public surface covers the companion-app and third-party-tool contract:

- `GET /api/v2/player/{playerId}/stats`
- `GET /api/v2/player/{playerId}/history?limit=N`
- `GET /api/v2/replay/{replayId}`
- `POST /api/v2/match/{matchId}/coach-stream`
- `POST /api/v2/notification/subscribe`

Player stats and history enforce the account public flag. Private replay reads,
coach-stream creation, and notification registration require scoped developer
tokens. Coach streams are explicitly read-only and return
`gameplayAuthority: false`.

## OpenAPI

`@oshun/openapi` registers the V2 companion API as `v2-companion`, resolves
`SPEC_PATHS.v2.companion`, validates `libs/openapi/v2/companion.yaml`, and lets
the Oshun web route serve the same document through `GET /api/v2/openapi`.

The V2 guardrail is `python3 V2/ue/Tools/check-v2-public-api.py`.