PlayCaller API

71 live endpoints across 9 sports. NFL, MLB, NBA, NHL, CFB, Soccer (6 leagues), Tennis, Golf, and UFC — player data, stats, scores, standings, injury signals, fantasy scoring, historical trends, and the validated /v1/feed intelligence layer — all in clean JSON.

Base URL: https://playcallerapp.com
Most data endpoints use the /v1/ prefix (e.g. /v1/mlb/players, /v1/nfl/games). Intelligence feeds are at /intelligence/ (no /v1/ prefix). Account endpoints use /daas/ (e.g. /daas/usage). All responses are JSON. All requests use HTTPS.

5-Step Quickstart

From zero to your first successful API call in under 5 minutes.

1

Start your free trial

Go to playcallerapp.com/developer and enter your email to start a 14-day free trial. No credit card required. Disposable email addresses are blocked.

2

Verify your email

Check your inbox for a verification email from [email protected]. Click the link to activate your key. The link expires in 24 hours.

3

Copy your API key from the dashboard

After verifying, you'll be redirected to your developer dashboard at /developer/dashboard where your key is displayed. Sandbox keys are prefixed pc_sbx_. Build keys use pc_bld_, Pro Insights keys use pc_pri_.

4

Store your key securely

Store your API key as an environment variable. Never commit it to source code. Use PC_API_KEY=pc_sbx_your_key in your .env file.

5

Make your first call

Fire a test request to confirm authentication. A 200 response means you're live.

bash

curl -H "X-PlayCaller-Key: $PC_API_KEY" \
  https://playcallerapp.com/intelligence/news?limit=1

SDK Quickstart

Official SDKs for TypeScript and Python — full IDE autocomplete, typed responses, and built-in retry handling. Auto-generated from the OpenAPI spec so they're always in sync.

TypeScript / Node.js

bash

npm install @playcaller/sdk

typescript

// Full IDE autocomplete + typed responses
import { PlayCallerClient } from "@playcaller/sdk";

const client = new PlayCallerClient({ apiKey: "pc_sbx_..." });

// Get NFL injury signals
const injuries = await client.intelligence.getInjuries({ sport: "nfl" });

// Get player alpha metrics (Pro Insights+)
const alpha = await client.nfl.players.getAlpha("pc_nfl_001234");

Python

bash

pip install playcaller-sdk

python

from playcaller import PlayCallerClient

client = PlayCallerClient(api_key="pc_sbx_...")

# Get live MLB game scores
games = client.mlb.get_games(date="today")

# Semantic player similarity (Pro Insights+)
similar = client.players.get_similar("pc_nfl_001234", sport="nfl")

MCP Server (AI agents)

The PlayCaller MCP server lets Cursor, Claude Desktop, and other AI tools call sports data endpoints directly as tools — no SDK required.

json

// Add to your Claude Desktop / Cursor MCP config:
{
  "playcaller": {
    "url": "https://playcallerapp.com/mcp",
    "headers": { "X-PlayCaller-Key": "pc_sbx_..." }
  }
}

Authentication

All API requests must include your API key in the X-PlayCaller-Key header. Query-string authentication is not supported.

Header format

http

X-PlayCaller-Key: pc_sbx_your_api_key_here

Key prefixes by tier: pc_sbx_ (Sandbox), pc_bld_ (Build), pc_pri_ (Pro Insights), pc_syn_ (Syndicate Alpha).

Successful authentication

A valid key returns HTTP 200 with your requested data:

json

{
  "status": "success",
  "data": { /* ... response payload ... */ }
}

Failed authentication — 401

A missing or invalid key returns HTTP 401:

json

{
  "status": "error",
  "code": "INVALID_API_KEY",
  "message": "API key is missing or invalid. Include it in the X-PlayCaller-Key header."
}

Security: Never expose your API key in client-side code or public repositories. Rotate compromised keys immediately from Settings → API Keys → Revoke.

GET /intelligence/news

Real-time player signals across NFL, MLB, NBA, and NHL — injuries, depth chart changes, role shifts, and practice reports. Sourced from beat reporter feeds. Updated every 2 hours. Available on all tiers.
Note: this endpoint is at /intelligence/news, not /v1/intelligence/news — intentionally outside the versioned namespace.

Parameters

Parameter	Type	Required	Description
sport	string	Optional	Filter by sport: `nfl`, `mlb`, `nba`. Omit to return all sports. Passing `?position=` returns a 400.
severity	string	Optional	Filter by severity: `high`, `medium`, `low`. Omit to return all.
team	string	Optional	3-letter team abbreviation (e.g., `PHI`, `KC`, `NYY`). Filter to single team.
limit	integer	Optional	Records to return. Default: `25`. Max: `100`.

Example — cURL

bash

curl -X GET \
  -H "X-PlayCaller-Key: pc_sbx_your_key" \
  "https://playcallerapp.com/intelligence/news?sport=nfl&severity=high&team=SF&limit=5"

Example — Python

python

import requests

api_key = "pc_sbx_your_key"
url = "https://playcallerapp.com/intelligence/news"

params = {
    "sport": "nfl",
    "severity": "high",
    "limit": 5
}
headers = {"X-PlayCaller-Key": api_key}

response = requests.get(url, headers=headers, params=params)
data = response.json()

for signal in data["data"]:
    print(signal["player_name"], signal["sport"], signal["severity"], signal["summary"])

200 — Successful Response

json

{
  "success": true,
  "endpoint": "/intelligence/news",
  "count": 2,
  "data": [
    {
      "id": 1247,
      "player_name": "Christian McCaffrey",
      "team": "SF",
      "sport": "nfl",
      "signal_type": "injury_update",
      "severity": "high",
      "title": "McCaffrey listed doubtful with calf injury",
      "summary": "CMC did not practice Wednesday or Thursday. Elijah Mitchell expected to start.",
      "source": "ESPN Injury Report",
      "source_url": "https://espn.com/...",
      "published_at": "2026-03-28T14:32:00Z"
    }
  ],
  "meta": {
    "tier": "sandbox",
    "calls_remaining_today": 195
  }
}

