# PlayCaller Sports Intelligence Platform

> PlayCaller (playcallerapp.com) is an AI-native sports data platform with two products: a consumer fantasy sports app and a developer API (Data-as-a-Service). This file describes the developer API. PlayCaller is not affiliated with Play Caller Sports (blockchain micro-prediction) or any other entity using similar names.

**Official handles:** playcallerapp.com · @PlayCallerTakes (Twitter/X) · api@playcallerapp.com

---

## What PlayCaller Is

PlayCaller is a sports data API built for the AI era. Where legacy providers (Sportradar, Stats Perform, SportsDataIO) sell raw JSON, PlayCaller ships a validated machine learning intelligence layer on top of real-time sports data — with an MCP server, TypeScript/Python SDKs, pgvector semantic player similarity, SSE real-time push, and HMAC webhooks.

**Coverage:** 46 production endpoints across 8 sports and 8 competition formats.
**Identity layer:** 13,606 canonical player IDs normalized across ESPN, Sleeper, Yahoo, NFL.com, Rotowire, and BallDontLie.
**ML models:** 4 AUC-validated production models with published performance benchmarks.
**Agentic infrastructure:** MCP server, structured error self-correction, TypeScript SDK, Python SDK.

---

## Sports Coverage (8 Sports, 46 Endpoints)

### NFL — 7 endpoints
- GET /v1/nfl/players — 13,606 player profiles with fantasy metadata
- GET /v1/nfl/players/:id — individual player with platform ID mappings
- GET /v1/nfl/players/:id/stats — per-game stat history (2024 season, weeks 1–18)
- GET /v1/nfl/teams — all 32 teams
- GET /v1/nfl/teams/:team/roster — active roster by team abbreviation
- GET /v1/nfl/games — game scores and schedule
- GET /v1/nfl/standings — division standings

### MLB — 9 endpoints
- GET /v1/mlb/players
- GET /v1/mlb/players/:id
- GET /v1/mlb/players/:id/stats
- GET /v1/mlb/teams
- GET /v1/mlb/teams/:team/roster
- GET /v1/mlb/games (supports ?date=today)
- GET /v1/mlb/standings
- GET /v1/mlb/scoring/leaders
- GET /v1/mlb/scoring/categories

### NBA — 8 endpoints
- GET /v1/nba/players
- GET /v1/nba/players/:id
- GET /v1/nba/players/:id/stats (5 seasons, 127,909 rows)
- GET /v1/nba/teams
- GET /v1/nba/teams/:team/roster
- GET /v1/nba/games (supports ?date=today)
- GET /v1/nba/standings
- GET /v1/nba/confidence — validated NBA confidence scores (AUC 0.855, Pro Insights)

### NHL — 2 endpoints
- GET /v1/nhl/games
- GET /v1/nhl/standings

### CFB (College Football) — 3 endpoints
- GET /v1/cfb/games
- GET /v1/cfb/standings
- GET /v1/cfb/rankings

### Soccer — 2 endpoints, 6 leagues
- GET /v1/soccer/games?league=epl|mls|la_liga|bundesliga|serie_a|champions_league
- GET /v1/soccer/standings?league=epl|mls|la_liga|bundesliga|serie_a|champions_league

### Tennis — 1 endpoint
- GET /v1/tennis/matches?tour=atp|wta

### Golf — 2 endpoints
- GET /v1/golf/tournaments?tour=pga|lpga
- GET /v1/golf/leaderboard?tour=pga|lpga

### Intelligence (all tiers, no /v1 prefix) — 3 endpoints
- GET /intelligence/news?sport=nfl|mlb|nba — beat reporter signals, refreshed every 2 hours
- GET /intelligence/injuries?sport=nfl|mlb|nba — active injury designations
- GET /analytics/trends — historical performance trend analysis

### Pro Insights+ only — 7 endpoints
- GET /v1/players/search — cross-sport player search (NFL + MLB + NBA in one call)
- GET /v1/trending — trending players by sport
- GET /v1/articles/waiver — AI-generated waiver wire analysis
- GET /v1/nba/confidence — AUC-validated NBA model scores
- GET /v1/:sport/games/history — historical game logs with full stat lines
- GET /v1/:sport/players/:id/alpha — alpha metrics (consistency, momentum, opportunity ceiling)
- GET /v1/players/similar/:id — pgvector semantic player similarity

### Real-time (Pro Insights+) — 1 endpoint
- GET /v1/events/stream — Server-Sent Events push stream (30s heartbeat)
  Events: player.injured, game.score_updated, anomaly.detected

### Webhooks (Syndicate Alpha only) — 4 endpoints
- POST /daas/webhooks — register HTTPS endpoint with event subscriptions
- GET /daas/webhooks — list active webhooks
- DELETE /daas/webhooks/:id — deactivate
- GET /daas/webhooks/:id/deliveries — delivery log with retry history

