Introduction
BoardQ turns score data into a live, beautiful leaderboard you can put on any screen. Push results from your own app through the REST API, sync them from a tool you already use, or add them by hand - either way the board updates in real time and stays sharp on everything from a phone to an office TV.
This guide covers what BoardQ can do, the key concepts behind a result, the full API reference for reading and writing scores, and how to style a board with custom CSS.
Features
Create & Display Custom Scoreboards
BoardQ simplifies the process of creating and displaying scoreboards for any occasion. Whether it's for a sport competitions, classroom achievements, or events, our tool lets you choose a design and add scores remotely.
Live Updates
As scores change, BoardQ instantly refreshes, ensuring viewers always see the most recent results. Turn every score update into a moment of intrigue and celebration.
Multiple Screens
BoardQ seamlessly broadcasts scores in real-time across multiple screens, ensuring synchronized displays for all viewers, no matter where they're watching.
API Integration
Seamlessly display scores from diverse sources such as gaming platforms, sports tracking systems, and educational quizzes, ensuring real-time consistency no matter the application. Generate API key in leaderboard settings section.
QR Integration
Display QR code next to your leaderboard in order to navigate mobile users to your online activity or companies personal page. Generate QR code in leaderboard settings section.
Board insertion to your web page
Just with a few lines of code you can grab created leaderboard and add it to your personal or business web page. Find your board code snippet under created board settings.
Key Concepts
displayTitle
| title of the result which will be displayed in the screen. Usually it is a participant name or number.additionalInfo
| not visible info in the screen. Usually it is used write down a participant data like email or phone number. It is possible to see that data when you click on scoreboard result or when you export the data.imgUrl
| optional http(s) URL to an image, displayed as a circular avatar next to the place number on the scoreboard. Pass an empty string to clear an existing image. points
| for the points scoreboard you have to use points value. ms
| stands for milliseconds. ms value is used in time scoreboard. You have to send ms value and that ms will be transformed to targeted time value which is set in time scoreboard setting, for example if you want to display time scores in hours then: 7950000ms --> 2h 12min 30secapikey
| key which is needed to interact with BoardQ API. This key should be sended though headers.API
The BoardQ REST API lets your app push and read scores so they appear on a live leaderboard. Any language that can make an HTTP request works - there's no SDK to install. Authenticate each request with your API key in the apikey header.
Two kinds of API keys
Board API key — belongs to one leaderboard; lets you add, read, update and delete its scores (endpoints below). Account API key — belongs to your account; lets you create leaderboards programmatically.
Creating a leaderboard via API
Generate an account key in Settings → Developer API (Premium), then create boards from code. The response includes the new board's own API key, so you can push scores immediately.
POST /boards
Headers: apikey: ACCOUNT_KEY · Body: { "name": "My board" } (optional: scoreboardType POINTS | TIME | CUSTOM, isPublic, customUnit, prefix, description, results)
Seeding rows on create — pass results (up to 200) to create the board with players already on it: { "name": "Q3 race", "results": [{ "name": "Alice", "points": 120 }, { "name": "Bob", "points": 80 } ] }. Each row accepts name, points, ms, additionalInfo, imgUrl. You can also add rows any time later with Add new result below, using the apikey from the create response.
description is shown on the board automatically whenever it's set (under the title, above the rows) — omit it or send an empty string to show nothing. Plain text or HTML, up to 5000 characters.
article — optional long-form write-up displayed above the leaderboard, rendered like a web article. Plain text (blank line = new paragraph) or simple HTML (<h2>, <p>, <strong>…), up to 50,000 characters. Pair it with articleTitle — an optional headline (up to 160 characters) rendered above the article body. Both are also editable in the board's settings next to the description.
Returns { board: { shortId, name, url }, apikey } — apikey is the board's key for the score endpoints below. Plan limits match the app (Free 2, Premium 30 boards).
Accepted values
scoreboardType (how scores behave): POINTS · TIME · CUSTOM. For a custom score column (e.g. YEARS, MILLIONAIRES), just send customUnit (singular) — the type becomes CUSTOM automatically. CUSTOM without customUnit returns 400.
boardType (leaderboard kind): GENERIC · SALES · SUPPORT · EVENT · CLAUDE_TOKENS (Claude Code tokens race — players join with npx boardq join) · RANKING (visitors drag & drop the board's items into their own ranked top list)
Design — pass boardPreset together with its matching scoreboardTemplate:
SALES+SALES_THEME (goal progress) · SALES_PODIUM+SALES_PODIUM_THEME (top-5 podium) · WINNERS+WINNERS_THEME (top-3 spotlight) · SALES_CHART+SALES_CHART_THEME (bar chart) · SALES_BARS+SALES_BARS_THEME (horizontal bars) · SUPPORT_PODIUM+SUPPORT_PODIUM_THEME (pedestal) · BUBBLES+BUBBLES_THEME · ARCS+ARCS_THEME · CARDS+CARDS_THEME (profile cards) · STEPS+STEPS_THEME (3D steps) · GAUGES+GAUGES_THEME · MOSAIC+MOSAIC_THEME. Simple row themes (no preset needed): DEFAULT · DARK · WHITE_DENSE
background: BACKGROUND_DEFAULT · BACKGROUND_BLUE · BACKGROUND_GREEN · BACKGROUND_FIRE · BACKGROUND_HEARTH · BACKGROUND_JUPITER · BACKGROUND_RACE · BACKGROUND_VICE · BACKGROUND_GRAINY · BACKGROUND_MEMARIANI
sortDirection: DESC (highest first) · ASC (lowest first). Defaults by type: POINTS/CUSTOM → DESC, TIME → ASC.
Value formatting: prefix (shown before every value, e.g. $, max 16 chars) · postfix (shown after, e.g. pts).
TIME boards: timeStartUnit / timeEndUnit control the displayed range (defaults SEC→MIN). Units: MS · SEC · MIN · H · D · MON · YRS
podiumDesign (for SALES_PODIUM / WINNERS / SUPPORT_PODIUM / BUBBLES designs, default CLASSIC): e.g. NEON · GLASS · MIDNIGHT · RETRO · MINIMAL · GLOW · OCEAN · SUNSET · EMERALD · CRIMSON and more — the full gallery is shown in the app's design step. chartColor (for SALES_CHART / SALES_BARS / ARCS / CARDS / STEPS): any hex color, e.g. #1f5b69.
MCP server (use BoardQ from Claude)
BoardQ hosts a remote MCP (Model Context Protocol) server, so Claude can manage your leaderboards conversationally. On claude.ai (web & mobile), add it as a custom connector under Settings → Connectors:
https://bq-server.onrender.com/mcp?key=YOUR_ACCOUNT_KEY
In Claude Code: claude mcp add --transport http boardq "https://bq-server.onrender.com/mcp?key=YOUR_ACCOUNT_KEY" — or run it locally instead with npx -y boardq mcp --key YOUR_ACCOUNT_KEY.
Exposed tools: create_leaderboard (with optional seeded players) · get_standings · add_score · update_score · delete_score. The key works on every board your account owns; regenerate it in Settings → Developer API to revoke — the URL contains your key, so treat it like a password. Learn more on the MCP server page.
Generating a board API key
The score endpoints below use the board key (not the account key). You get one in either of two ways: it's returned by POST /boards when you create a board via API, or — for boards made in the app — open the board, go to its Settings → API, and click Generate API key. Premium feature. Keep keys secret - treat them like passwords and send them only from your backend.
A Premium account can have up to 2 scoreboards with an active API key. To free up a slot, remove the key from an existing board before generating a new one. Need more keys? Reach out through the contact page.
Base URL
All endpoints below are relative to this base URL.
https://bq-server.onrender.com/api
POST/result/:scoreboardId
Endpoint dedicated to add new result to the targeted time or points scoreboard.
URL:
:scoreboardId
(required)BODY:
displayTitle
(required)additionalInfo
imgUrl
- http(s) URL, shown as a circle next to the place number
points OR ms
(required)HEADERS:
apikey
(required)const url = 'https://bq-server.onrender.com/api/result/SCOREBOARD_ID';const apiKey = API_KEY
const data = {displayTitle: "John Doe",additionalInfo: "johndoe@example.com",imgUrl: "https://example.com/avatar.png",points: 120};
fetch(url, {method: 'POST',headers: {'Content-Type': 'application/json','apikey': apiKey},body: JSON.stringify(data)}).then(response => response.json()).then(data => console.log(data)).catch(error => console.error('Error:', error));
GET/results/:scoreboardId
Endpoint dedicated to get all results from targeted scoreboard.
URL:
:scoreboardId
(required)HEADERS:
apikey
(required)const url = 'https://bq-server.onrender.com/api/result/SCOREBOARD_ID';const apiKey = API_KEY
fetch(url, {method: 'GET',headers: {'Content-Type': 'application/json','apikey': apiKey}}).then(response => response.json()).then(data => console.log(data)).catch(error => console.error('Error:', error));
GET/results/:scoreboardId/:resultId
Endpoint dedicated to get specific result from targeted scoreboard.
URL:
:scoreboardId
(required):resultId
(required)HEADERS:
apikey
(required)const url = 'https://bq-server.onrender.com/api/result/SCOREBOARD_ID/RESULT_ID';const apiKey = API_KEY
fetch(url, {method: 'GET',headers: {'Content-Type': 'application/json','apikey': apiKey}}).then(response => response.json()).then(data => console.log(data)).catch(error => console.error('Error:', error));
PUT/result/:scoreboardId/:resultId
Endpoint dedicated to add new result to the targeted time or points scoreboard.
URL:
:scoreboardId
(required):resultId
(required)BODY:
displayTitle
additionalInfo
imgUrl
- http(s) URL; pass empty string to clear
points OR ms
HEADERS:
apikey
(required)const url = 'https://bq-server.onrender.com/api/result/SCOREBOARD_ID/RESULT_ID';const apiKey = API_KEY
const data = {displayTitle: "John Doe",additionalInfo: "johndoe@example.com",imgUrl: "https://example.com/avatar.png",points: 120};
fetch(url, {method: 'PUT',headers: {'Content-Type': 'application/json','apikey': apiKey},body: JSON.stringify(data)}).then(response => response.json()).then(data => console.log(data)).catch(error => console.error('Error:', error));
DELETE/results/:scoreboardId/:resultId
Endpoint dedicated to delete specific result from targeted scoreboard.
URL:
:scoreboardId
(required):resultId
(required)HEADERS:
apikey
(required)const url = 'https://bq-server.onrender.com/api/result/SCOREBOARD_ID/RESULT_ID'; const apiKey = API_KEY;
fetch(url, {method: 'DELETE',headers: {'Content-Type': 'application/json','apikey': apiKey}}).then(response => response.json()).then(data => console.log(data)).catch(error => console.error('Error:', error));