# PuckAPI -- Full API Reference

> 12 NHL data tools. Stats, odds, and everything between.

Base URL: https://mcp.puckapi.com
Auth: `Authorization: Bearer YOUR_API_KEY` or `x-api-key: YOUR_API_KEY`
MCP: `https://mcp.puckapi.com/mcp?key=YOUR_API_KEY`

All endpoints accept POST with JSON body. All responses include `X-Credits-Used` and `X-Credits-Remaining` headers.

---

## POST /v1/list_teams (1 credit)

List all 32 active NHL teams. Excludes historical/relocated franchises (ATL, ARI).

### Request

```json
{
  "conference": "Eastern",       // optional: "Eastern" | "Western"
  "division": "Atlantic"         // optional: string
}
```

### Response

```json
{
  "data": {
    "teams": [
      {
        "abbrev": "BUF",
        "name": "Buffalo Sabres",
        "city": "Buffalo",
        "conference": "Eastern",
        "division": "Atlantic",
        "arena": "KeyBank Center"
      }
    ],
    "count": 32
  }
}
```

---

## POST /v1/get_standings (2 credits)

Current NHL standings with records and advanced stats.

### Request

```json
{
  "conference": "Eastern",       // optional
  "division": "Atlantic",        // optional
  "season": "20252026"           // optional, defaults to current
}
```

### Response

```json
{
  "data": {
    "standings": [
      {
        "teamAbbrev": "BUF",
        "teamName": "Buffalo Sabres",
        "conference": "Eastern",
        "division": "Atlantic",
        "rank": 1,
        "points": 110,
        "gamesPlayed": 82,
        "wins": 50,
        "losses": 25,
        "otLosses": 7,
        "pointPct": 0.671,
        "goalDiff": 45,
        "goalsForPerGame": 3.42,
        "goalsAgainstPerGame": 2.87,
        "corsiPct": 52.1,
        "fenwickPct": 51.8,
        "expectedGoalsFor": 215.3,
        "expectedGoalsAgainst": 198.7,
        "snapshotDate": "2026-04-15"
      }
    ],
    "snapshot_date": "2026-04-15",
    "count": 32
  }
}
```

---

## POST /v1/get_team_stats (5 credits)

Detailed stats for a specific team including record and advanced metrics.

### Request

```json
{
  "team": "BUF",                 // required: team abbreviation
  "season": "20252026"           // optional
}
```

### Response

```json
{
  "data": {
    "team": {
      "abbrev": "BUF",
      "fullName": "Buffalo Sabres",
      "city": "Buffalo",
      "conference": "Eastern",
      "division": "Atlantic",
      "arena": "KeyBank Center",
      "active": true
    },
    "current_stats": {
      "rank": 5,
      "points": 95,
      "gamesPlayed": 82,
      "wins": 42,
      "losses": 30,
      "otLosses": 10,
      "pointPct": 0.573,
      "goalDiff": 12,
      "corsiPct": 51.2,
      "fenwickPct": 50.8,
      "snapshotDate": "2026-04-15"
    },
    "season": "20252026"
  }
}
```

---

## POST /v1/get_schedule (2 credits)

Upcoming games that haven't been played yet.

### Request

```json
{
  "team": "BUF",                 // optional
  "days": 7                      // optional, 1-30, default 7
}
```

### Response

```json
{
  "data": {
    "upcoming_games": [
      {
        "id": "2025020887",
        "gameDate": "2026-03-15",
        "startTime": "2026-03-15T23:00:00Z",
        "homeTeam": "BUF",
        "awayTeam": "TOR",
        "homeTeamName": "Buffalo Sabres",
        "awayTeamName": "Toronto Maple Leafs",
        "venue": "KeyBank Center",
        "gameType": "regular"
      }
    ],
    "count": 3
  }
}
```

---

## POST /v1/get_games (5 credits)

Query games by date range, team, season, state, or type.

### Request

```json
{
  "date_from": "2026-01-01",    // optional: YYYY-MM-DD
  "date_to": "2026-01-31",      // optional: YYYY-MM-DD
  "team": "BUF",                // optional
  "season": "20252026",         // optional
  "game_state": "FINAL",        // optional: "FUT" | "LIVE" | "FINAL" | "OFF"
  "game_type": "regular",       // optional: "regular" | "playoff" | "preseason"
  "limit": 100                  // optional, 1-500, default 100
}
```

