Content backend for web games, organised in modules:
Outside the modules, Analytics shows everything the project serves to its games.
Base URL: https://games-backstages.com — Web interface: / (account required) — This page: /docs
One call gives the whole organisation of a project — for a human or an AI agent coordinating its management:
curl -H "Authorization: Bearer $KEY" "https://games-backstages.com/api/projects/my-game/context?format=text"
GET /api/projects/{project}/context (JSON) or ?format=text (indented tree): the module tree in menu
order (nodes and their content), and for each module what it holds — Constants: categories › groups / Rules (with their
versions) › constants (type, enum options with their GUIDs, helper source); Images: folders (image count); System Actions: actions (with their parameters);
Player accounts: client id, redirect URIs, player count, enabled sub-modules, activity events; Leaderboard: kind and entry
count — plus the project's image tags. Every item with its GUID and name. No values and no files: a game reads values with
GET /api/projects/{project}/values and images with the index /p/{project}/images.json.
[a-z0-9][a-z0-9-]{1,39}). Owned by an account.i + 9 base-36
characters, folders f…, tags t…, modules m… (older ones p…), categories c…,
constants k…, enum options o…, players u…, activity events e…. A leaderboard and an
OAuth client use the GUID of their module. Renaming or reorganising
in Backstages never breaks a game.all contains the whole project.bomb
([A-Za-z0-9][A-Za-z0-9_-]* segments separated by /, unique in the folder) — display and upload only,
not an address. Replacing an image's file keeps its GUID.| tier | scale | max side | quality AVIF / WebP |
|---|---|---|---|
high | 100 % | 4096 px | 60 / 85 |
mid | 50 % | 2048 px | 55 / 80 |
low | 35 % | 1024 px | 45 / 70 |
CORS open (Access-Control-Allow-Origin: *): usable directly as WebGL textures.
| Route | Response |
|---|---|
GET /p/{project}/images.json | Project index (see below). Cache-Control: no-cache. |
GET /p/{project}/{id}.{hash}.{tier}.{format} | One variant of image id (format = avif | webp). Immutable, cached 1 year. |
GET /p/{project}/_bundles/{folder}.{hash}.{tier}.{format}.zip | All images of a folder (its GUID, or all) in one zip (uncompressed, entries {id}.{format}). Immutable. |
GET /i/{project}/{id}?tier={tier}&format={avif|webp|auto} | 302 to the variant. Defaults: mid, auto (AVIF if the Accept header allows it). Stable URL for an <img>. |
GET /sdk/backstages.js | SDK (ES module), types: /sdk/backstages.d.ts. |
{
"project": "shardball",
"updatedAt": 1790409039586,
"base": "/p/shardball/",
"pattern": "{id}.{hash}.{tier}.{format}",
"bundlePattern": "_bundles/{id}.{hash}.{tier}.{format}.zip",
"tiers": { "high": { "scale": 1, "maxSide": 4096, "webp": 85, "avif": 60 }, "mid": { … }, "low": { … } },
"formats": ["avif", "webp"],
"images": {
"i4k2m9x0qa": {
"name": "bomb", "folder": "f8r1c7w3zd", "tags": ["t0p5n2b8ke"],
"hash": "250ce049cf", "w": 1254, "h": 1254, "bytes": 1172804,
"variants": { "high": { "w": 1254, "h": 1254, "avif": 39170, "webp": 73536 }, "mid": { … }, "low": { … } }
}
},
"folders": {
"f8r1c7w3zd": { "name": "bonus", "module": "mk3w0q8v1b", "images": ["i4k2m9x0qa", "…"],
"bundle": { "hash": "dd73691661", "bytes": { "mid": { "avif": 87042, "webp": 163084 }, … } } }
},
"all": { "hash": "…", "bytes": { … } },
"tags": { "t0p5n2b8ke": { "name": "Bonus", "color": "#e63946" } }
}
Keys are GUIDs; name (the path after the folder), folder and tag names are for display. bundle is
null for an empty folder; a folder's module is the Images module that shows it (organisation only). Variant URL: base + pattern; bundle URL: base + bundlePattern
(id = folder GUID or all). bytes = size in bytes; w/h in pixels.
Each project has an API key, visible and regenerable in the web interface (project page). Header:
Authorization: Bearer {key}. Regenerating the key revokes the old one immediately.
| Route | Effect | Response |
|---|---|---|
GET /api/projects/{project} | Reads the index. | 200 index |
POST /api/projects/{project}/foldersbody {name, module?} | Creates a folder (free name, 1–60 characters) in that Images module (default: the first one). | 201 {folder: {id, name, module}} |
PUT /api/projects/{project}/images?folder={folderId}&name={name}body = raw image file | Upload into a folder: creates the image (new GUID) or replaces the one of that name in the folder (same GUID). Computes all variants and bundles (a few seconds). PNG, JPEG, WebP, AVIF, TIFF, GIF; 50 MB max. | 201 {changed: true, image}200 {changed: false, image} if identical |
GET /api/projects/{project}/images/{id} | Downloads the original file (private). | 200 image |
PUT /api/projects/{project}/images/{id}body = raw image file | Replaces the image's file (same GUID). | as above · 404 unknown |
POST /api/projects/{project}/images/{id}?… | Edits the original in one pass, then re-processes once. Applied in this order:
1. op= comma-separated, in order: trim (crop to visible pixels, else to the uniform border),
center (center the subject in its transparent frame, same size), rotr/rotl (90° right/left),
flop/flip (horizontal/vertical mirror);
2. angle: free rotation, −45 to 45° (clockwise if positive), bilinear. fit=crop (default): cropped to the largest rectangle with the image's aspect ratio (no empty corners); fit=adapt: the whole image stays visible (frame enlarged, transparent corners, then tightened to visible pixels);
3. crop=left,top,right,bottom: manual crop, margins removed as fractions (0–1) of the image at this stage;
4. scale: downscale factor, 0.01–1, aspect ratio kept (area averaging, alpha-weighted);
5. color: saturation, contrast, brightness (multipliers 0–3, 1 = unchanged), hue (−180 to 180°).
Example: ?op=trim,rotr&angle=-7.5&scale=0.5&hue=30. The math is public in /pixels.js. | 200 {changed, image} |
PATCH /api/projects/{project}/images/{id}body {name} | Renames the image in its folder (display only: GUID, files and bundles do not change). | 200 {image} · 409 name taken in the folder |
DELETE /api/projects/{project}/images/{id} | Deletes the image. | 204 |
PATCH /api/projects/{project}/folders/{id}body {name?, module?} | Renames the folder and/or moves it to another Images module (display only: GUIDs, files and bundles do not change). | 200 {folder} |
DELETE /api/projects/{project}/folders/{id} | Deletes the folder and every image in it. | 200 {deleted: n} |
GET /api/projects/{project}/tags | The project's tags, in order. | 200 {tags: [{id, name, color, count}]} |
POST /api/projects/{project}/tagsbody {name, color} | Creates a tag. Name: 1–40 characters (letters, digits, spaces, _ . -), unique; color #rrggbb. | 201 {id, tags} · 409 name taken |
PATCH /api/projects/{project}/tags/{id}body {name?, color?} | Renames and/or recolors it (its GUID does not change). | 200 {tags} |
DELETE /api/projects/{project}/tags/{id} | Deletes the tag and removes it from its images (the images stay). | 200 {tags} |
POST /api/projects/{project}/tags/{id}/imagesbody {images: [GUID…]} | Adds the tag to these images (all must exist). | 200 {tags} |
DELETE /api/projects/{project}/tags/{id}/images/{GUID} | Removes the tag from that image. | 200 {tags} |
image = {id, name, hash, ext, w, h, bytes, variants, updatedAt} (folder = folder GUID, name = name in the folder).
curl -X PUT -H "Authorization: Bearer $KEY" --data-binary @bomb.png \ "https://games-backstages.com/api/projects/my-game/images?folder=f8r1c7w3zd&name=bomb"
JSON body {"error": "message"}. 400 invalid name or parameter · 401 missing or invalid key ·
404 unknown image, folder or project · 413 file too large · 415 unsupported format.
A project's menu is a tree of modules, each with a permanent id (m + 9 base-36 characters; older ones
p…), a type, a free name and a parent: images (folders of the project's images),
constants (one configuration: categories, constants, Rules), servercall (System Actions: a set of game actions),
players (the OAuth client of the game's player accounts — one per project, its name is the project's),
leaderboard (one board) and node — a plain folder that holds other modules (nodes can be nested). parent is the id of a node, or
null at the root. A project can have several images modules: each shows its own folders, but there is
still one resource pack per project (one images.json, tags shared).
Modules can be added, renamed, moved and deleted (with their content; an Images module only when it has no folder left;
deleting a node moves its modules up to its place). A configuration is addressed by the id of its Constants module:
…/configs/{moduleId}/… — moving it in the menu never changes that.
| Route | Body | Effect |
|---|---|---|
GET /api/projects/{project}/modules | {modules: [{id, type, name, parent, ref}]}; siblings are listed in menu order. | |
POST /api/projects/{project}/modules | {type, name?, parent?, kind?} | Creates a module (a Constants module gets an empty configuration; a Leaderboard takes kind score (default) or time). 201 {modules, id}, plus secret for a Player accounts module (shown once). |
PATCH /api/projects/{project}/modules/{id} | {name?, parent?, before?} | Renames it; parent: put it in that node (null = root; not into itself or its own content); before: place it before that module (null = last). |
DELETE /api/projects/{project}/modules/{id} | Deletes it with its content (its configuration, its actions); a node's modules move up to its parent. |
Each Constants module of a project holds one configuration: a schema — categories, nested groups and typed fields — owned by Games Backstages, and values, which the game's server reads through the API with the project's API key (configurations are private: never published as public files). Everything can be managed in the web interface or through the API below; both edit the same data. Games Backstages only distributes: when there are several versions, the game chooses which one it uses.
Everything is addressed by GUID — there are no keys. A configuration by the GUID of its module, a category, a group, a Rules or a constant by its own GUID. Names are only labels: rename, move or reorganise anything, the game (which reads by GUID) never notices.
c + 9 base-36 characters for a category,
k + 9 for a field (e.g. km9dnk2sz5). Shown as GUID: … in the interface (click to copy).{id, label, sep?}; sep: optional heading shown above it in the menu.{id, parent, category, label, type, …}. parent: the
GUID of its category, or of the group / Rules that contains it; category (read-only): the GUID of its category.
| type | properties | value |
|---|---|---|
number | min < max, step > 0; integer: true → whole numbers (bounds and step must be integers) | clamped into [min, max], rounded if integer |
text | maxLength 1–5000 (default 200) | truncated to maxLength |
boolean | — | true / false |
enum | options: ordered list of {id, label} (1–100; label 80 max., unique). Send {label} or a plain text for a new option: it gets a GUID o…; renaming or reordering keeps it | the GUID of one option (anything else → the first option) |
tag | — | the GUID of one of the project's image tags, or "" (none) |
image | — | the GUID of one of the project's images (i…), or "" (none). Resolve it with the public index /p/{project}/images.json (or the SDK); replacing the image's file keeps its GUID. |
color | — | "#rrggbb", stored lowercase ("#rgb" is expanded; anything else → the starting value, black) |
sum (helper) | of: GUID of a number or boolean constant (not an array) inside a Rules; the helper itself lives outside any Rules | computed, read-only: the sum of that constant over all the Rules' versions (booleans: how many are checked); recomputed on every change. Deleting the source deletes the helper. |
group | — | none: a group only contains other fields (groups, Rules, constants) |
rules | versions: ordered list of names (default ["Default"]) | none: a versionable group — every constant inside it (at any depth) has one value per version |
array: true on a number, text or boolean field makes its value a list of
that type (up to 1000 elements, each coerced like a single value; starts empty). Turning it off keeps the first element; turning it on
wraps the current value. Optional default: starting value (else min, empty text, false).rules): a group of constants with named versions (e.g. Default,
Survival), all published (500 versions max.). A version name: letters, digits, spaces, _ . - (40 max.). No Rules inside a Rules.
A new version copies the values of an existing one. A constant moved into a Rules takes its value in every version;
moved out, it keeps the value of the first version.| Route | Response |
|---|---|
GET /api/projects/{project}/valuesheader Authorization: Bearer {key} | What a game reads: the values of all the project's Constants modules together,
{updatedAt, common, rules, versions}, by GUID — moving a category to another Constants module changes nothing for the game.
versions: {rulesId: [version names in order]} (a JSON object does not keep that order). |
GET /api/projects/{project}/configs/{moduleId}/valuesheader Authorization: Bearer {key} | The same for one module only: {config, updatedAt, common, rules, versions}, by GUID only. common: constants outside any Rules, and helpers. rules: {rulesId: {version: values}}, every version. Groups have no value. Cache-Control: no-store. Read it from your game's server, never from a browser (the key gives full access to the project). |
{
"config": "game", "updatedAt": 1790409039586,
"common": { "k6bie85sc5": 10, "k0qfst2p4r": "Hold on" },
"rules": { "kohgfkg0rl": { "Default": { "kc2mvwnh83": 40 }, "Survival": { "kc2mvwnh83": 60 } } }
}
// On your game server (the key stays there):
const cfg = await fetch('https://games-backstages.com/api/projects/my-game/configs/pefgk1h056/values', {
headers: { authorization: `Bearer ${process.env.BACKSTAGES_KEY}` },
}).then((r) => r.json());
const moveSpeed = cfg.common['k6bie85sc5']; // a constant, by its GUID
const game = cfg.rules['kohgfkg0rl'][mode === 'survival' ? 'Survival' : 'Default']; // the game picks the version
const ballMax = game['kc2mvwnh83'];
Same authentication as images: Authorization: Bearer {key}. Bodies are JSON. Unless stated otherwise, a
successful change returns the whole updated configuration {name, schema, common, rules} plus id or
deleted. {config} below = the GUID of the Constants module (see Modules).
| Route | Body | Effect |
|---|---|---|
| Configuration | ||
GET /api/projects/{project}/configs/{config} | The whole configuration. | |
| Categories | ||
POST …/configs/{config}/categories | {label, before?} | Creates a category (before: GUID of the category to insert it before; default last). 201 + its id. |
PATCH …/configs/{config}/categories/{id} | {label?, before?} | Renames it; before: move it before that category, null = last. |
DELETE …/configs/{config}/categories/{id} | Deletes the category and everything inside. deleted = number of fields removed. | |
| Fields (constants, groups, Rules, helpers) | ||
GET …/configs/{config}/fields/{id} | {field, value} (constant outside Rules), {field, rules, values: {version: value}} (constant in a Rules; rules = its GUID), {field} (group or Rules; a Rules' field.versions lists its versions). | |
POST …/configs/{config}/fields | {parent, label, type, min, max, step, integer?, maxLength?, options?, array?, of?, versions?, before?, value?, values?} | Creates a field in parent (GUID of a category, group or Rules). before: GUID of a sibling to insert it before (default: last in its parent). value: its value — in a Rules, the same for every version; values {version: value}: per version. 201 + its id. |
PATCH …/configs/{config}/fields/{id} | any of {label, parent, before, type, min, max, step, integer, maxLength, options, array, of, value, values} | Updates it. parent: moves it (a group or a Rules with its whole content; not into itself). before: GUID of a sibling to move it before; null = last in its parent. A constant stays a constant, a group a group, a Rules a Rules, a helper a helper. Values are re-clamped to new bounds. |
DELETE …/configs/{config}/fields/{id} | Deletes it (a group or a Rules with its content). deleted = number of fields removed. | |
Versions of a Rules ({rules} = the Rules' GUID; version names URL-encoded) | ||
POST …/configs/{config}/rules/{rules}/versions | {name, from?} | Creates a version, copying the values of from (default: the first version). 201. |
PATCH …/configs/{config}/rules/{rules}/versions/{version} | {name?, before?} | Renames it; before: move it before that version, null = last. |
DELETE …/configs/{config}/rules/{rules}/versions/{version} | Deletes it and its values (not the last one). | |
PATCH …/configs/{config}/rules/{rules}/versions/{version}/values | {id: value, …} | Sets values of constants of this Rules, for this version. |
| Values and bulk operations | ||
PATCH …/configs/{config}/common | {id: value, …} | Sets constants outside any Rules. |
POST …/configs/{config}/categories/{id}/move | {module} | Moves the category, with everything in it (groups, Rules and their versions, constants, helpers) and its values, to another Constants module. GUIDs do not change; a helper and its source must move together. |
PUT …/configs/{config}/values | {common?: {id: value}, rules?: {rulesId: {version: {id: value}}}} | Bulk import: sets the given values (the others are kept). |
PUT …/configs/{config}/schema | {groups: [category…], fields: [field…]} | Replaces the whole schema at once. Send existing categories and fields with their id: values follow them. Items without id are new and get one. Fields left out are deleted. |
C=https://games-backstages.com/api/projects/my-game/configs/pefgk1h056 # the GUID of the Constants module
api() { curl -s -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" "$@"; }
HERO=$(api -X POST $C/categories -d '{"label": "Hero"}' | jq -r .id)
SHIELD=$(api -X POST $C/fields -d "{\"parent\": \"$HERO\", \"label\": \"Shield\", \"type\": \"group\"}" | jq -r .id)
RADIUS=$(api -X POST $C/fields -d "{\"parent\": \"$SHIELD\", \"label\": \"Radius\", \"type\": \"number\", \"min\": 1, \"max\": 8, \"step\": 0.25, \"value\": 3.75}" | jq -r .id)
api -X PATCH $C/common -d "{\"$RADIUS\": 4}" # change the value
api -X PATCH $C/fields/$RADIUS -d "{\"parent\": \"$HERO\"}" # move it out of the group: same GUID, the game sees nothing
api -X DELETE $C/fields/$SHIELD # delete the group (and its content)
JSON body {"error": "message"}. 400 invalid body: unknown or invalid GUID, unknown parent, group moved
into itself, Rules inside a Rules, type change between constant, group, Rules and helper, min ≥ max, value of a Rules
constant without a version, last version deleted… · 401 missing or invalid key · 404 unknown
configuration, category, field, Rules or version. A rejected request changes nothing.
Describe actions your game server exposes (e.g. "reset every account") and trigger them from the web interface
(module Actions Système, type servercall) or the API. Each action has its own key. When triggered, Games Backstages sends
POST {url} with headers Authorization: Bearer {action key} and X-Backstages-Action: {id},
and a JSON body {action, params}, without following redirects, 30 s timeout. Your endpoint must run the action only if the key matches (compare in constant time);
the status and the beginning of the response (2000 characters) are recorded and shown. URL: https:// only
(http:// allowed for localhost/127.0.0.1, for local tests).
Parameters: an action can require up to 10 parameters, each {id, label, type} with a permanent GUID
(q + 9 characters; renaming keeps it) and a type: text (non-empty, 2000 characters max.),
integer, decimal, or player (the GUID u… of a player of the project's
Player accounts module). They are all required: the interface asks for them on click (then asks for confirmation if the action
needs it), and the game receives them by GUID: {"action": "a…", "params": {"q…": "cheating", "q…": 7, "q…": "u…"}}
(params is {} for an action without parameters). A missing or invalid value is refused
(400) and the game is not called.
| Route | Body | Effect |
|---|---|---|
GET /api/projects/{project}/servercalls?module={moduleId} | {calls: [{id, label, description, url, confirm, params, lastAt, lastStatus, lastBody}]} of that module (keys never listed). | |
POST /api/projects/{project}/servercalls | {module, label, description?, url, confirm?, params?} | Creates an action (confirm, default true: the interface asks before triggering). 201 {calls, id, key}. |
PATCH /api/projects/{project}/servercalls/{id} | any of {label, description, url, confirm, params} | Updates it. params replaces the whole list: send existing ones with their id to keep their GUID; those without get a new one. |
DELETE /api/projects/{project}/servercalls/{id} | Deletes it. | |
GET · POST /api/projects/{project}/servercalls/{id}/key | Shows · regenerates its key (project owner, signed in). After regenerating, give the new key to the game. | |
POST /api/projects/{project}/servercalls/{id}/run | {params: {paramId: value}} (when the action has parameters) | Triggers it: {at, status, body} (status 0: the game did not answer). |
// On the game server:
app.post('/action/ban', (req, res) => {
const ok = timingSafeEqual(req.headers.authorization, `Bearer ${process.env.BAN_KEY}`);
if (!ok) return res.status(401).end();
const { params } = req.body; // by GUID, copied from the action's detail
ban(params['qpojp02do9'], params['qc3chys45n']); // player GUID (u…), days (integer)
res.json({ ok: true });
});
import { createAssets } from 'https://games-backstages.com/sdk/backstages.js';
const assets = createAssets({ base: 'https://games-backstages.com', project: 'my-game' });
await assets.ready; // reads the index (images.json)
await assets.loadFolder('f8r1c7w3zd'); // one zip for the whole folder (GUID); also loadAll(), loadImage(id)
const ids = assets.folderImages('f8r1c7w3zd'); // the folder's image GUIDs
const bmp = assets.get('i4k2m9x0qa'); // ImageBitmap (e.g. PIXI.Texture.from(bmp))
const url = assets.url('i4k2m9x0qa'); // URL of the chosen variant
Copy GUIDs from the web interface (chip under each image and next to each folder).
Options: tier (auto | low | mid | high), format (auto | avif | webp), decode (default createImageBitmap).
With auto, the tier depends on the screen (size × pixel density), device memory and data-saver mode,
then drops one step if the measured throughput is low; the format is AVIF if the browser can decode it.
A Player accounts module (one per project) lets a game's players sign in with their Games Backstages account —
one email and password for every game that uses it. Games Backstages handles sign-up, email verification, password reset and
the standard emails; the game receives a permanent player GUID (u…) and the email, and keeps its own session and
data. Player accounts are separate from creator accounts. The client id is the module's GUID and the name shown to players is
the project's. Its secret and allowed redirect URIs are set under Configuration de l’OAuth. Optional sub-modules,
all off by default, add features: mails — the game's own welcome email, sent on a player's first sign-in to that game
({jeu} and {email} are replaced); activity — an activity feed: declare named events in
Backstages (each gets a GUID e…, renaming keeps it), and the game's server reports them for a player.
Only declared events of players who joined the game are accepted: a player cannot post activity themselves.
Flow: authorization code with PKCE (S256). The sign-in page can be opened in a popup window over the game
(the callback page then notifies the game with postMessage and closes) or by a plain redirect.
| Step | Request | Result |
|---|---|---|
| 1. Send the player | GET /oauth/authorize?response_type=code&client_id={moduleId}&redirect_uri={uri}&state={random}&code_challenge={S256(verifier)}&code_challenge_method=S256 | Games Backstages sign-in page, in the game's name. Unknown client or redirect URI: error page, no redirect. |
| 2. Back to the game | {uri}?code=…&state=… | Check state. The code is single-use, valid 5 minutes. Errors come back as ?error=…&state=…. |
| 3. Exchange (game server only) | POST /oauth/token (JSON or form): grant_type=authorization_code, code, redirect_uri, client_id, client_secret, code_verifier | {token_type, player: {id, email, email_verified}, first_login} · 401 invalid_client · 400 invalid_grant |
| Activity (game server) | POST /oauth/activity, header Authorization: Bearer {client secret}, {client_id, event: GUID, player: GUID} | 201 · 401 bad secret · 403 sub-module off · 404 unknown event or player not in the game. Also counts as the player being seen. |
| Delete (game server, when the player asks) | POST /oauth/delete, header Authorization: Bearer {client secret}, {client_id, player: GUID} | {deleted: "game"} the player left this game (link and activity removed) · {deleted: "account"} also the account itself (email + password), when no other game uses it · 404 not a player of this game. Games Backstages has no player space: each game offers account deletion to its players. |
| 4. Presence (game server, every minute) | POST /oauth/presence {client_id, client_secret, players: [GUID…]} — the players connected right now | {online}. Feeds last sign-in, the online now count and the online curve (sampled every 5 minutes, kept 90 days). A player not reported for 2.5 minutes counts as offline. |
Module (creator session or project key): GET|PATCH /api/projects/{project}/players/{moduleId} {redirects?, features? (e.g. ["mails"]), welcomeSubject?, welcomeBody?} ·
sub-modules: PUT|DELETE …/players/{moduleId}/features/{mails|activity} (enable / disable) ·
secret: GET|POST …/players/{moduleId}/secret (project owner, POST = new secret; also returned once when the module is created) ·
GET …/players/{moduleId}/stats?range=24h|7d|30d {total, online, series: [{at, online, total}]} ·
GET …/players/{moduleId}/list?limit=&offset=&q= (q: part of an email) {players: [{id, email, firstAt, lastAt, online}], total} (last sign-in first) ·
events: GET|POST …/players/{moduleId}/events {name} (idempotent: an existing name returns its event, 200), PATCH|DELETE …/events/{id} ·
feed: GET …/players/{moduleId}/activity?q=&player=&event=&before=&limit= → {entries: [{at, player: {id, email}, event: {id, name}}]} (limit 200 max.; newest first; q: free text in the player's email or the event name; before = the last at for the next page) ·
curve: GET …/activity/series?range=1d|7d|30d|6m + the same filters → {bucket, series: [{at, count}]} (1 h, 6 h, 1 day or 1 week buckets, empty ones included).
A Leaderboard module is one board (as many as you want per project), addressed by the module's GUID. Kind
score (highest first) or time (shortest first, in milliseconds); ties: first reached first. An
entry has a key chosen by the game (a player, a team, a character…), a displayed label, a
numeric value and optional small data for display. Entries are written by the game's server
with the project key; the ranking is public. Create one with POST /api/projects/{project}/modules
{type: "leaderboard", name, kind}.
| Route | Body | Effect |
|---|---|---|
GET /api/projects/{project}/leaderboards/{id} | {id, kind, total} · PATCH {kind} | |
PUT …/leaderboards/{id}/entries/{key} | {label, value, data?, keep?} | Creates or updates the entry. keep: "best" (default) changes the value only if better; "last" always. Label and data always follow. → {changed, rank}. DELETE removes it. |
POST …/leaderboards/{id}/entries | {entries: [...], keep?, replace?} | Bulk (10 000 max.); replace: true makes the board exactly these entries. |
DELETE …/leaderboards/{id}/entries | ?keys=a,b (optional) | Removes these keys, or resets the whole board. |
GET …/leaderboards/{id}/entries?limit=&offset=&q= | The ranking {entries: [{rank, key, label, value, data, at}]}; q searches label or key (ranks stay those of the full board). | |
GET /lb/{project}/{id}?limit=&offset=&key= | Public, CORS open: {kind, total, entries, rank?} (rank of key when given). |
// On the game server, after a match:
await fetch(`https://games-backstages.com/api/projects/my-game/leaderboards/${BOARD}/entries/${encodeURIComponent(playerId)}`, {
method: 'PUT',
headers: { authorization: `Bearer ${process.env.BACKSTAGES_KEY}`, 'content-type': 'application/json' },
body: JSON.stringify({ label: 'Gump', value: 1840 }), // keep: "best" by default
});
// Anywhere (browser included):
const top = await fetch(`https://games-backstages.com/lb/my-game/${BOARD}?limit=10`).then((r) => r.json());
Outside the modules, every project counts what games ask Games Backstages for, per hour (kept a little over 6 months):
public files (images.json, zip bundles, single image variants — with bytes served), configuration and context reads,
leaderboard public reads and writes, player accounts (sign-in pages opened, sign-ins, presence reports, activities, deletions),
System Action runs, and other API calls made with the project key. The creator's own use of the web interface is not counted.
| Route | Response |
|---|---|
GET /api/projects/{project}/usage?range=1d|7d|30d|6m(API key or owner session) | {range, bucket, since, total: {count, bytes}, metrics: [{id, label, count, bytes, top?}], series: [{at, count, bytes}]}.
Metric ids: index, bundle, image, values, context, lb_read, lb_write,
oauth_page, oauth_login, presence, activity, account_delete, servercall, api.
top (metrics about an item): the 10 most requested [{ref, name, count, bytes}] — folder (all = the whole project), image,
leaderboard, action or API route; name is null once the item is deleted. series: 1 h, 6 h, 1 day or 1 week buckets, empty ones included. |
Files served straight from the disk are read from the web server's access log (every 30 s, without IP addresses or headers), so the last minute may not show yet. A file cached by the player's browser is not requested again and is not counted.
No public sign-up: an administrator creates accounts. An account owns its projects and creates or deletes them
from the web interface. Session routes (/api/login, /api/projects…) serve the interface;
for automation, use a project's API key.