Bring Ball Ranks data into your app or agent.

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.

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.

curl "https://ballranks.com/api/v1/rankings/season?sport=basketball" \
  -H "Authorization: Bearer brk_your_key"

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.

Model Zero supports anonymous and Free access. Model One requires a key from an account with an active Premium membership.

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.

Common query parameters

Sport support

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"

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 arguments match the REST query parameters. JSON-RPC batches are not supported.

Before these access-level limits, every request passes a shared 60-request-per-minute IP abuse cap. The limits above still apply. Limited requests return 429 with Retry-After and X-RateLimit-Remaining headers.

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"
  }
}