### Response

```json
{
  "data": {
    "games": [
      {
        "id": "2025020887",
        "season": "20252026",
        "gameDate": "2026-01-15",
        "startTime": "2026-01-15T23:00:00Z",
        "homeTeam": "BUF",
        "awayTeam": "TOR",
        "homeTeamName": "Buffalo Sabres",
        "awayTeamName": "Toronto Maple Leafs",
        "homeScore": 4,
        "awayScore": 2,
        "gameState": "FINAL",
        "gameType": "regular",
        "venue": "KeyBank Center"
      }
    ],
    "count": 15
  }
}
```

---

## POST /v1/get_game_detail (10 credits)

Full details for a specific game including team info, odds, and goalie starts.

### Request

```json
{
  "game_id": "2025020887"        // required: NHL game ID
}
```

### Response

```json
{
  "data": {
    "game": { "id": "2025020887", "homeTeam": "BUF", "awayTeam": "TOR", "homeScore": 4, "awayScore": 2, "gameState": "FINAL", "gameDate": "2026-01-15" },
    "home_team": { "abbrev": "BUF", "fullName": "Buffalo Sabres", "conference": "Eastern", "division": "Atlantic" },
    "away_team": { "abbrev": "TOR", "fullName": "Toronto Maple Leafs", "conference": "Eastern", "division": "Atlantic" },
    "odds": [
      {
        "bookmaker": "draftkings",
        "snapshotType": "opening",
        "mlHome": -120,
        "mlAway": 100,
        "mlHomeProb": 0.545,
        "mlAwayProb": 0.500,
        "spreadHome": -1.5,
        "spreadHomeOdds": 180,
        "spreadAway": 1.5,
        "spreadAwayOdds": -220,
        "total": 6.0,
        "totalOverOdds": -110,
        "totalUnderOdds": -110,
        "capturedAt": "2026-01-15T12:00:00Z"
      }
    ],
    "goalie_starts": { "gameId": "2025020887", "homeGoalieId": 8478024, "awayGoalieId": 8479361 }
  }
}
```

---

## POST /v1/get_head_to_head (10 credits)

Historical matchups between two teams.

### Request

```json
{
  "team1": "BUF",                // required
  "team2": "TOR",                // required
  "season": "20252026",          // optional
  "limit": 20                   // optional, 1-100, default 20
}
```

### Response

```json
{
  "data": {
    "team1": "BUF",
    "team2": "TOR",
    "record": { "BUF": 8, "TOR": 12 },
    "total_games": 20,
    "games": [
      { "id": "2025020887", "gameDate": "2026-01-15", "homeTeam": "BUF", "awayTeam": "TOR", "homeScore": 4, "awayScore": 2, "gameState": "FINAL" }
    ]
  }
}
```

---

## POST /v1/search_players (2 credits)

Find NHL players by name across 16 seasons (3,000+ players).

### Request

```json
{
  "query": "McDavid",           // required: partial name match
  "team": "EDM",                // optional
  "position": "C",              // optional: "G" | "D" | "C" | "LW" | "RW"
  "active": true,               // optional, default true
  "limit": 10                   // optional, 1-50, default 10
}
```

### Response

```json
{
  "data": {
    "players": [
      {
        "id": 8478402,
        "name": "Connor McDavid",
        "firstName": "Connor",
        "lastName": "McDavid",
        "team": "EDM",
        "teamName": "Edmonton Oilers",
        "position": "C",
        "positionType": "forward",
        "jerseyNumber": 97,
        "birthCountry": "CAN",
        "active": true
      }
    ],
    "count": 1
  }
}
```

---

## POST /v1/get_player_stats (5 credits)

Player bio and team context. Includes goalie stats for goalies when available.

### Request

```json
{
  "player_id": 8478402          // required: NHL player ID
}
```

### Response