### Account & Discovery — 3 endpoints
- GET /v1/sports — full sport/endpoint discovery map
- GET /daas/usage — quota, rate limit, and call count for this key
- GET /mcp + POST /mcp — MCP server (see below)

---

## Validated Machine Learning Models

PlayCaller ships 4 AUC-validated ML models in production. Every model has a published AUC, out-of-sample hit rate, and model registry entry. No hollow scores.

### NFL Confidence Model (Active, v1)
- Type: Logistic regression with Platt calibration
- Training: 20,585 NFL game observations
- AUC-ROC: 0.697
- Decile lift: 4.61x (top decile vs baseline)
- Output: Calibrated probability 16–58% (display range)
- Endpoint: /v1/feed (Pro Insights)

### NFL Heat / Opportunity Convergence Model (Active, v2)
- Type: Opportunity-trend detection
- AUC-ROC: 0.623
- Quartile lift: 25.6pp
- Signal: Converging snap_pct, target_share, and air_yards before market repricing
- Endpoint: /v1/feed (Pro Insights)

### MLB Pitcher Form Model (Active, v1)
- Type: Pitcher-centric logistic regression
- AUC-ROC: 0.671
- Signal: Pitch velocity trends, K-rate deviation, recent ERA
- Endpoint: /v1/feed for MLB (Pro Insights)

### NBA Confidence Model (Active, v3)
- Type: Usage-weighted ensemble
- AUC-ROC: 0.855
- Key signal: usage_vacuum (minutes spike when teammate sits out)
- Endpoint: GET /v1/nba/confidence (Pro Insights)

---

## Alpha Metrics (Pre-computed Weekly)

Available at GET /v1/:sport/players/:id/alpha for NFL, MLB, and NBA (Pro Insights+).
2,880 players seeded across all three sports as of July 2026.

- **Consistency Score (0–100):** Higher = more reliable floor. Computed as 100 × (1 − stddev/avg) of snap_pct or minutes_played over last 8 games. Use for identifying reliable starters.
- **Momentum Delta (signed float):** Avg fantasy points last 3 games minus avg games 4–6 back. Positive = trending up. Use for riding hot streaks or fading cold players.
- **Opportunity Ceiling (float):** 90th-percentile target_share or usage_rate from last 8 games. What the player can do in an optimal game. Use for GPP ceiling plays.

---

## Semantic Player Similarity (pgvector)

Available at GET /v1/players/similar/:id (Pro Insights+).

- **Architecture:** 8-dimensional stat embedding per player (avg_fp, usage, opportunity, rushing_yds, receiving_yds, consistency, momentum_norm, ceiling)
- **Index:** IVFFlat cosine similarity (lists=10) on 2,880 vectors
- **No LLM required:** Vectors are purely computed from historical_performance + alpha_metrics
- **Query:** "Find NFL players with the same production profile as Davante Adams" resolves in <5ms
- **Use case:** Trade target discovery, handcuff identification, DFS correlation stacking

---

## Player Identity Resolution

13,606 canonical player IDs (PlayCaller IDs, format: pc_nfl_XXXXXX) normalized across:
- ESPN player IDs
- Sleeper player IDs
- Yahoo player IDs
- NFL.com player IDs
- Rotowire player IDs
- BallDontLie player IDs

Endpoint: GET /v1/:sport/players/:id or GET /mcp → get_player_identity tool
Use: Import fantasy lineups from any platform, resolve to a single canonical ID, query intelligence against it.

---

## MCP Server (AI Agent Integration)

POST https://playcallerapp.com/mcp — JSON-RPC 2.0 protocol (Anthropic MCP spec 2024-11-05)
Auth: X-PlayCaller-Key header
Discovery: GET https://playcallerapp.com/mcp — returns tool list without auth

### 7 Production Tools

1. **get_injury_signals** — Active beat reporter injury and intelligence signals. Params: sport (nfl|mlb|nba|all), severity (high|medium|low|all), limit (max 50). Returns player, team, signal_type, severity, title, summary, source, updated_at.

2. **get_player_identity** — Resolve player name or platform ID to canonical PlayCaller identity with all platform mappings. Params: name (fuzzy), sport, platform, platform_id.

3. **get_anomaly_scores** — Players with anomalous usage/performance deviation from baseline. Anomaly score 0–100; >70 is meaningful. Params: sport, min_score, limit.

4. **get_prediction_markets** — Beat reporter signals tagged as prediction market props. Params: sport, limit.

5. **get_player_projections** — Trailing 10-game fantasy point average with active injury signal overlay. Params: player_name (required), sport (required), scoring.

6. **get_player_stats** — Per-game stat history. NFL: 2024 season. NBA: 5 seasons (2021–2025, 127k rows). Params: player_name (required), sport (required), season, limit.