Response Fields

Field	Type	Description
id	integer	Signal record ID
player_name	string	Full player name
team	string	3-letter team code
sport	string	Sport key: `nfl`, `mlb`, or `nba`
signal_type	string	Type of signal (e.g., `injury_update`, `depth_chart`, `role_change`)
severity	string	`high`, `medium`, or `low`
title	string	Short signal headline
summary	string	Full signal text
confidence_score	integer\|null	Calibrated probability score (0-75 display range) from a logistic regression model trained on 20,585 observations across 5 NFL seasons. AUC-ROC 0.697, 4.61x decile lift. `null` for non-NFL signals.
source	string	Source name (e.g., beat reporter, injury report)
source_url	string\|null	Original source URL, if available
published_at	string	ISO 8601 timestamp when signal was scraped

GET /intelligence/injuries

Dedicated injury feed — returns only injury-type signals (injury, injury_update, ir_placement, return_from_ir). Filters out general news and role change signals. Updated every 2 hours. Available on all tiers.
Note: this endpoint is at /intelligence/injuries, not /v1/intelligence/injuries.

Example — cURL

bash

curl "https://playcallerapp.com/intelligence/injuries?sport=nfl&severity=high&team=CIN&limit=5" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

Query Parameters

Parameter	Type	Required	Description
sport	string	Optional	Filter by sport: `nfl`, `mlb`, `nba`. Omit for all sports.
severity	string	Optional	Filter: `high`, `medium`, `low`
team	string	Optional	3-letter team code (e.g., `CIN`, `NYY`, `LAL`)
player	string	Optional	Player name substring match
limit	integer	Optional	Max results (default 50, max 200)

Response Fields

Field	Type	Description
player_name	string	Full player name
team	string	3-letter team abbreviation
sport	string	Sport key: `nfl`, `mlb`, or `nba`
signal_type	string	`injury`, `injury_update`, `ir_placement`, or `return_from_ir`
severity	string	`high`, `medium`, or `low`
title	string	Short headline
summary	string	Full signal text
published_at	string	ISO 8601 timestamp when signal was scraped

GET /v1/analytics/trends Pro

Historical NFL performance data (2023–2025). Game-by-game stats including fantasy points, snap%, target share, and air yards. Grouped and sorted by player. Requires Pro Insights tier.

Parameters

Parameter	Type	Required	Description
player_name	string	Optional	Partial name match (case-insensitive). E.g., `McCaffrey`, `Hill`.
team	string	Optional	3-letter team abbreviation (e.g., `MIA`, `SF`).
position	string	Optional	`QB`, `RB`, `WR`, `TE`. Filter by position.
season	integer	Optional	NFL season year: `2023`, `2024`, or `2025`.
week	integer	Optional	NFL week number (1–18). Filter to a specific week.
limit	integer	Optional	Max records to return. Default: `50`. Max: `500`.

Example — cURL

bash

curl -X GET \
  -H "X-PlayCaller-Key: pc_pri_your_key" \
  "https://playcallerapp.com/v1/analytics/trends?position=RB&season=2024&limit=10"

Example — Python

python

import requests

api_key = "pc_pri_your_key"
url = "https://playcallerapp.com/v1/analytics/trends"

params = {
    "player_name": "McCaffrey",
    "season": 2024
}
headers = {"X-PlayCaller-Key": api_key}

response = requests.get(url, headers=headers, params=params)
data = response.json()

for trend in data["trends"]:
    print(trend["player_name"], "avg fp:", trend["avg_fantasy_points"])

200 — Successful Response

json

{
  "success": true,
  "endpoint": "/v1/analytics/trends",
  "seasons": [2024],
  "total_records": 12,
  "trends": [
    {
      "player_name": "Christian McCaffrey",
      "team": "SF",
      "position": "RB",
      "games_in_sample": 4,
      "avg_fantasy_points": 28.4,
      "recent_game": {
        "season": 2024,
        "week": 4,
        "opponent": "NE",
        "fantasy_points": 31.2,
        "rushing_yards": 141,
        "rushing_tds": 1,
        "receiving_yards": 71,
        "receptions": 7,
        "snap_pct": 84,
        "target_share": 22,
        "air_yards": 45
      },
      "all_games": [/* ... array of same shape as recent_game ... */]
    }
  ],
  "meta": {
    "tier": "pro",
    "calls_remaining_this_month": 9847
  }
}

Trend Object Fields

Field	Type	Description
player_name	string	Full player name
team	string	3-letter team code
position	string	Player position (QB, RB, WR, TE)
games_in_sample	integer	Number of game records in this player's result set
avg_fantasy_points	number	Average fantasy points across all games in sample
recent_game	object	Most recent game record (season, week, opponent, all stat fields)
all_games	array	All game records for this player in the result set. Each game includes: `season`, `week`, `opponent`, `fantasy_points`, `passing_yards`, `passing_tds`, `rushing_yards`, `rushing_tds`, `receiving_yards`, `receiving_tds`, `receptions`, `snap_pct`, `target_share`, `air_yards`

MLB — Players

Access the full MLB player database — 966 players across all 30 teams, sourced from MLB Stats API and updated daily. Available on all tiers.

GET /v1/mlb/players

List active MLB players. Filterable by position, team, status, or name search.

Parameter	Type	Required	Description
position	string	Optional	Filter by position: `SP`, `RP`, `C`, `1B`, `2B`, `3B`, `SS`, `OF`, `DH`
team	string	Optional	3-letter team abbreviation (e.g., `NYY`, `LAD`)
status	string	Optional	`active`, `injured`, `inactive`
search	string	Optional	Partial name search (case-insensitive)
limit	integer	Optional	Results per page. Default: 50. Max: 200.
offset	integer	Optional	Pagination offset. Default: 0.

