API Reference

The StatsGuy REST API lets you pull game, season, team, and player stats programmatically. Authenticate using an X-API-Key header with a key generated in your dashboard.

Authentication

All API requests require an X-API-Key header:

curl https://statsguy.clickingspree.com/api/v1/stats/game/GAME_ID \
  -H "X-API-Key: sg_your_key_here"

API keys are scoped to your account. Generate and revoke keys from Dashboard → API Keys.

Base URL

https://statsguy.clickingspree.com/api/v1

Rate Limits

500 requests per 15-minute window per API key.

Endpoints — Stats

GET

https://statsguy.clickingspree.com/api/v1/stats/game/:gameId

Returns team stats and player stats for a single completed or in-progress game.

Example Response

{
  "game": { "id": "...", "gameDate": "2025-10-04", "status": "final",
             "finalHomeScore": 28, "finalAwayScore": 14, ... },
  "teamStats": [
    { "team": { "abbreviation": "WSW" },
      "passYards": 312, "rushYards": 145, "totalYards": 457, ... }
  ],
  "playerStats": [
    { "player": { "lastName": "Johnson", "firstName": "D.", "number": "5", "position": "QB" },
      "passAttempts": 28, "passCompletions": 19, "passYards": 247, "passTouchdowns": 3, ... }
  ]
}

GET

https://statsguy.clickingspree.com/api/v1/stats/season/:seasonId

Returns season-aggregate player stats across all final games in the season.

Example Response

{
  "season": { "id": "...", "name": "2025 Season", "year": 2025 },
  "playerStats": [
    { "playerId": "...", "teamId": "...",
      "_sum": { "passYards": 2847, "passTouchdowns": 24, "rushYards": 312, ... } }
  ]
}

GET

https://statsguy.clickingspree.com/api/v1/stats/team/:teamId

Returns game-by-game team stats for all games a team has played.

Parameters

Name	Type	Required	Description
teamId	string (UUID)	yes	The team ID

Example Response

{
  "team": { "name": "Westside Warriors", "abbreviation": "WSW", ... },
  "stats": [
    { "game": { "gameDate": "2025-09-05", ... },
      "passYards": 280, "rushYards": 190, "totalPoints": 35, ... }
  ]
}

GET

https://statsguy.clickingspree.com/api/v1/stats/player/:playerId

Returns game-by-game stats for a single player.

Example Response

{
  "player": { "firstName": "Derek", "lastName": "Johnson", "number": "5", "position": "QB" },
  "stats": [
    { "game": { "gameDate": "2025-09-05", ... },
      "passAttempts": 32, "passCompletions": 21, "passYards": 289, ... }
  ]
}

GET

https://statsguy.clickingspree.com/api/v1/stats/leaders/:seasonId

Returns season stat leaders (top passers, rushers, receivers, tacklers, etc.).

Example Response

{
  "season": { "name": "2025 Season" },
  "leaders": [
    { "playerId": "...", "_sum": { "passYards": 2847, "passTouchdowns": 24 } },
    ...
  ]
}

Endpoints — Games

GET

https://statsguy.clickingspree.com/api/v1/games

List all games for your account, optionally filtered.

Parameters

Name	Type	Required	Description
seasonId	string	no	Filter by season
teamId	string	no	Filter to games involving a team
status	string	no	scheduled \| in_progress \| final

Example Response

[
  { "id": "...", "gameDate": "2025-10-04",
    "homeTeam": { "name": "Westside Warriors", "abbreviation": "WSW" },
    "awayTeam": { "name": "Eastside Eagles", "abbreviation": "ESE" },
    "finalHomeScore": 28, "finalAwayScore": 14, "status": "final" },
  ...
]

GET

https://statsguy.clickingspree.com/api/v1/games/:id/plays

Returns full play-by-play log for a game with all passing, rushing, and defensive details.

Example Response

[
  { "playNumber": 1, "quarter": 1, "gameClock": "12:00",
    "down": 1, "distance": 10, "yardLine": 25,
    "playType": "rush", "yardsGained": 6,
    "rushingPlay": { "rusher": { "lastName": "Williams", "number": "22" }, "yards": 6, ... } },
  ...
]

Error responses

// 401 — missing or invalid API key
{ "error": "Invalid API key" }

// 404 — resource not found
{ "error": "Game not found" }

// 429 — rate limit exceeded
{ "error": "Too many requests" }

Pagination

Endpoints that return lists currently return all matching records. Pagination support (cursor-based) is on the roadmap for season endpoints with large result sets.