Docs/Guides/Quickstart

Quickstart

This page gets you from zero to a successful API call. We'll create a guest session, log in, fetch the player's profile, and submit a Lextris result. Pick whichever style fits your stack.

1. Pick your client

You have three options:

  • The TypeScript SDK (@katforge/api) — recommended for any JS/TS project. Handles auth refresh, storage, and error mapping.
  • Raw fetch — works in any language. You handle JWT lifetime yourself.
  • The interactive API Reference — try every endpoint in your browser.

The rest of this guide shows the SDK and curl side-by-side.

2. Get a token

Every endpoint that does anything interesting requires a JWT access token. The fastest way to get one is to create a guest session — no signup required:

TypeScript
import { KATforge, browserStorage } from '@katforge/api';

const katforge = new KATforge ({
   baseUrl: 'https://api.katforge.com',
   storage: browserStorage
});

const session = await katforge.auth.guest ();
console.log (session.player);   // { id: 42, name: 'Brave_Lion_42', is_guest: true }
console.log (session.access_token);
shell
curl -X POST https://api.katforge.com/v1/gateway/guest \
   -H 'Content-Type: application/json' \
   -d '{}'

You'll get back a TokenResponse with an access_token, a refresh_token (also set as a cookie), and a player object.

For a registered account, swap auth.guest() for auth.login(identifier, password).

3. Make your first authenticated request

The SDK keeps the access token in memory and attaches it automatically:

TypeScript
const me = await katforge.users.me ();
console.log (me);   // { id: 7, username: 'anders', email: '...', ... }
shell
curl https://api.katforge.com/v1/users/@me \
   -H "Authorization: Bearer $ACCESS_TOKEN"

4. Submit a game result

Let's submit a Lextris result. Game results are namespaced under /v1/games/{game}:

TypeScript
const result = await katforge.games.lextris.submitResult ({
   type: 'daily',
   score: 1500,
   level: 5,
   wordsFound: 12,
   blocksDropped: 45,
   timeTaken: '225.00',
   date: '2026-01-15',
   completed: true
});

console.log (`You're rank #${result.rank}`);
shell
curl -X POST https://api.katforge.com/v1/games/lextris/results \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   -H 'Content-Type: application/json' \
   -d '{
      "type": "daily",
      "score": 1500,
      "level": 5,
      "wordsFound": 12,
      "blocksDropped": 45,
      "timeTaken": "225.00",
      "date": "2026-01-15",
      "completed": true
   }'

5. Read the leaderboard

Leaderboards are paginated. The SDK exposes them as PaginatedResponse objects you can iterate, page through, or fully collect:

TypeScript
// Collect the top 50
const top = await katforge.games.lextris
   .leaderboard ({ mode: 'daily', limit: 50 })
   .all ();

// Or iterate every entry across all pages
for await (const entry of katforge.games.lextris.leaderboard ({ mode: 'daily' })) {
   console.log (`#${entry.rank} ${entry.display_name} — ${entry.score}`);
}

// Or just one page
const page = await katforge.games.lextris
   .leaderboard ({ mode: 'daily', page: 1, limit: 20 })
   .page ();

What's next

  • Authentication — full auth flows including OAuth and SSO
  • Realtime — subscribe to Stumper multiplayer over Mercure SSE
  • Errors — error shapes and recovery patterns
  • API Reference — every endpoint, schema, and try-it panel
  • SDK Reference — generated docs for every method in @katforge/api
Next →Authentication