bash

curl -H "X-PlayCaller-Key: pc_sbx_your_key" \
  "https://playcallerapp.com/v1/mlb/players?team=NYY&position=SP&limit=5"

json

{
  "success": true,
  "total": 18,
  "count": 5,
  "data": [
    {
      "id": "pc_mlb_694973",
      "full_name": "Gerrit Cole",
      "position": "SP",
      "team": "NYY",
      "status": "active"
    }
  ],
  "meta": {
    "sport": "mlb",
    "tier": "sandbox",
    "calls_remaining_this_month": 996
  }
}

GET /v1/mlb/players/:id

Individual player detail by PlayCaller ID (format: pc_mlb_XXXXXX).

bash

curl -H "X-PlayCaller-Key: pc_sbx_your_key" \
  "https://playcallerapp.com/v1/mlb/players/pc_mlb_660670"

GET /v1/mlb/players/:id/stats

Game-by-game stat lines for a player. Includes batting and pitching stats plus fantasy points. Updated daily after games finalize.

Parameter	Type	Required	Description
date	string	Optional	Filter to a specific game date: `YYYY-MM-DD`
limit	integer	Optional	Number of game lines. Default: 30. Max: 200.

bash

curl -H "X-PlayCaller-Key: pc_sbx_your_key" \
  "https://playcallerapp.com/v1/mlb/players/pc_mlb_660670/stats?limit=5"

json

{
  "success": true,
  "player": { "full_name": "Juan Soto", "team": "NYY", "position": "OF" },
  "data": [
    {
      "stat_date": "2026-03-20",
      "batting": { "h": 2, "hr": 1, "rbi": 3, "sb": 0, "r": 2, "bb": 1, "ab": 4 },
      "pitching": { "ip": 0, "k": 0, "sv": 0 },
      "fantasy_points": 16.5,
      "is_final": true
    }
  ]
}

MLB — Teams & Rosters

All 30 MLB teams with roster metadata. Available on all tiers.

GET /v1/mlb/teams

Returns all 30 MLB teams with abbreviation, full name, roster size, and position breakdown.

bash

curl -H "X-PlayCaller-Key: pc_sbx_your_key" \
  "https://playcallerapp.com/v1/mlb/teams"

json

{
  "success": true,
  "count": 30,
  "data": [
    {
      "abbreviation": "NYY",
      "full_name": "New York Yankees",
      "roster_size": 32,
      "active_players": 29,
      "positions": ["1B","2B","3B","C","OF","RP","SP","SS"]
    }
  ]
}

GET /v1/mlb/teams/:team/roster

Full roster for a specific team. Use 3-letter abbreviation (e.g., NYY, LAD, BOS). Optionally filter by ?position=SP.

bash

curl -H "X-PlayCaller-Key: pc_sbx_your_key" \
  "https://playcallerapp.com/v1/mlb/teams/LAD/roster?position=SP"

MLB — Games

Live and scheduled MLB game states polled from MLB Stats API every few minutes during game windows. Includes live scores, inning state, and lineup status. Available on all tiers.

GET /v1/mlb/games

Parameter	Type	Required	Description
date	string	Optional	Filter by game date: `YYYY-MM-DD`. Default: all available.
state	string	Optional	Filter by game state: `pre_game`, `scheduled`, `in_progress`, `final`, `completed`, `postponed`
limit	integer	Optional	Max results. Default: 30. Max: 100.

bash

curl -H "X-PlayCaller-Key: pc_sbx_your_key" \
  "https://playcallerapp.com/v1/mlb/games?date=2026-03-21"

json

{
  "success": true,
  "data": [
    {
      "game_pk": 748234,
      "game_date": "2026-03-21",
      "state": "final",
      "home_team": { "name": "Seattle Mariners", "score": 6 },
      "away_team": { "name": "Chicago Cubs", "score": 3 },
      "inning": 9,
      "is_final": true,
      "last_polled": "2026-03-21T04:54:52Z"
    }
  ]
}

MLB — Scoring Pro

Fantasy scoring leaders and rotisserie category leaders powered by PlayCaller's baseball scoring engine. Requires Pro Insights tier.

GET /v1/mlb/scoring/leaders

Top fantasy scorers for a given date (default: latest available date). Filterable by position, team, or date.

Parameter	Type	Required	Description
date	string	Optional	Game date: `YYYY-MM-DD`. Default: most recent.
position	string	Optional	Filter by position: `SP`, `OF`, `SS`, etc.
team	string	Optional	3-letter team abbreviation.
limit	integer	Optional	Default: 25. Max: 100.

bash

curl -H "X-PlayCaller-Key: pc_pri_your_key" \
  "https://playcallerapp.com/v1/mlb/scoring/leaders?date=2026-03-20&limit=10"

json

{
  "success": true,
  "data": [
    {
      "rank": 1,
      "player_name": "Cole Young",
      "team": "Seattle Mariners",
      "position": "SS",
      "fantasy_points": 16.5,
      "batting": { "h": 3, "hr": 1, "rbi": 2, "sb": 1 },
      "is_final": true
    }
  ]
}

GET /v1/mlb/scoring/categories

Rotisserie category leaders: top performers in HR, RBI, SB, Runs, Walks, IP, Strikeouts, and Saves. Returns top 10 per category for the latest (or specified) game date.

Parameter	Type	Required	Description
date	string	Optional	Game date: `YYYY-MM-DD`. Default: most recent date with data.

bash

curl -H "X-PlayCaller-Key: pc_pri_your_key" \
  "https://playcallerapp.com/v1/mlb/scoring/categories?date=2026-03-20"