7. **get_team_roster** — Active roster by team abbreviation. Params: team (required), sport (required), position, limit (max 100).

### Structured Error Self-Correction

All tool errors return machine-readable JSON for agent self-correction:
- Rate limit: { error_code: "RATE_LIMIT_EXCEEDED", limit_per_minute, retry_after_seconds: 60 }
- Quota exceeded: { error_code: "MONTHLY_QUOTA_EXCEEDED", quota, used, upgrade_url }
- Unknown tool: { error_code: -32602, available: [list of valid tool names] }

### Claude Desktop Config
```json
{
  "mcpServers": {
    "playcaller": {
      "command": "npx",
      "args": ["-y", "@playcaller/sdk", "mcp"],
      "env": { "PLAYCALLER_API_KEY": "pc_sbx_your_key_here" }
    }
  }
}
```

---

## Real-Time: SSE Event Stream

GET /v1/events/stream (Pro Insights+)
Persistent HTTP connection. 30-second heartbeat. Events pushed as they happen.

Events:
- player.injured — fires on every injury refresh cycle (every 4h); payload: { player, team, severity, signal_type, sport }
- game.score_updated — fires during live game pipeline; payload: { game_id, home_team, away_team, home_score, away_score, status }
- anomaly.detected — fires on anomaly refresh; payload: { player, team, anomaly_score, recommendation }

JavaScript:
```js
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)));
```

---

## Webhooks (Syndicate Alpha)

HMAC-SHA256 signed push delivery to any HTTPS endpoint.
Every delivery includes:
- X-PlayCaller-Signature: sha256=<hex> — for payload verification
- X-PlayCaller-Delivery-Id: UUID — for idempotent deduplication
- X-PlayCaller-Event: event type string

Retry logic: 3 attempts (immediate → 30s → 5min). Auto-deactivates + emails owner after 3 consecutive failures.

---

## SDKs

### TypeScript
```
npm install @playcaller/sdk
```
https://www.npmjs.com/package/@playcaller/sdk

```typescript
import { PlaycallerApiClient } from "@playcaller/sdk";
const client = new PlaycallerApiClient({ apiKey: "pc_sbx_your_key" });
const injuries = await client.intelligence.getIntelligenceInjuries({ sport: "nfl" });
const alpha = await client.v1.getAlpha({ sport: "nfl", id: "pc_nfl_4046533" });
```

### Python
```
pip install playcaller-sdk
```
https://pypi.org/project/playcaller-sdk/

```python
from playcaller import PlaycallerApi
client = PlaycallerApi(api_key="pc_sbx_your_key")
injuries = client.intelligence.get_intelligence_injuries(sport="nfl")
```

---

## Pricing

| Tier | Price | Daily Cap | Sports | ML / SSE / Vectors | Webhooks |
|------|-------|-----------|--------|--------------------|----------|
| Developer Sandbox | Free (14 days) | 200 req/day | Core data only | Blocked | No |
| Build | $99/mo | 2,000 req/day | Core data only | Blocked | No |
| Pro Insights | $499/mo | 20,000 req/day | All 46 endpoints | Included (rate-capped) | No |
| Syndicate Alpha | $1,499/mo | No cap | All 46 endpoints | Uncapped | Yes |

Free sandbox at https://playcallerapp.com/developer — no credit card, no sales call, API key in 60 seconds.

---

## Authentication

All endpoints: `X-PlayCaller-Key: pc_sbx_...` header
Key prefixes: pc_sbx_ (Sandbox), pc_bld_ (Build), pc_pri_ (Pro Insights), pc_syn_ (Syndicate Alpha)

Quickstart:
```bash
curl "https://playcallerapp.com/intelligence/injuries?sport=nfl&severity=high" \
  -H "X-PlayCaller-Key: YOUR_KEY"
```

---

## Key URLs

- Developer landing: https://playcallerapp.com/developer
- API docs: https://playcallerapp.com/developer/docs
- OpenAPI spec (JSON): https://playcallerapp.com/openapi.json
- OpenAPI spec (YAML): https://playcallerapp.com/docs/openapi.yaml
- RapidAPI listing: https://rapidapi.com/teoforfootbowl/api/playcaller-data-api
- Sitemap: https://playcallerapp.com/sitemap.xml
- MCP endpoint: https://playcallerapp.com/mcp

## Token-Efficient Data Surfaces

Markdown versions of all player, team, and waiver wire pages for token-efficient agent reads:
- /players/{slug}.md — player profile as clean markdown
- /teams/{slug}.md — team roster with status indicators
- /waiver-wire/{sport}/{year}/week-{N}.md — waiver wire article as markdown

Example: https://playcallerapp.com/players/patrick-mahomes.md