Skip to content

Endpoint Reference

Auth (/v1/auth)

Method Route Purpose
GET /login/{provider} Initiate OAuth PKCE (google, discord, steam)
GET /callback/{provider} OAuth redirect handler; issues one-time code
POST /exchange Exchange code for JWT + refresh token
POST /refresh Rotate refresh token
POST /logout Revoke refresh token
POST /register Email/password registration
POST /login/email Email/password login

Access tokens expire in 60 minutes. Refresh tokens last 30 days and rotate on use (replay attempts revoke the token family). Refresh tokens are stored as BCrypt hashes, never in plaintext.

Sessions (/v1/sessions, requires JWT)

Method Route Purpose
POST / Upload session summary (no raw telemetry)

Idempotent on (userId, clientSessionId). Creates Session + Lap rows, optionally enqueues a track processing job, and emits a session.uploaded outbox event.

Leaderboards (/v1/leaderboards)

Method Route Purpose
GET / Ranked lap times for a track (cached in Redis)
POST /submit Submit a lap for ranking

One entry per (Track, User) — new submission replaces if faster. Quality score ≥ 0.8 required. Emits leaderboard.submit outbox event for achievement checking.

AI Coach (/v1/ai, requires JWT)

Method Route Purpose
POST /insights One-shot coaching from analysis metrics
POST /chat Multi-turn conversational coaching

Uses claude-sonnet-4-6, max 1024 tokens. System prompt: "You are ApexLab Coach, an expert sim-racing performance analyst." Session context (track, lap times, insights, segment deltas) included with every call.

Other endpoints (all require JWT)

  • GET/POST /v1/feed — activity stream (session uploads, leaderboard submissions, achievements)
  • GET /v1/achievements — user achievements
  • GET /v1/achievements/catalog — all available achievements
  • GET /v1/tracks — distinct tracks with uploaded sessions
  • GET/PATCH /v1/profile — user profile (display name, avatar)
  • GET /health — liveness probe