200 — Successful Response

json

{
  "success": true,
  "stat_date": "2026-03-20",
  "home_runs": [
    { "rank": 1, "id": "pc_mlb_660670", "player_name": "Juan Soto", "team": "NYY", "position": "OF", "value": 2, "stat_date": "2026-03-20" }
  ],
  "rbi": [ /* top 10 by RBI */ ],
  "stolen_bases": [ /* top 10 by SB */ ],
  "runs": [ /* top 10 by R */ ],
  "walks": [ /* top 10 by BB */ ],
  "innings_pitched": [ /* top 10 by IP */ ],
  "strikeouts": [ /* top 10 by K */ ],
  "saves": [ /* top 10 by SV */ ]
}

Each category contains an array of up to 10 players. Each entry has: rank, id, player_name, team, position, value (the category stat), and stat_date.

Pro Insights tier required. Calling this endpoint with a Sandbox or Build key returns HTTP 403 with TIER_INSUFFICIENT.

MLB — Standings

Current MLB standings by division. Returns wins, losses, win percentage, and games back for all 30 teams. Available on all tiers.

Example — cURL

bash

curl https://playcallerapp.com/v1/mlb/standings \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

NBA Endpoints

7 NBA endpoints covering game scores, standings, teams, rosters, players, and per-game box score history. Powered by ESPN data pipelines. 127,909 historical game rows across 5 seasons (2021–2025). Available on all tiers.

GET /v1/nba/players

Returns NBA players. Filterable by name search, position, team, with pagination support.

Parameter	Type	Required	Description
search	string	Optional	Partial name match (case-insensitive)
position	string	Optional	Filter by position: `PG`, `SG`, `SF`, `PF`, `C`
team	string	Optional	Team abbreviation (e.g., `LAL`, `BOS`)
limit	integer	Optional	Results per page. Default: 50. Max: 200.
offset	integer	Optional	Pagination offset. Default: 0.

bash

curl "https://playcallerapp.com/v1/nba/players?team=BOS&position=PG" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/nba/players/:id

Returns full profile for a single NBA player by playcaller_id. Includes position, team, and status from the player identity registry.

bash

curl https://playcallerapp.com/v1/nba/players/pc_nba_lebron_01 \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/nba/players/:id/stats

Returns per-game box score history for an NBA player. Covers 5 seasons (2021–2025) with 127,909 rows total. Supports season and limit filters.

Parameter	Type	Required	Description
season	integer	Optional	Season year (e.g., `2024`). Omit for all available.
limit	integer	Optional	Results to return. Default: 30.

bash

curl "https://playcallerapp.com/v1/nba/players/pc_nba_lebron_01/stats?season=2024&limit=10" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

Box Score Fields

Field	Type	Description
game_date	string	ISO date of game
season	integer	Season year
points / rebounds / assists	number\|null	Core box score stats
steals / blocks / turnovers	number\|null	Defensive and turnover stats
minutes_played	number\|null	Minutes played
usage_rate	number\|null	Usage rate percentage
is_starter	boolean\|null	Whether the player started
is_back_to_back	boolean	Whether this game was a back-to-back
fantasy_points	number\|null	Computed DK-style fantasy points

GET /v1/nba/teams

Returns all NBA teams. Filter by conference. Each team includes player_count and a roster_url link.

bash

curl https://playcallerapp.com/v1/nba/teams?conference=east \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/nba/teams/:team/roster

Returns active roster for an NBA team by abbreviation (e.g., BOS, LAL, GSW).

bash

curl https://playcallerapp.com/v1/nba/teams/BOS/roster \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/nba/games

Returns NBA game scores and states. Filter by date. Cache-Control: 30s during live games, 120s otherwise.

bash

curl https://playcallerapp.com/v1/nba/games?date=today \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/nba/standings

Returns current NBA standings by conference and division.

bash

curl https://playcallerapp.com/v1/nba/standings \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

NFL Endpoints

6 NFL endpoints covering players, teams, game schedules, and per-game statistical history. Game log data covers the 2024 season (weeks 1–18). Available on all tiers.

GET /v1/nfl/players

Returns NFL players from the player identity registry. Supports search, position, and team filters with pagination.

Parameter	Type	Required	Description
search	string	Optional	Partial name match (case-insensitive)
position	string	Optional	Filter by position: `QB`, `RB`, `WR`, `TE`, `K`, `DEF`
team	string	Optional	Team abbreviation (e.g., `KC`, `SF`, `DAL`)
limit	integer	Optional	Results per page. Default: 50. Max: 200.
offset	integer	Optional	Pagination offset. Default: 0.

bash

curl "https://playcallerapp.com/v1/nfl/players?team=KC&position=QB" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/nfl/players/:id

Returns full profile for a single NFL player by playcaller_id. Enriched with team name, conference, and division from the 32-team static roster.

bash

curl https://playcallerapp.com/v1/nfl/players/pc_nfl_mahomes_01 \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

200 — Player Profile

json

{
  "success": true,
  "player": {
    "playcaller_id": "pc_nfl_mahomes_01",
    "full_name": "Patrick Mahomes",
    "position": "QB",
    "team": "KC",
    "team_name": "Kansas City Chiefs",
    "conference": "AFC",
    "division": "AFC West",
    "status": "active"
  }
}

GET /v1/nfl/players/:id/stats

Returns per-game statistical history for an NFL player. Data sourced from historical_performance; 2024 season weeks 1–18 are available.

Parameter	Type	Required	Description
season	integer	Optional	Season year (e.g., `2024`). Omit for all available.
week	integer	Optional	NFL week number (1–18 regular season).
limit	integer	Optional	Results to return. Default: 20.

bash

curl "https://playcallerapp.com/v1/nfl/players/pc_nfl_mahomes_01/stats?season=2024" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

Game Log Fields

