Overview
One data surface, two protocols
REST and MCP use the same rankings, projections, access rules, and request limits. Choose REST for direct application requests or MCP when an AI client should discover and call Ball Ranks tools.
Quick start
Make your first request
- 1
Create an API key for higher limits, or start anonymously.
- 2
Send the key as a Bearer token. Never put it in a URL or client-side source code.
- 3
Choose
sport=basketballorsport=footballand call an endpoint.
curl "https://ballranks.com/api/v1/rankings/season?sport=basketball" \
-H "Authorization: Bearer brk_your_key"Authentication
One key for REST and MCP
Create and revoke your key from the account page. Each account can have one active key. The full key is shown once; Ball Ranks stores only its hash.
Authorization header
Authorization: Bearer brk_your_keyModel Zero supports anonymous and Free access. Model One requires a key from an account with an active Premium membership.
REST API
Endpoints
All endpoints return JSON. The API contract version is 1; each response also includes the selected model and the model data version in meta.
Use the machine-readable OpenAPI 3.1 document to generate a client or import the API into a compatible tool.
| Method | Path | Returns |
|---|---|---|
| GET | /api/v1/rankings/weekly | Weekly football rankings by position |
| GET | /api/v1/rankings/season | Season rankings for basketball or football |
| GET | /api/v1/players/{player}/rankings | One player’s season ranking |
| GET | /api/v1/players/{player}/projections | One player’s season or weekly projection |
Common query parameters
| Parameter | Values | Notes |
|---|---|---|
| sport | basketball · football | Required except on the football-only weekly endpoint. |
| model | v0 · v1 | Defaults to v0. Model One uses v1 and requires Premium. |
| season | Season label | Optional. The currently published projection season is supported. |
| scoring_format | standard · half_ppr · ppr | Football only. Defaults to ppr. |
| week | 1–18 | Required for weekly rankings and weekly player projections. |
| position | QB · RB · WR · TE · K · DST | Weekly rankings only. Defaults to RB. |
| scope | season · weekly | Player projections only. Defaults to season; weekly requires week. |
| limit · offset | Integers | List pagination. Limit defaults to 50 and cannot exceed 100. |
Sport support
| Sport | Weekly rankings | Season rankings | Season projection | Weekly projection |
|---|---|---|---|---|
| Basketball | — | Supported | Supported | — |
| Football | Supported | Supported | Supported | Supported |
curl "https://ballranks.com/api/v1/rankings/weekly?week=4&position=WR&scoring_format=ppr"curl "https://ballranks.com/api/v1/players/victor-wembanyama/projections?sport=basketball"Downloads
API tools and discovery
OpenAPI 3.1
Endpoint schemas, response examples, and authentication for client generators and API tools.
Postman collection
Ready-to-run requests for both sports, including weekly football projections.
Import the collection into Postman. It starts with anonymous Model Zero requests. Choose a published football week before sending weekly requests. For account access, set the collection variable api_key, then select Bearer Token in the collection’s Authorization tab and use {{api_key}} as the token. Premium users can set model to v1.
Automated clients can discover REST and MCP through the API catalog. Plans and request limits are available as JSON.
MCP server
Connect an AI client
Connect a client that supports Streamable HTTP to https://ballranks.com/api/mcp. Use the same Bearer header as REST when you want account limits or Model One access. The server is stateless and every tool is read-only.
curl -X POST "https://ballranks.com/api/mcp" \
-H "Authorization: Bearer brk_your_key" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
--data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'Tools
| Tool | Returns |
|---|---|
| get_week_rankings | Weekly football rankings for one position and scoring format |
| get_season_rankings | Season rankings for basketball or football |
| get_player_rankings | One player’s season ranking by ID or slug |
| get_player_projections | One player’s season or supported weekly projection |
Tool arguments match the REST query parameters. JSON-RPC batches are not supported.
For agents that support skills, install the Ball Ranks skill to add API instructions and request examples.
npx skills add Ollynov/ball-ranks-skills --skill ball-ranksThe skill uses the same API key and plan limits as other clients.
Usage
Plans and rate limits
| Access | Per minute | Per day | Model access |
|---|---|---|---|
| Anonymous | — | 50 | Model Zero |
| Free account | 8 | 80 | Model Zero |
| Premium | 60 | 1,000 | Model Zero and Model One |
Data requests first pass a shared 60-request-per-minute IP abuse cap, followed by the access-level limits above. MCP handshake and discovery methods do not use a daily data allowance, but they have a separate 300-request-per-minute IP abuse cap. Limited requests return 429 with Retry-After and X-RateLimit-Remaining headers.
Anonymous access and Free accounts cost $0. Premium is $39.99 per year and includes Model One for both sports. REST and MCP data requests share your allowance; creating another key does not reset it. See Premium membership and the machine-readable plans and limits.
Errors
Handle errors consistently
REST errors use an HTTP status and a JSON body with a stable code. MCP preserves request-limit HTTP statuses in its JSON-RPC error response.
{
"apiVersion": "1",
"error": {
"code": "invalid_request",
"message": "week: week is required for weekly projections"
}
}400 · invalid_request
A field is missing, invalid, or unexpected.
401 · unauthorized
The API key is invalid or revoked.
403 · premium_required
Model One needs an active Premium account.
404 · not_found / unavailable
The player, published data, or requested model was not found.
422 · unsupported_combination
The sport, scope, or season combination is not supported.
429 · rate_limit_exceeded
The shared IP or per-minute limit was reached.
429 · registration_required
The anonymous daily limit was reached.
429 · premium_required
The Free account daily limit was reached.
503 · rate_limit_unavailable
The request limiter is temporarily unavailable.
503 · unavailable
Ball Ranks data is temporarily unavailable.
API changelog
Developer updates
Follow changes to endpoints, response fields, authentication, and request limits here. REST uses /api/v1 and reports apiVersion in every response. Use modelDataVersion, generatedAt, and updatedAt to track published data updates.
Request limits
- Anonymous REST and MCP access now allows 50 requests per day for each originating IP, up from 10.
Developer resources · API v1
- Postman requests for basketball and football rankings and player projections.
- OpenAPI response examples and retry header documentation.
- Machine-readable plans, request limits, and REST/MCP discovery.
Security
Report a vulnerability
Email help@ballranks.com with the affected URL, steps to reproduce the issue, and its impact. Use accounts you control when testing, and keep API keys and other people’s personal data out of your report.
Security tools can find the reporting contact in security.txt. For integration, account, or billing questions, use support.
Ready to build?
Create your API key.
One key works across the REST API and MCP server. Revoke or replace it from your account at any time.
Open developer access Get integration support