REST API
Public resource areas, request conventions, representative endpoints and error handling.
Conventions
The base is https://api.beatkhana.com/api. Protected calls use an OAuth bearer token. JSON is used for normal bodies; media uploads use multipart; token and revoke requests use form encoding. Encode user-provided path identifiers and follow the generated OpenAPI schema for query parameters.
Resource catalogue
| Area | Operations |
|---|---|
| OAuth and identity | OAuth exchanges, session validation, profiles and linked identities. |
| Tournaments | Discovery, details, settings, registration, permissions, visibility and timeline. |
| Teams | Creation, invitations, membership, registration and roster lifecycle. |
| Brackets and matches | Divisions, brackets, matches, generation, team placement and results. |
| Maps and pools | Suggestions, votes, comments, flairs, imports, publishing and archive. |
| Overlays and match flows | Overlay management, scene documents and match-flow operations. |
| TournamentAssistant | Live overlay state and authorised management-session state. |
| Media | Multipart uploads, listings, image delivery and deletion. |
| Streaming | Stream keys, assignments and authorised media-server validation. |
| Calendar and notices | Public calendar windows and site notices. |
| Badges and awards | Badge requests, nominations, votes and results. |
Representative endpoints
GET /api/tournaments
GET /api/tournaments/{identifier}
POST /api/tournaments
PATCH /api/tournaments/{identifier}
POST /api/tournaments/{identifier}/visibility/request
POST /api/tournaments/{identifier}/visibility/approve
POST /api/tournaments/{identifier}/visibility/reject
GET /api/oauth/authorize
POST /api/oauth/token
POST /api/oauth/revoke
GET /api/oauth/applications
POST /api/oauth/applications
GET /api/resources/pooling/pools
GET /api/resources/pooling/pools/{poolGuid}
GET /api/resources/pooling/maps
GET /api/resources/pooling/maps/{mapGuid}The authoritative operation list, parameters and schemas are published at api.beatkhana.com/docs.
Error handling
Check response.ok before parsing the success type. Preserve status and text for diagnostics; authorization failures can mean missing OAuth scope, global permission, tournament role, record ownership or an invalid lifecycle transition. Use 429 backoff when returned and never retry non-idempotent mutations blindly.
const response = await fetch(`https://api.beatkhana.com/api/resources/pooling/pools/${encodeURIComponent(poolGuid)}`, {
headers: { Authorization: `Bearer ${accessToken}` },
});
if (!response.ok) {
const detail = await response.text();
throw new Error(`BeatKhana ${response.status}: ${detail}`);
}
return response.json();