ScoreForge

ScoreCommand

Capability

Public API

Your data. Your integrations. Real-time access.

ScoreForge exposes a public REST API for building custom integrations, external displays, or data exports. Every endpoint is authenticated with API keys, rate-limited per key, and returns structured JSON. For live scoring data, a real-time subscription query streams match updates with zero polling — the same mechanism that powers the Display app.

All Capabilities
01

Four REST endpoints

The API provides read access to your tournament data through four GET endpoints. List tournaments with optional status filtering, list brackets for a tournament, list matches with filters for status, round, and court, or get a single match with full scoring state including the complete tennis state object.

GET /api/public/tournaments — list tournaments, optional status filter (draft/active/completed/cancelled)

GET /api/public/brackets — list brackets for a tournament, sorted by display order

GET /api/public/matches — list matches with filters for status, round, court, and sort order

GET /api/public/match — single match with participant details and full tennisState

02

API key authentication

Generate API keys from the settings page. Each key follows the format sf_XXXXXXXX_YYYYYYYY with a display prefix for identification. Keys are SHA-256 hashed before storage — the full key is shown exactly once on creation. Pass it via the x-api-key header. Keys only access tournaments owned by the key's creator.

Key format: sf_ prefix + 8-char display prefix + 24-char random suffix

SHA-256 hashed before storage; full key shown once on creation

Authenticate via x-api-key header (or apiKey query param, deprecated)

Keys scoped to the owner's tournaments — no cross-user access

03

Per-key rate limiting

Every API key is rate-limited to 100 requests per 60-second window. Each response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so clients can pace themselves. Exceeding the limit returns a 429 response with the reset timestamp. Real-time subscriptions are exempt since they use persistent connections.

100 requests per 60-second sliding window per API key

Rate limit headers on every response: Limit, Remaining, Reset

429 Too Many Requests with ISO timestamp for retry

Real-time subscriptions bypass rate limiting (persistent connection)

04

Real-time match subscriptions

The watchMatch query provides a Convex reactive subscription for live match data. Instead of polling, clients establish a persistent connection and receive updates the instant a point is scored, a server changes, or a match completes. This is the same mechanism powering the Scoreboard Designer's live data binding.

Convex reactive query: subscribe once, receive updates instantly

Returns full match state including tennis scores, server, and tiebreak status

Used by the Display app's Rust Convex SDK for live scoreboards

No rate limiting on subscriptions — persistent connection model

05

Key management

Manage up to 10 API keys per account from the settings page. Generate keys with a custom name, revoke them to disable access immediately, rotate to get a new key while keeping the same record, or delete permanently. Each key tracks its creation date and last used timestamp for monitoring.

Up to 10 active API keys per user account

Generate, revoke (soft disable), rotate (new key material), or delete keys

Each key has a name, creation date, and last-used timestamp

CORS enabled with exposed rate limit headers for browser clients

Previous

Mobile Scoring

Ready to run your tournament?

ScoreForge gives your operations team the tools to manage brackets, score matches live, and broadcast results — all from one platform.

View All Capabilities