# PuckAPI

> The hockey data API. 12 NHL data tools for AI agents: standings, schedules, player stats, goalie leaderboards, betting odds, line movement, and head-to-head matchups. REST API + MCP server.

Full reference with response shapes: https://puckapi.com/llms-full.txt
MCP server setup: https://puckapi.com/llms-install.md

## Quick Start

- API base URL: https://mcp.puckapi.com
- Auth: `Authorization: Bearer YOUR_API_KEY` or `x-api-key: YOUR_API_KEY`
- MCP server: `https://mcp.puckapi.com/mcp?key=YOUR_API_KEY`
- 500 free credits on signup, no credit card required
- REST API responses include `X-Credits-Used` and `X-Credits-Remaining` headers

## Which Tool Should I Use?

### Looking up a team?
- Need all teams or check an abbreviation? -> list_teams (1 cr)
- Current standings with records? -> get_standings (2 cr)
- Detailed stats for one team? -> get_team_stats (5 cr)
- Compare two teams head-to-head? -> get_head_to_head (10 cr)

### Looking up games?
- Upcoming schedule? -> get_schedule (2 cr)
- Past games with filters? -> get_games (5 cr)
- Full detail for one game with odds and goalies? -> get_game_detail (10 cr)

### Looking up players?
- Find a player by name? -> search_players (2 cr)
- Bio and team context for one player? -> get_player_stats (5 cr)
- Goalie leaderboard (save%, GAA, GSAX)? -> get_goalie_stats (5 cr)

### Betting odds?
- Odds for a specific game? -> get_odds (10 cr)
- How lines moved over time? -> get_line_movement (25 cr)

## All Endpoints

### Teams (3 endpoints)
- POST /v1/list_teams (1 cr) -- All 32 active NHL teams. Filter by conference or division.
- POST /v1/get_standings (2 cr) -- Current standings with points, records, and advanced stats (Corsi, Fenwick, xGF, xGA).
- POST /v1/get_team_stats (5 cr) -- Detailed stats for one team by abbreviation.

### Games (4 endpoints)
- POST /v1/get_schedule (2 cr) -- Upcoming games for the next N days.
- POST /v1/get_games (5 cr) -- Query past and future games by date, team, season, state, or type.
- POST /v1/get_game_detail (10 cr) -- Full game detail with both teams, odds, and goalie starts.
- POST /v1/get_head_to_head (10 cr) -- Matchup history between two teams with win/loss record.

### Players (3 endpoints)
- POST /v1/search_players (2 cr) -- Find players by name, team, or position. 3,000+ players across 16 seasons.
- POST /v1/get_player_stats (5 cr) -- Player bio and team context. Includes goalie stats for goalies.
- POST /v1/get_goalie_stats (5 cr) -- Goalie leaderboard sorted by save%, GAA, GSAX, or wins.

### Odds (2 endpoints)
- POST /v1/get_odds (10 cr) -- Betting odds for a game. Moneylines, spreads, totals from DraftKings, FanDuel, BetMGM, ESPN BET.
- POST /v1/get_line_movement (25 cr) -- Time-series odds snapshots grouped by bookmaker.

## Data Coverage

- Teams: 32 active + 2 historical (ATL, ARI)
- Games: 2010-11 through current season
- Odds: 2019-20 through current (4 bookmakers)
- Players: 3,000+ across 16 seasons
- Goalie stats: Current season with daily snapshots

## Pricing

Most tools cost 1-5 credits. Free accounts get 500 credits. Plans from $19/mo at https://puckapi.com/dashboard/billing.

## Documentation

Full API docs: https://puckapi.com/docs
MCP setup guide: https://puckapi.com/docs/mcp-server