Documentation

Overview

A multi-game leaderboard service you can stand up in minutes. This page covers the concepts and the quick start; the guides go deeper.

The service stores scores in TursoDB and exposes a small JSON API. Games authenticate with a per-game bearer key. There are no player accounts: the game is trusted to report scores for the players it knows about.

Core concepts

Game + API key

Each game you register gets a unique API key. The key is the game's identity and its permission — it can only touch that game's data.

Leaderboards

A game owns many boards, addressed by a slug like classic or speedrun. Boards are sorted descending (higher wins) or ascending (lower wins).

Scores

Players submit scores with an id, optional name, and optional metadata. Their rank always reflects their best score.

A request with game A's key can never read or write game B's boards — asking for another game's board returns 404 rather than leaking its existence.

Quick start

1. Create the database

Create a Turso database and note its URL and an auth token. Skip this if you just want to try things locally — a file: URL works too.

terminal

# Create a Turso database and grab its URL + token.
turso db create leaderboard
turso db show leaderboard --url      # libsql://...
turso db tokens create leaderboard   # auth token

2. Configure the environment

Copy the example env file and fill in your credentials.

.env

TURSO_DATABASE_URL=libsql://your-db.turso.io
TURSO_AUTH_TOKEN=your-token

For local development without Turso:

.env

# Or develop locally against a plain file.
TURSO_DATABASE_URL=file:leaderboard.db

3. Apply the schema and create a game

This creates the tables, registers a game, and prints its API key exactly once. Store it somewhere safe.

terminal

npm install
npm run db:init
npm run admin game:create "Space Blaster"
npm run dev

4. Make a request

The API key is the only credential. Send it as a bearer token on every call.

GET/api/leaderboards

terminal

curl -H "Authorization: Bearer lgb_..." \
  http://localhost:3000/api/leaderboards

Deploy to Vercel

Push the repository to GitHub and import it into Vercel. Add TURSO_DATABASE_URL and TURSO_AUTH_TOKEN as environment variables, then deploy. Run the admin CLI from your machine pointing at the same Turso database to create games and boards.

Next steps

REST API guide

Every endpoint, parameter, and response shape, with copy-paste examples.

Open guide

Godot addon guide

Install the addon and call it from GDScript in a few lines.

Open guide

Both guides assume the API is deployed and you have a game key. See the quick start if you need one.