For developers

Build on the sports OS.

REST API, OpenAPI 3.0 spec, Server-Sent Events for live data, OAuth-friendly bearer auth, idempotent mutations, request-id correlation. Whatever you're wiring — fans, athletes, clubs, sponsors — there's an endpoint for it.

Open Swagger UI Download OpenAPI spec

Interactive API reference

Swagger UI — try every endpoint live with your token. Persists auth across reloads.

Open Swagger →

OpenAPI 3.0 spec

Machine-readable JSON. Drop into Postman, redoc, openapi-typescript, orval, etc.

Get the spec →

Architecture brief

How the platform fits together — request lifecycle, data ownership, realtime, phase plan.

Read on GitHub →

Error envelope spec

Every non-2xx is `{ error: { code, message, requestId, details? } }`. Branch on `code`.

Read the contract →

Core concepts

Six things to know before you start

Auth — bearer JWT

`POST /auth/sign-in` returns a 30-day JWT. Send `Authorization: Bearer <token>` on every authed call. OAuth flows route through `/auth/oauth-provision`.

Idempotency — Stripe-style

Mutations accept `Idempotency-Key: <uuid>`. Same key + same body replays the cached response; same key + different body returns 409. Keys live for 24h.

Pagination — cursor

List endpoints return `{ items, nextCursor }`. Pass `?cursor=<token>` for the next page. `nextCursor` is `null` at the end. Cursors are opaque.

Rate limits — sliding window

Throttler keyed by IP + (when authed) user id. Most endpoints 60 req/min; auth 5 req/min. 429 response carries `Retry-After`.

Realtime — Server-Sent Events

Watch parties, floating reactions, and live match events all stream via SSE. Use any compliant `EventSource`. Auto-reconnect via `Last-Event-ID`.

Correlation — x-request-id

Every response carries `x-request-id`. The same id appears in `error.requestId` on failures and on every Pino log line. Quote it to support for instant grep.

Quick start

Sign in, post a take, watch a match

# 1. Sign in
TOKEN=$(curl -s https://api.sportsplex.app/api/auth/sign-in \
  -H "content-type: application/json" \
  -d '{"email":"you@example.com","password":"…"}' \
  | jq -r '.accessToken')

# 2. Read your timeline
curl -s https://api.sportsplex.app/api/feed -H "authorization: Bearer $TOKEN" | jq

# 3. Post
curl -s https://api.sportsplex.app/api/feed \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"body":"That goal was unreal."}' | jq

# 4. Subscribe to live match events (SSE)
curl -N https://api.sportsplex.app/api/matches/fd:538140/events/stream

Found a bug? Want an SDK?

Email dev@sportsplex.app with the request id from the failing call (we log every one). For partnerships, integrations, or bulk-API access, drop a note and we'll set up a call.

dev@sportsplex.app Security disclosure