Field	Type	Description
season	integer	NFL season year
week	integer	Week number
passing_yards / passing_tds	number\|null	Passing stats (QB path)
rushing_yards / rushing_tds	number\|null	Rushing stats
receiving_yards / receiving_tds / receptions	number\|null	Receiving stats
snap_pct	number\|null	Snap share (0–100)
target_share	number\|null	Target share for skill players
air_yards	number\|null	Total air yards on targets
fantasy_points	number\|null	Computed fantasy points (PPR scoring)

GET /v1/nfl/teams

Returns all 32 NFL teams with conference, division, and active player count. Filter by conference or division.

Parameter	Type	Required	Description
conference	string	Optional	`AFC` or `NFC`
division	string	Optional	e.g., `AFC West`, `NFC North`

bash

curl "https://playcallerapp.com/v1/nfl/teams?conference=AFC" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/nfl/teams/:team/roster

Returns active roster for a team by 2-3 letter abbreviation (e.g., KC, SF, DAL). Optional ?position= filter.

bash

curl "https://playcallerapp.com/v1/nfl/teams/KC/roster?position=WR" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/nfl/games

Returns NFL game schedule and scores from the nfl_games table (285 games, 2026 season schedule).

Parameter	Type	Required	Description
season	integer	Optional	Season year (e.g., `2026`)
week	integer	Optional	NFL week number
status	string	Optional	Game status filter (e.g., `final`, `scheduled`)
limit	integer	Optional	Results to return. Default: 16.

bash

curl "https://playcallerapp.com/v1/nfl/games?season=2026&week=1" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/nfl/standings

Returns W/L/T records for all 32 NFL teams, computed from game results. Grouped by conference and division. Optional ?season= filter (defaults to current year).

bash

curl "https://playcallerapp.com/v1/nfl/standings?season=2026" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/players/search

Search across NFL, MLB, NBA, and NHL player identities in a single call. Useful when the sport is unknown or you want autocomplete across all sports. Returns up to 100 results ordered alphabetically.

Parameter	Type	Required	Description
q	string	Required	Partial name match (case-insensitive). Minimum 2 characters.
sport	string	Optional	Narrow to one sport: `nfl`, `mlb`, or `nba`. Omit for all.
position	string	Optional	Position filter (e.g., `QB`, `OF`, `PG`).
limit	integer	Optional	Results to return. Default: 20. Max: 100.

bash

curl "https://playcallerapp.com/v1/players/search?q=mahomes" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

200 — Successful Response

json

{
  "success": true,
  "endpoint": "/v1/players/search",
  "count": 1,
  "query": "mahomes",
  "data": [
    {
      "playcaller_id": "pc_nfl_mahomes_01",
      "full_name": "Patrick Mahomes",
      "position": "QB",
      "team": "KC",
      "sport": "nfl",
      "status": "active"
    }
  ]
}

College Football Endpoints

College football game scores, standings, and rankings. Rankings require Pro Insights tier.

GET /v1/cfb/games

Returns CFB game scores and states. Filter by date.

bash

curl https://playcallerapp.com/v1/cfb/games?date=2026-04-10 \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/cfb/standings

Returns current CFB conference standings.

bash

curl https://playcallerapp.com/v1/cfb/standings \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/cfb/rankings Pro

Returns AP Top 25 and CFP rankings. Requires Pro Insights tier.

bash

curl https://playcallerapp.com/v1/cfb/rankings \
  -H "X-PlayCaller-Key: pc_pri_your_key"

NHL Endpoints

NHL game scores, live updates, and division standings. Available on all tiers.

GET /v1/nhl/games

Returns NHL game scores and states. Optional ?date=today, ?state=in_progress, ?limit=.

bash

curl https://playcallerapp.com/v1/nhl/games?date=today \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/nhl/standings

Returns NHL standings grouped by division. Optional ?season= and ?division=.

bash

curl https://playcallerapp.com/v1/nhl/standings \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

Soccer Endpoints

Soccer game scores and league standings across 6 major leagues: EPL, MLS, La Liga, Bundesliga, Serie A, and UEFA Champions League. Available on all tiers.

GET /v1/soccer/games

bash

curl https://playcallerapp.com/v1/soccer/games?league=la_liga&date=today \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/soccer/standings

bash

curl https://playcallerapp.com/v1/soccer/standings?league=bundesliga \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

Tennis Endpoints

ATP and WTA match scores and results. Year-round coverage across all Grand Slams and tour events. Available on all tiers.

GET /v1/tennis/matches

Returns live and completed matches. Filter by ?tour=atp|wta, ?date=today, ?state=in_progress|final.

bash

curl https://playcallerapp.com/v1/tennis/matches?tour=atp&date=today \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

Golf Endpoints

PGA Tour and LPGA Tour leaderboards with live scoring updated every 4 hours during active tournaments. Available on all tiers.

GET /v1/golf/tournaments

Lists active and recent tournaments. Optional ?tour=pga|lpga.

bash

curl https://playcallerapp.com/v1/golf/tournaments \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/golf/leaderboard

Returns current tournament leaderboard with positions, scores to par, and round-by-round scores. Optional ?tour=pga|lpga, ?limit= (max 156).

bash

curl https://playcallerapp.com/v1/golf/leaderboard?limit=25 \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /v1/sports

Returns the list of all sports and endpoints currently available in the API. Useful for dynamically discovering available data sources and their status.

bash

curl https://playcallerapp.com/v1/sports \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

GET /daas/usage

Returns quota usage, rate limit, and tier information for the authenticated API key. Use this to build quota-aware dashboards or to monitor remaining calls before you hit limits. Available on all tiers.

Example — cURL

bash

curl -X GET \
  -H "X-PlayCaller-Key: pc_sbx_your_key" \
  "https://playcallerapp.com/daas/usage"

200 — Successful Response

json

