API Overview

Base URL

All endpoints are served over HTTPS. Plain HTTP requests will be redirected.

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header. See the Authentication docs for details on key types and generation.

# v1 API (developer keys)
curl -H "Authorization: Bearer rkly_your_key_here" \
  https://rankly.gg/api/v1/leaderboard

# Ingest endpoint (server API key)
curl -H "Authorization: Bearer RNKLY-XXXX-XXXX-XXXX-XXXX" \
  https://rankly.gg/api/ingest

Rate Limits

API requests are limited to 100 requests per minute per API key using a sliding window. Rate limit information is included in response headers.

Exceeding the limit returns a 429 response with a retry_after_ms field indicating when to retry.

Response Format

All responses are JSON. Successful responses wrap data in a data field alongside a meta object. List endpoints include a pagination object. Error responses include an error field with a human-readable message.

// Success (list)
{
  "data": [ { ... }, { ... } ],
  "meta": { "serverId": "..." },
  "pagination": { "page": 1, "perPage": 25, "total": 384 }
}

// Success (single object)
{
  "data": { ... },
  "meta": { "serverId": "..." }
}

// Error
{
  "error": "Invalid API key"
}