# PitchIntel API

Base URL: `/api`

Public **read-only** JSON endpoints. No authentication required unless noted.

**Probability engine:** `wc-prob-v5` (attack/defense split, H2H modifier, Dixon–Coles scoreline matrix).

## Public API v1 (third-party integrations)

Base: `/api/v1` — continuous match updates for external apps.

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | /v1 | API key (prod) | Platform overview + event types |
| GET | /v1/feed?cursor=0 | API key (prod) | Delta event feed (poll every 5–15s live) |
| GET | /v1/matches?since=&status= | API key (prod) | Match list with change filter |
| GET | /v1/matches/:ref/snapshot | API key (prod) | Full match state (score, stats, recap) |
| GET | /v1/stream?cursor=0 | API key (prod) | SSE live event stream |
| POST | /v1/webhooks | **API key** | Register webhook URL |
| GET | /v1/webhooks | **API key** | List your webhooks |
| DELETE | /v1/webhooks/:id | **API key** | Remove webhook |
| POST | /v1/webhooks/:id/test | **API key** | Send test delivery |

**API key:** `X-API-Key: pi_live_...` (provision via `POST /api/admin/api-clients` with `X-Admin-Token`).

**Webhook signature:** verify `X-PitchIntel-Signature: sha256=<hmac>` over raw JSON body using your webhook secret.

**Event types:** `match.score_updated`, `match.status_changed`, `match.completed`, `match.stats_updated`, `match.commentary_updated`, `match.events_updated`

## Core

| Method | Path | Description |
|--------|------|-------------|
| GET | /health | Health, dependencies, pipeline timestamps |
| GET | /home | Homepage bundle (dashboard, schedule, standings, probabilities) |
| GET | /dashboard | Featured match, counts |
| GET | /schedule | WC 2026 schedule (104 matches) |
| GET | /matches/:ref | Match detail (`:ref` = SEO slug or legacy `m-*` id) |
| GET | /matches/:ref/stats | Live match statistics |
| GET | /matches/:ref/recap | Recap and commentary |
| GET | /matches/:ref/events | Goals, cards, substitutions |
| GET | /matches/:ref/staff | Managers and officials |
| GET | /matches/:ref/probability | Win/draw/loss probabilities (`wc-prob-v5`) |
| GET | /matches/:ref/pitch-map | Pitch map, ratings, movement vectors |
| GET | /matches/:ref/lineups | Official lineups |
| GET | /matches/:ref/history | Past World Cup meetings |
| GET | /matches/:ref/preview | AI match preview |
| GET | /matches/:ref/tactical-briefing | Tactical briefing |
| GET | /matches/:ref/scenario-predictions | Multi-scenario predictions |
| GET | /matches/:ref/probability-movement | Probability history |
| GET | /analysis/:ref | Multi-factor analysis |

## Tournament

| Method | Path | Description |
|--------|------|-------------|
| GET | /tournaments/2026/standings | 12 group tables + third-place ranking |
| GET | /tournaments/2026/bracket | Knockout bracket (R32 → Final) |
| GET | /tournaments/2026/match-probabilities | Bulk probabilities + gap-fill; meta `{ total, withProbability, pending }` |
| GET | /tournaments/2026/champion-odds | Monte Carlo champion probabilities |
| GET | /tournaments/2026/prediction-accuracy | Favorite hit rate, top-3 scoreline, Brier |
| GET | /tournaments/2026/upcoming-probability-verification | Upcoming fixtures missing snapshots (`?refresh=1`) |

## Teams & news

| Method | Path | Description |
|--------|------|-------------|
| GET | /teams | 48 WC 2026 teams |
| GET | /teams/:teamId | Team profile |
| GET | /teams/:teamId/wc-h2h | Team WC head-to-head |
| GET | /news | News list (24+ RSS + FIFA WC2026; paginated + hot strip) |
| GET | /news/:docId | Single article (VI translation on demand) |
| GET | /news/assets/:docId | Article thumbnail |

## Machine-readable

- OpenAPI: `/.well-known/openapi.json`
- API catalog (RFC 9727): `/.well-known/api-catalog`
- Interactive docs: `/docs/api`
- Agent skills: `/.well-known/agent-skills/index.json`

## Admin

`/api/admin/*` requires `X-Admin-Token` header unless noted. See `/auth.md`.

| Method | Path | Description |
|--------|------|-------------|
| POST | /admin/recompute-all | Recompute all 104 WC2026 matches |
| POST | /admin/recompute/:matchId | Recompute one match |
| POST | /admin/crawl-news | Trigger news crawl now |
| POST | /admin/refresh-champion-odds | Refresh champion simulation |
| POST | /admin/verify-upcoming-probabilities | Gap-fill upcoming fixtures |
| POST | /admin/lineups/sync-squads | Sync official squads → lineups |
| POST | /admin/matches/:matchId/lineup | Submit official XI |
| POST | /admin/api-clients | Create partner API key |
| GET | /admin/api-clients | List API clients |
| DELETE | /admin/api-clients/:id | Revoke API client |
| GET | /admin/sources | Source registry health (public) |