{
  "success": true,
  "key_prefix": "pc_sbx_abc1...",
  "tier": "sandbox",
  "is_trial": true,
  "trial_starts_at": "2026-03-28T00:00:00Z",
  "trial_ends_at": "2026-04-11T00:00:00Z",
  "trial_days_remaining": 12,
  "calls_this_month": 153,
  "calls_limit_month": 1000,
  "calls_remaining": 847,
  "rate_limit_per_min": 30,
  "reset_at": "2026-04-01T00:00:00Z",
  "upgrade_url": "https://playcallerapp.com/developer#pricing",
  "endpoint_breakdown": [
    {
      "endpoint": "/v1/intelligence/news",
      "calls": "98",
      "avg_ms": 42,
      "last_call": "2026-03-28T11:52:33Z"
    },
    {
      "endpoint": "/v1/mlb/players",
      "calls": "55",
      "avg_ms": 61,
      "last_call": "2026-03-28T10:14:07Z"
    }
  ]
}

Response Fields

Field	Type	Description
key_prefix	string	First 12 chars of your key + "..." (never the full key)
tier	string	`sandbox`, `build`, `pro_insights`, or `syndicate_alpha`
is_trial	boolean	Whether this is a free trial key
trial_days_remaining	integer\|null	Days left in trial, or `null` for paid keys
calls_this_month	integer	API calls made in the current billing cycle
calls_limit_month	integer	Monthly call quota for your tier
calls_remaining	integer	Calls remaining before hitting `MONTHLY_QUOTA_EXCEEDED`
rate_limit_per_min	integer	Per-minute rate limit
reset_at	string	ISO 8601 timestamp when monthly quota resets
endpoint_breakdown	array	Per-endpoint call counts + avg response time for the last 30 days

Rate Limits & Response Headers

Rate limits are enforced per API key, measured daily and per-minute. Daily limits reset at midnight UTC.

Rate-Limit Response Headers

Every authenticated response includes standard rate-limit headers so you can track your position without polling /daas/usage:

Header	Example	Description
X-PlayCaller-Tier	sandbox	Your current tier name
X-RateLimit-Limit	200	Your daily request ceiling (`unlimited` for Syndicate Alpha)
X-RateLimit-Remaining	194	Requests remaining today
X-RateLimit-Reset	1751846400	Unix epoch timestamp when the daily counter resets (midnight UTC)
X-RateLimit-Policy	200/day;w=86400, 2/min;w=60	Full policy: daily cap and per-minute cap
X-PlayCaller-Sandbox-Expires	2026-07-21T00:00:00.000Z	ISO timestamp when sandbox expires. Sandbox keys only.
X-PlayCaller-Sandbox-Days-Remaining	9	Integer days remaining in sandbox. Sandbox keys only.

bash

# Check your rate-limit position from any response headers
curl -sI -H "X-PlayCaller-Key: pc_sbx_your_key" \
  https://playcallerapp.com/v1/sports \
  | grep -i x-ratelimit

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 194
X-RateLimit-Reset: 1751846400
X-RateLimit-Policy: 200/day;w=86400, 2/min;w=60

Plan	Daily Calls	Rate Limit
Developer Sandbox ($0, 14 days, no card)	200 req/day	2 req/min
Build ($99/mo)	2,000 req/day (60,000/mo)	2 req/min
Pro Insights ($499/mo)	20,000 req/day (600,000/mo)	5 req/min
Syndicate Alpha ($1,499/mo)	No daily ceiling	Custom

Pro+ is a forthcoming add-on tier — priority access to new validated confidence models as they ship. See the waitlist page for details. Pricing and rate limits aren't finalized yet.

429 — Per-Minute Rate Limit

Exceeding your per-minute limit returns HTTP 429. The Retry-After header tells you exactly when to retry:

json

{
  "error_code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit of 30 req/min exceeded. Retry in 42s or upgrade your plan.",
  "calls_this_minute": 31,
  "limit_per_minute": 30,
  "retry_after_seconds": 42,
  "upgrade_url": "https://playcallerapp.com/?upgrade=1"
}

429 — Monthly Quota Exhausted

Once your monthly call quota is used up, all requests return HTTP 429 until your billing cycle resets:

json

{
  "error_code": "MONTHLY_QUOTA_EXCEEDED",
  "message": "Monthly call quota of 1000 exceeded. Resets on 2026-04-01.",
  "calls_used": 1000,
  "calls_limit": 1000,
  "resets_on": "2026-04-01T00:00:00Z",
  "upgrade_url": "https://playcallerapp.com/?upgrade=1"
}

Upgrade path: Hit your limit? Upgrade your plan at playcallerapp.com. Changes take effect immediately — no waiting for cycle reset.

Error Codes

All errors return a standardized JSON object with error_code, message, and documentation_url.

HTTP Status	Code	Meaning
400	INVALID_PARAMETER	A query parameter value is malformed or out of range.
401	MISSING_API_KEY	`X-PlayCaller-Key` header is absent.
401	INVALID_API_KEY	Key not found, revoked, or not yet verified.
402	TRIAL_EXPIRED	14-day Developer Sandbox has ended. Upgrade to a paid plan to continue.
403	TIER_INSUFFICIENT	Endpoint requires a higher plan tier. Response includes `required_tier` and `upgrade_url`.
429	RATE_LIMIT_EXCEEDED	Per-minute request limit exceeded. Retry after `retry_after_seconds`.
429	MONTHLY_QUOTA_EXCEEDED	Monthly call quota exhausted. Resets on billing cycle date.
500	INTERNAL_ERROR	Server error. Retry with exponential backoff.

402 — Trial Expired

json

{
  "error_code": "TRIAL_EXPIRED",
  "message": "Your 14-day Developer Sandbox has expired. Upgrade to a paid plan to continue.",
  "trial_ended_at": "2026-04-11T00:00:00Z",
  "upgrade_url": "https://playcallerapp.com/?upgrade=1"
}

