# API — BR Versus

> Referência da API REST do BR Versus. Todas as rotas retornam JSON via Nitro server routes.

## Jogo

### POST /api/game/start
Cria nova sessão com bracket shuffled (BR vs Mundo no Round 1).
- Rate limit: 10 req/min por IP
- Retorna: sessionId, shareHash, matchups[]

### POST /api/game/vote
Registra voto em um confronto.
- Rate limit: 100 req/min por IP
- Body: sessionId, round, matchIndex, candidateLeftId, candidateRightId, winnerId, isReversal, timeToVoteMs

### POST /api/game/finish
Finaliza torneio e atualiza estatísticas atomicamente.
- Body: sessionId, winnerId, totalVotes, totalReversals, durationSeconds, results[]
- Retorna: champion, stats atualizadas

### GET /api/game/:hash
Carrega partida pelo hash de compartilhamento.
- Retorna: bracket completo, votos, estado (em andamento ou finalizado)

## Dados

### GET /api/stats
Dashboard com estatísticas globais, ranking top 10 e performance por round.

### GET /api/candidates
Lista pratos com stats.
- Query: group (all|brasileira|internacional), sort (ranking|winRate|titles|name)

### GET /api/candidates/:id
Prato por ID com stats e posição no ranking.

### GET /api/candidates/by-slug/:slug
Prato por slug (ex: pao-de-queijo, fish-and-chips).

## Schema (5 tabelas)

- **candidates**: 64 pratos (name, nationality, profession, group, description, curiosity, image_file)
- **candidate_stats**: Stats por prato (wins, losses, championships, points, best_round)
- **game_sessions**: Sessões de jogo (UUID, timestamps, winner, telemetria)
- **vote_logs**: Log de cada voto (round, match, winner, tempo de decisão)
- **global_stats**: Singleton com totais agregados

## Documentação Relacionada

- [/llms.txt](https://brversus.com/llms.txt) — Índice principal
- [/llms-foods.txt](https://brversus.com/llms-foods.txt) — Fichas dos 64 pratos
- [/llms-stats.txt](https://brversus.com/llms-stats.txt) — Sistema de estatísticas