```json
{
  "data": {
    "player": {
      "id": 8478402,
      "name": "Connor McDavid",
      "firstName": "Connor",
      "lastName": "McDavid",
      "team": "EDM",
      "teamName": "Edmonton Oilers",
      "position": "C",
      "positionType": "forward",
      "jerseyNumber": 97,
      "birthDate": "1997-01-13",
      "birthCountry": "CAN",
      "heightInches": 73,
      "weightLbs": 193,
      "shootsCatches": "L",
      "headshotUrl": "https://..."
    },
    "goalie_stats": null
  }
}
```

---

## POST /v1/get_goalie_stats (5 credits)

Goalie performance leaderboard.

### Request

```json
{
  "team": "BUF",                // optional
  "season": "20252026",         // optional
  "min_games": 10,              // optional, default 10
  "sort_by": "save_pct",        // optional: "save_pct" | "gaa" | "gsax" | "wins"
  "limit": 20                   // optional, 1-50, default 20
}
```

### Response

```json
{
  "data": {
    "goalies": [
      {
        "playerId": 8479361,
        "playerName": "Ukko-Pekka Luukkonen",
        "team": "BUF",
        "teamName": "Buffalo Sabres",
        "gamesPlayed": 55,
        "wins": 28,
        "losses": 20,
        "otLosses": 7,
        "savePct": 0.915,
        "gaa": 2.78,
        "gsax": 5.2,
        "shutouts": 3,
        "highDangerSavePct": 0.842,
        "rollingSavePct": 0.920,
        "trend": "hot",
        "restDays": 2,
        "snapshotDate": "2026-04-15"
      }
    ],
    "count": 15,
    "filters": { "season": "20252026", "min_games": 10, "sort_by": "save_pct" }
  }
}
```

---

## POST /v1/get_odds (10 credits)

Betting odds for a specific game. Data covers 2019-20 through current.

### Request

```json
{
  "game_id": "2025020887",      // required
  "bookmaker": "draftkings",    // optional: lowercase key
  "snapshot_type": "opening"    // optional: "opening" | "closing"
}
```

### Response

```json
{
  "data": {
    "game_id": "2025020887",
    "home_team": "BUF",
    "away_team": "TOR",
    "game_date": "2026-01-15",
    "odds": [
      {
        "bookmaker": "draftkings",
        "snapshotType": "opening",
        "source": "the-odds-api",
        "mlHome": -120,
        "mlAway": 100,
        "mlHomeProb": 0.545,
        "mlAwayProb": 0.500,
        "spreadHome": -1.5,
        "spreadHomeOdds": 180,
        "spreadAway": 1.5,
        "spreadAwayOdds": -220,
        "total": 6.0,
        "totalOverOdds": -110,
        "totalUnderOdds": -110,
        "capturedAt": "2026-01-15T12:00:00Z"
      }
    ],
    "bookmaker_count": 4
  }
}
```

---

## POST /v1/get_line_movement (25 credits)

Time-series odds snapshots showing how lines moved. Most expensive tool.

### Request

```json
{
  "game_id": "2025020887",      // required
  "bookmaker": "fanduel"        // optional: lowercase key
}
```

### Response

```json
{
  "data": {
    "game_id": "2025020887",
    "home_team": "BUF",
    "away_team": "TOR",
    "movement": {
      "draftkings": [
        { "bookmaker": "draftkings", "snapshotType": "opening", "mlHome": -115, "mlAway": -105, "spreadHome": -1.5, "total": 6.0, "capturedAt": "2026-01-15T10:00:00Z" },
        { "bookmaker": "draftkings", "snapshotType": "closing", "mlHome": -130, "mlAway": 110, "spreadHome": -1.5, "total": 6.5, "capturedAt": "2026-01-15T23:00:00Z" }
      ]
    }
  }
}
```

---

## Error Responses

All errors return JSON with an `error` field:

```json
{ "error": "Team 'XYZ' not found. Use standard NHL abbreviations (e.g. BUF, TOR, NYR)." }
```

| Status | Meaning |
|--------|---------|
| 400 | Invalid parameters |
| 401 | Missing or invalid API key |
| 402 | Insufficient credits |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Server error |

## Credit Costs

| Credits | Tools |
|---------|-------|
| 1 | list_teams |
| 2 | get_standings, get_schedule, search_players |
| 5 | get_games, get_team_stats, get_player_stats, get_goalie_stats |
| 10 | get_odds, get_game_detail, get_head_to_head |
| 25 | get_line_movement |