403 — Tier Insufficient

json

{
  "error_code": "TIER_INSUFFICIENT",
  "message": "This endpoint requires pro_insights tier or higher. Your current tier: build.",
  "current_tier": "build",
  "required_tier": "pro_insights",
  "upgrade_url": "https://playcallerapp.com/?upgrade=1"
}

GET /v1/feed Pro

Pre-composed player intelligence dossier. Returns a complete intelligence object for a player in a single API call: calibrated confidence score, validated heat signal, full signal breakdown, and a plain-English synthesis sentence. Rate-capped on Pro Insights; uncapped on Syndicate Alpha. Requires Pro Insights tier.

Query Parameters

Parameter	Type	Required	Description
player	string	Required	Player name or playcaller_id
team	string	Optional	3-letter team code to disambiguate common names

Response Fields

Field	Type	Description
player_name	string	Canonical player name
team	string	Current team abbreviation
position	string	Position code
confidence_score	integer\|null	Calibrated probability score (0-75 display range) from a logistic regression model trained on 20,585 observations across 5 NFL seasons. AUC-ROC 0.697, 4.61x decile lift. Display capped at 75 pending tail calibration validation.
heat_signal	string\|null	Validated directional heat: `Cold`, `Warming`, `Hot`, or `Surging`. AUC-ROC 0.623, quartile lift 25.6pp, 3-fold walk-forward validated.
synthesis	string\|null	Plain-English summary generated from signal data, validated against source before delivery
signals	array	Individual signals that drove the score, with source and weight
_audit	object	Model provenance block: `model_version`, `observations_used`, `generated_at`, `signals_validated`. Present on all /v1/feed responses.

MCP Server

PlayCaller implements Anthropic's Model Context Protocol over HTTP. Connect Cursor, Claude Desktop, Perplexity, or any MCP-compatible AI to live sports intelligence with a single endpoint.

7 Tools

Tool	Description
get_injury_signals	Active beat reporter signals, filterable by sport and severity
get_player_identity	Resolve a player across ESPN, Sleeper, Yahoo, NFL.com. 31,000+ player identities normalized
get_anomaly_scores	Players deviating from 3-season usage baseline, score 0-100
get_player_projections	Trailing 10-game fantasy point average with injury signal overlay. Not a predictive model — a plain average.
get_prediction_markets	Active Kalshi prop markets. `confidence_score` field pending Kalshi data consent.
get_player_stats	Per-game stat history for NFL/MLB/NBA/NHL players by name. NFL 2024 wks 1–18, NBA 5 seasons (127k rows).
get_team_roster	Active roster for any NFL, MLB, NBA, or NHL team by abbreviation. Optional position filter.

Quick Connect

Add to .cursor/mcp.json or Claude Desktop config:

json

{ "mcpServers": { "playcaller": { "url": "https://playcallerapp.com/mcp", "headers": { "X-PlayCaller-Key": "YOUR_KEY" } } } }

Full tool schemas at GET /mcp (unauthenticated discovery). Auth: X-PlayCaller-Key header on POST.

GET /v1/trending

Returns the top hashtag trends across sports, scraped every 2 hours. Useful for surfacing breakout player moments and news spikes. Available on all tiers. Max 50 results.

Query Parameters

Param	Type	Required	Description
sport	string	Optional	Filter by sport: `nfl`, `mlb`, `nba`
limit	integer	Optional	Max results (default 20, max 50)

Example

bash

curl "https://playcallerapp.com/v1/trending?sport=mlb&limit=10" \
  -H "X-PlayCaller-Key: pc_sbx_your_key"

200 — Response fields: tag, sport, category, relevance_score, scraped_at, expires_at

GET /v1/articles/waiver

Returns AI-generated waiver wire analysis articles backed by validated signal data. Requires Pro Insights tier. The sport parameter is required.

Query Parameters

Param	Type	Required	Description
sport	string	Required	Sport: `nfl`, `mlb`, `nba`
week	integer	Optional	Week number (NFL). Defaults to current week.

Example

bash

curl "https://playcallerapp.com/v1/articles/waiver?sport=nfl" \
  -H "X-PlayCaller-Key: pc_pri_your_key"

200 — Response includes: title, content (full article), sport, week, published_at, signals_used

403 — TIER_INSUFFICIENT: Pro Insights required

GET /v1/nba/confidence

Returns detailed NBA player confidence scores from the validated NBA Confidence V3 model (AUC 0.855). Includes raw score, percentile rank, component breakdown, and a model audit block. Requires Pro Insights tier.

Query Parameters

Param	Type	Required	Description
player	string	Optional	Filter by player name (partial match)
team	string	Optional	Filter by team abbreviation
limit	integer	Optional	Max results (default 20)

Example

bash

curl "https://playcallerapp.com/v1/nba/confidence?limit=5" \
  -H "X-PlayCaller-Key: pc_pri_your_key"

200 — Response includes: player_name, team, confidence_score, percentile, component_breakdown, model_audit

403 — TIER_INSUFFICIENT: Pro Insights required

GET /v1/:sport/games/history

Returns historical per-game performance data for players. Supports nfl, nba, and mlb. NFL returns snap_pct, target_share, air_yards. NBA returns usage_rate, is_starter, is_back_to_back. MLB returns full batting and pitching lines. Requires Pro Insights tier.

Path Parameters

Param	Type	Required	Description
sport	string	Required	Path segment: `nfl`, `nba`, or `mlb`

Query Parameters

Param	Type	Required	Description
player	string	Optional	Filter by player name (partial match)
team	string	Optional	Filter by team abbreviation
season	integer	Optional	Season year (e.g. `2025`)
limit	integer	Optional	Max results (default 50)

Example

