API Overview

Introduction to the ScoreSaber Reloaded REST API, including base URL, response formats, and error handling

Introduction

The ScoreSaber Reloaded API is a REST API built with Elysia that provides programmatic access to player profiles, scores, leaderboards, and statistics. The API uses OpenAPI specifications and is available at /swagger for interactive documentation.

Base URL

The API is available at:

https://ssr-api.fascinated.cc

For development environments:

http://localhost:8080

Response Format

The API supports multiple response formats based on the Accept header:

JSON (Default)

All endpoints return JSON by default:

curl https://ssr-api.fascinated.cc/player/76561198449412074

content-type · string

application/json

Devalue Format

For optimized data serialization, send the Accept: application/devalue header:

curl -H "Accept: application/devalue" https://ssr-api.fascinated.cc/player/76561198449412074

content-type · string

application/devalue

Error Handling

The API uses standard HTTP status codes and returns structured error responses.

Error Response Format

All errors follow this structure:

statusCode · number

HTTP status code (400, 404, 429, 500, etc.)

message · string

Human-readable error message describing what went wrong

timestamp · string

ISO 8601 timestamp when the error occurred

Common Status Codes

200 · Success

Request completed successfully

400 · Bad Request

Invalid request parameters or malformed request body

404 · Not Found

The requested resource (player, leaderboard, score) was not found

429 · Too Many Requests

Rate limit exceeded - slow down your requests

500 · Internal Server Error

An unexpected error occurred on the server

Example Error Response

{
  "statusCode": 404,
  "message": "Player \"12345\" not found",
  "timestamp": "2026-03-04T12:34:56.789Z"
}

Validation Errors

Validation errors (400 status) return an array of validation issues:

curl https://ssr-api.fascinated.cc/leaderboard/search?page=invalid

Response:

[
  {
    "type": "Query",
    "at": "page",
    "message": "Expected number",
    "expected": {
      "type": "number"
    }
  }
]

Rate Limits

The API implements rate limiting to ensure fair usage and system stability. When the rate limit is exceeded, the API returns a 429 Too Many Requests status code.

Rate limits are monitored and adjusted dynamically. The API tracks ScoreSaber’s rate limit headers (x-ratelimit-remaining) when proxying requests.

Rate Limit Response

{
  "statusCode": 429,
  "message": "rate-limited",
  "timestamp": "2026-03-04T12:34:56.789Z"
}

OpenAPI Documentation

Interactive API documentation is available at:

https://ssr-api.fascinated.cc/swagger

The Swagger UI provides:

• Complete endpoint listing with parameters
• Request/response schemas
• Try-it-out functionality
• Type definitions and examples

Health Check

Verify the API is operational:

curl https://ssr-api.fascinated.cc/health

Response:

OK

API Statistics

Get backend statistics:

curl https://ssr-api.fascinated.cc/statistics

Returns information about:

• Total players tracked
• Total scores stored
• Database statistics
• Cache metrics