Developer platform

Bring Ball Ranks data into your app or agent.

Read fantasy basketball and football rankings and projections through a versioned REST API or the read-only Ball Ranks MCP server.

REST · anonymous request
curl "https://ballranks.com/api/v1/rankings/season?sport=football&scoring_format=ppr"

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.

REST API

Versioned JSON endpoints for rankings and player projections.

View endpoints →

MCP server

A stateless Streamable HTTP server with four read-only tools.

View MCP setup →

Quick start

Make your first request

  1. 1

    Create an API key for higher limits, or start anonymously.

  2. 2

    Send the key as a Bearer token. Never put it in a URL or client-side source code.

  3. 3

    Choose sport=basketball or sport=football and call an endpoint.

REST · authenticated request
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_key

Model 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.

MethodPathReturns
GET/api/v1/rankings/weeklyWeekly football rankings by position
GET/api/v1/rankings/seasonSeason rankings for basketball or football
GET/api/v1/players/{player}/rankingsOne player’s season ranking
GET/api/v1/players/{player}/projectionsOne player’s season or weekly projection

Common query parameters

ParameterValuesNotes
sportbasketball · footballRequired except on the football-only weekly endpoint.
modelv0 · v1Defaults to v0. Model One uses v1 and requires Premium.
seasonSeason labelOptional. The currently published projection season is supported.
scoring_formatstandard · half_ppr · pprFootball only. Defaults to ppr.
week1–18Required for weekly rankings and weekly player projections.
positionQB · RB · WR · TE · K · DSTWeekly rankings only. Defaults to RB.
scopeseason · weeklyPlayer projections only. Defaults to season; weekly requires week.
limit · offsetIntegersList pagination. Limit defaults to 50 and cannot exceed 100.

Sport support

SportWeekly rankingsSeason rankingsSeason projectionWeekly projection
Basketball—SupportedSupported—
FootballSupportedSupportedSupportedSupported
Football · weekly rankings
curl "https://ballranks.com/api/v1/rankings/weekly?week=4&position=WR&scoring_format=ppr"
Basketball · player projection
curl "https://ballranks.com/api/v1/players/victor-wembanyama/projections?sport=basketball"

Downloads

API tools and discovery

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.

MCP · list available tools
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

ToolReturns
get_week_rankingsWeekly football rankings for one position and scoring format
get_season_rankingsSeason rankings for basketball or football
get_player_rankingsOne player’s season ranking by ID or slug
get_player_projectionsOne 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.

Install the Ball Ranks skill
npx skills add Ollynov/ball-ranks-skills --skill ball-ranks

The skill uses the same API key and plan limits as other clients.

Usage

Plans and rate limits

AccessPer minutePer dayModel access
Anonymous—50Model Zero
Free account880Model Zero
Premium601,000Model 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.

REST · error shape
{
  "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