bash

curl "https://playcallerapp.com/v1/nfl/games/history?team=KC&season=2025" \
  -H "X-PlayCaller-Key: pc_pri_your_key"

200 — Response varies by sport; all include player_name, team, game_date, and sport-specific stat columns

403 — TIER_INSUFFICIENT: Pro Insights required

404 — Unsupported sport

GET /v1/:sport/players/:id/alpha

Returns pre-computed alpha metrics for a player: consistency score, momentum delta, and opportunity ceiling. Computed weekly from the last 8 games of historical performance data. Requires Pro Insights tier.

Path Parameters

Param	Type	Required	Description
sport	string	Required	`nfl`, `mlb`, or `nba`
id	string	Required	PlayCaller player ID (e.g. `pc_nfl_4046533`)

Response Fields

Field	Type	Description
consistency_score	number	0–100. Higher = more consistent floor. Based on stddev of snap_pct/minutes over last 8 games.
momentum_delta	number	Signed float. Avg fantasy points last 3 games minus avg games 4–6 back. Positive = trending up.
opportunity_ceiling	number	90th-percentile target share or usage rate from last 8 games — what the player can do in an optimal game.
sample_size	integer	Games used to compute metrics.
week_computed	string	ISO week the batch was last run.

Example

bash

curl "https://playcallerapp.com/v1/nfl/players/pc_nfl_4046533/alpha" \
  -H "X-PlayCaller-Key: pc_pri_your_key"

200 — Returns player_id, sport, consistency_score, momentum_delta, opportunity_ceiling, sample_size, week_computed

403 — TIER_INSUFFICIENT: Pro Insights required

404 — No alpha data yet for this player (batch runs weekly)

GET /v1/players/similar/:id

Returns players with the most similar production profile using pgvector cosine similarity. Each player is represented as an 8-dimensional stat vector (avg fantasy points, usage, opportunity, rushing yards, receiving yards, consistency, momentum, ceiling) — no LLM, purely computed from historical performance. Requires Pro Insights tier.

Path Parameters

Param	Type	Required	Description
id	string	Required	PlayCaller player ID to find matches for

Query Parameters

Param	Type	Required	Description
sport	string	Required	Sport: `nfl`, `mlb`, or `nba`
limit	integer	Optional	Number of similar players to return (default 10, max 25)

Example

bash

curl "https://playcallerapp.com/v1/players/similar/pc_nfl_4046533?sport=nfl&limit=5" \
  -H "X-PlayCaller-Key: pc_pri_your_key"

200 — Returns array of { playcaller_id, name, position, team, similarity_score } ordered by cosine similarity

403 — TIER_INSUFFICIENT: Pro Insights required

404 — No embedding computed for this player yet

GET /v1/events/stream

Opens a persistent Server-Sent Events connection that pushes real-time sports events as they happen. Heartbeat every 30 seconds keeps the connection alive. Requires Pro Insights tier.

Event Types

Event	Trigger	Payload
player.injured	Every 4h injury refresh	`{ player, team, severity, signal_type, sport }`
game.score_updated	Live game pipeline	`{ game_id, home_team, away_team, home_score, away_score, status }`
anomaly.detected	Weekly anomaly refresh	`{ player, team, anomaly_score, recommendation }`

Example

bash

curl -N "https://playcallerapp.com/v1/events/stream" \
  -H "X-PlayCaller-Key: pc_pri_your_key"

JavaScript Example

javascript

const source = new EventSource(
  "https://playcallerapp.com/v1/events/stream",
  { headers: { "X-PlayCaller-Key": "pc_pri_your_key" } }
);
source.addEventListener("player.injured", e => console.log(JSON.parse(e.data)));
source.addEventListener("game.score_updated", e => console.log(JSON.parse(e.data)));

200 — text/event-stream; heartbeat every 30s; connection persists until closed

403 — TIER_INSUFFICIENT: Pro Insights required

Webhooks (Syndicate Alpha)

Register HTTPS endpoints to receive push delivery of sports events as they happen. Every delivery is signed with HMAC-SHA256 so you can verify it came from PlayCaller. Auto-retry on failure (0s → 30s → 5min). Requires Syndicate Alpha tier.

Endpoints

Method	Path	Description
POST	/daas/webhooks	Register a new webhook. Body: `{ url, events[] }`
GET	/daas/webhooks	List active webhooks for this API key
DELETE	/daas/webhooks/:id	Deactivate a webhook
GET	/daas/webhooks/:id/deliveries	Delivery log with status codes and retry history

Signature Verification

Every POST includes X-PlayCaller-Signature: sha256=<hex> and X-PlayCaller-Delivery-Id headers. Verify before processing:

javascript

const crypto = require('crypto');
function verifySignature(secret, rawBody, sigHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sigHeader));
}

Register Example

bash

curl -X POST "https://playcallerapp.com/daas/webhooks" \
  -H "X-PlayCaller-Key: pc_syn_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.com/hooks","events":["player.injured","game.score_updated"]}'

201 — Returns { id, url, events, secret }. Store secret — it is only returned once.

403 — TIER_INSUFFICIENT: Syndicate Alpha required

Webhook auto-deactivates after 3 consecutive failures. You will receive an email notification and can re-register at any time.

Roadmap

New capabilities ship with the Pro+ tier as they clear validation. Join the waitlist to lock in early pricing.

GET /v1/feed

The Confidence Moat™ — priority access to new validated confidence models as they land in the Feed, built the same way as the live NFL and NBA confidence scores today (real AUC, not a heuristic).

Pro+ — Coming Soon

GET /v1/identity/map

Cross-platform player identity resolution — maps a player across Sleeper, ESPN, Yahoo, DraftKings, FanDuel, and Kalshi using a unified PlayCaller player ID. Stop maintaining your own lookup tables.

Pro+ — Coming Soon