Schemas

The named schemas of openapi.yaml, games-api 0.7.0. A route’s body or response links here; a field that is itself a named schema links to its own section.

• Error
• Period
• AgeBand
• Player
• PlayerWithToken
• ConsumeResponse
• SaveMeta
• SaveServerCopy
• Save
• LeaderboardEntry
• LeaderboardTop
• EventBatch
• EventIn
• Catalog
• CatalogGame
• CatalogRating
• RatingSummary
• Comment
• GameReviews
• PlayerReview
• CommentAdmin
• CommentPage
• GameRatingAdmin
• FeedbackKind
• FeedbackStatus
• FeedbackInput
• FeedbackAccepted
• FeedbackAdmin
• FeedbackUpdate
• FeedbackPage
• MediaSlot
• MediaFile
• GameMedia
• GameTexts
• CategoryIcon
• Category
• CategoryInput
• Tag
• TagInput
• OtherSite
• Site
• SiteInput
• PublishResult
• Distribution
• Game
• GameInput
• GameVersion
• SiteGame
• SiteGameInput
• Leaderboard
• LeaderboardInput
• ScoreAdmin
• PlayerAdmin
• PlayerPage
• PlayerExport
• EventCount
• EventDaily
• StatsTotals
• StatsDay
• StatsGameRow
• StatsKeyCount
• StatsOverview
• GameStatsDay
• GameStatsTotals
• GameStatsBoard
• GameStats
• WebStatsRow
• WebStats
• AuditEntry
• GameToken
• AccountName
• NewPassword
• TotpCode
• MembershipRole
• Scope
• ConsoleMe
• SignInResult
• TotpEnrolment
• ConsoleSessionInfo
• InvitationPreview
• InvitationRequestInput
• InvitationRequestStatus
• InvitationRequest
• InvitationRequestPage
• Membership
• AccountAdmin
• AccountPage
• AccountPatch
• ImpersonationStarted
• InvitationGrant
• Invitation
• InvitationInput
• ApprovalOwner
• ApprovalGame
• ApprovalSite
• ApprovalDomains
• ApprovalVersion
• Approvals
• RejectInput
• Member
• MemberInput
• SiteKeyScope
• SiteKey
• SiteKeyCreated
• SiteKeyInput
• RetentionShare
• StatsCohort
• StatsFunnel
• ConsoleStatsDay
• ConsoleStatsTotals
• ConsoleGameStats
• ServerPlayerInput
• ServerPlayer

Error

Property	Type	Required	Description
error	one of "unauthorized", "forbidden", "not_found", "invalid", "conflict", "too_large", "rate_limited", "unavailable", "internal"	yes
message	string	yes
details	object	no

Period

Type: one of "day", "week", "all"; default "all".

AgeBand

Type: one of "all", "kids", "teen", "adult".

Player

Property	Type	Required	Description
id	string (uuid)	yes
nickname	string	yes
guest	boolean	yes
site	string	yes
locale	string	yes
emailMasked	string or null	no	a***@example.com for the account page
hasPassword	boolean	yes	True when the account set a password (ADR 0011); false for a guest
createdAt	string (date-time)	no

PlayerWithToken

Property	Type	Required	Description
player	Player	yes
token	string	yes

ConsumeResponse

What magic-link consume, consume-code and sign-in answer (ADR 0011)

Property	Type	Required	Description
player	Player	yes
token	string	yes
merged	boolean	yes	True when a guest was merged into the account by this call
redirect	string	no	Path on the site to go to; magic-link consume only, when the link carried one

SaveMeta

Property	Type	Required	Description
gameId	string	yes
version	integer	yes
etag	string	yes
bytes	integer	yes
updatedAt	string (date-time)	yes

SaveServerCopy

The 409 body. When nothing is stored yet, version is 0, etag is empty and updatedAt and data are null.

Property	Type	Required	Description
gameId	string	yes
version	integer	yes
etag	string	yes
bytes	integer	yes
updatedAt	string (date-time) or null	yes
data	any or null	yes

Save

Type: SaveMeta + object.

Property	Type	Required	Description
gameId	string	yes
version	integer	yes
etag	string	yes
bytes	integer	yes
updatedAt	string (date-time)	yes
data	any	yes

LeaderboardEntry

Property	Type	Required	Description
rank	integer	yes
nickname	string	yes
score	integer	yes
meta	object or null	no
isMe	boolean	yes

LeaderboardTop

Property	Type	Required	Description
period	Period	yes	default "all"
entries	LeaderboardEntry[]	yes
total	integer	yes
me	LeaderboardEntry or null	no

EventBatch

Property	Type	Required	Description
events	EventIn[]	yes	at most 50 items

EventIn

Property	Type	Required	Description
name	string	yes	frame_loaded is reserved: accepted with a player token from the hub, refused with a game token (ADR 0015); pattern ^[a-z][a-z0-9_]{0,39}$
props	object	no
props.*	string or number or boolean	no
ts	integer	yes	Unix milliseconds on the client
gameId	string	no
gameVersion	string	no
sessionId	string (uuid)	no
host	string	no
locale	string	no

Catalog

Property	Type	Required	Description
site	object	yes
site.slug	string	yes
site.name	string	yes
site.domains	string[]	yes
site.locales	string[]	yes
site.policy	object	yes
site.policy.accountsAllowed	boolean	no
site.policy.personalizedAdsAllowed	boolean	no
site.policy.ageBand	AgeBand	no
site.navCategories	string[]	yes	Category slugs of the top menu, in menu order; only slugs that exist
site.otherSites	OtherSite[]	yes
site.analyticsDomain	string	yes	The domain registered at CausalIT (causalitDomain, else the first domain); the front’s tag reports to it
generatedAt	string (date-time)	yes
categories	Category[]	yes
tags	Tag[]	yes	Every tag of the site, in site order; game tags are slugs of this list
games	CatalogGame[]	yes

CatalogGame

Property	Type	Required	Description
slug	string	yes
order	integer	yes
featured	boolean	yes
categories	string[]	yes
tags	string[]	yes
orientation	one of "portrait", "landscape", "any"	yes
minutes	integer or null	yes	Typical run length in minutes; null when not set
mobile	boolean	yes
daily	boolean	yes
coverColor	string or null	no
publishedAt	string (date-time) or null	no	When the live version was activated; null without one
bundleUrl	string (uri) or null	yes	https://play.filudi.com/<slug>/<version>/index.html; null when no live version
version	string or null	yes
boards	object[]	yes
boards[].name	string	no
boards[].sort	one of "desc", "asc"	no
texts	object	yes	Keyed by locale
texts.*	GameTexts	no
media	GameMedia	yes	Filled slots only; a missing key is an empty slot
rating	CatalogRating	yes	Stars of a game on the site (ADR 0012). Follows ratings within the catalog’s 60-second cache.

CatalogRating

Stars of a game on the site (ADR 0012). Follows ratings within the catalog’s 60-second cache.

Property	Type	Required	Description
average	number or null	yes	Mean of the stars, rounded to one decimal; null when count is 0
count	integer	yes	at least 0

RatingSummary

Property	Type	Required	Description
average	number or null	yes	Mean of the stars, rounded to one decimal; null when count is 0
count	integer	yes	at least 0
histogram	integer[]	yes	Ratings per star count; index 0 is one star, index 4 is five stars; 5 to 5 items

Comment

Property	Type	Required	Description
id	string (uuid)	yes
nickname	string	yes	The author’s current nickname, read when the list is served
body	string	yes	Plain text with newlines; render as text
createdAt	string (date-time)	yes
editedAt	string (date-time) or null	yes

GameReviews

Property	Type	Required	Description
rating	RatingSummary	yes
comments	Comment[]	yes
nextCursor	string or null	yes	Null on the last page

PlayerReview

Property	Type	Required	Description
stars	integer or null	yes	Null when the player has not rated the game; 1 to 5
comments	Comment[]	yes	The player’s visible comments on the game, newest first

CommentAdmin

Property	Type	Required	Description
id	string (uuid)	yes
gameId	string (uuid)	yes
game	string	yes	Game slug
player	object	yes
player.id	string (uuid)	yes
player.nickname	string	yes
player.emailMasked	string or null	yes
body	string	yes
locale	string	yes
hidden	boolean	yes
hiddenBy	string or null	yes	Username of the moderator
hiddenAt	string (date-time) or null	yes
createdAt	string (date-time)	yes
editedAt	string (date-time) or null	yes

CommentPage

Property	Type	Required	Description
items	CommentAdmin[]	yes
nextCursor	string or null	yes
total	integer	yes

GameRatingAdmin

Property	Type	Required	Description
gameId	string (uuid)	yes
game	string	yes	Game slug
average	number or null	yes
count	integer	yes
histogram	integer[]	yes	Index 0 is one star; 5 to 5 items

FeedbackKind

Type: one of "bug", "suggestion", "other".

FeedbackStatus

Type: one of "new", "seen", "done".

FeedbackInput

Property	Type	Required	Description
site	string	yes	Site slug
game	string	no	Game slug; absent when the message is about the site
kind	FeedbackKind	yes
message	string	yes	Counted after trim; 10 to 2000 characters
email	string (email) or string	no	Where the team may reply; "" counts as no email
page	string	no	Path of the page, without the query string; at most 512 characters; pattern ^/
locale	string	no	The page locale; kept when it is a locale of the site

FeedbackAccepted

Property	Type	Required	Description
id	string (uuid)	yes

FeedbackAdmin

Property	Type	Required	Description
id	string (uuid)	yes
kind	FeedbackKind	yes
status	FeedbackStatus	yes
message	string	yes
email	string or null	yes	In clear: the reporter gave it to be contacted
gameId	string (uuid) or null	yes
game	string or null	yes	Game slug; null for the site or a deleted game
player	object or null	yes
page	string or null	yes
userAgent	string or null	yes
locale	string or null	yes
note	string or null	yes
createdAt	string (date-time)	yes
updatedAt	string (date-time)	yes

FeedbackUpdate

At least one field; an empty body is a 400.

Property	Type	Required	Description
status	FeedbackStatus	no
note	string or null	no	Null clears the note; "" is stored as null; at most 2000 characters

FeedbackPage

Property	Type	Required	Description
items	FeedbackAdmin[]	yes
nextCursor	string or null	yes
total	integer	yes

MediaSlot

ADR 0007 gives the ratio, pixel range, file types and size limit of each slot

Type: one of "image-square", "image-landscape", "image-portrait", "video-landscape", "video-portrait".

MediaFile

Property	Type	Required	Description
url	string (uri)	yes	https://play.filudi.com/<slug>/media/<kind>-<format>-<sha256:16>.<ext>; immutable
type	one of "image/avif", "image/webp", "image/jpeg", "image/png", "video/mp4"	yes
bytes	integer	yes
width	integer	yes
height	integer	yes
durationMs	integer	no	Videos only

GameMedia

Filled slots only; a missing key is an empty slot

Property	Type	Required	Description
images	object	yes
images.square	MediaFile	no
images.landscape	MediaFile	no
images.portrait	MediaFile	no
videos	object	yes
videos.landscape	MediaFile	no
videos.portrait	MediaFile	no

GameTexts

Property	Type	Required	Description
title	string	yes
tagline	string	yes	One line under the title
description	string	yes
howToPlay	string[]	no
controls	object[]	no
controls[].keys	string[]	no
controls[].does	string	no
seoTitle	string	no
seoDescription	string	no

CategoryIcon

Stroke icons drawn by hub-core (categoryIconSvg), the same list in the admin picker

Type: one of "puzzle", "joystick", "calendar", "keyboard", "letters", "brain", "cards", "dice", "target", "rocket", "timer", "trophy", "heart", "star", "sparkle", "grid", "map", "music", "bolt", "leaf".

Category

Property	Type	Required	Description
id	string (uuid)	no
slug	string	yes
order	integer	yes
icon	CategoryIcon or null	no
texts	object	yes
texts.*.title	string	no
texts.*.navTitle	string	no	Short form for the menu, chips and card meta: “Puzzle” for “Puzzle games”
texts.*.description	string	no
gameCount	integer	no	Admin routes only; games of the site in this category
createdAt	string (date-time)	no
updatedAt	string (date-time)	no

CategoryInput

Property	Type	Required	Description
slug	string	no	On create only; ignored on PATCH; pattern ^[a-z][a-z0-9-]{0,39}$
icon	CategoryIcon or null	no
texts	object	no	Keyed by locale; the site’s default locale needs a title
texts.*.title	string	no	at most 120 characters
texts.*.navTitle	string	no	at most 24 characters
texts.*.description	string	no	at most 1000 characters

Tag

Property	Type	Required	Description
id	string (uuid)	no
slug	string	yes
order	integer	yes
texts	object	yes	Keyed by locale
texts.*.title	string	no
gameCount	integer	no	Admin routes only; games of the site carrying this tag
createdAt	string (date-time)	no
updatedAt	string (date-time)	no

TagInput

Property	Type	Required	Description
slug	string	no	On create only; ignored on PATCH; pattern ^[a-z][a-z0-9-]{0,39}$
texts	object	no	Keyed by locale; the site’s default locale needs a title
texts.*.title	string	no	at most 60 characters

OtherSite

A sister site of the footer

Property	Type	Required	Description
name	string	yes	1 to 60 characters
url	string (uri)	yes	https only
description	string	no	at most 120 characters

Site

Property	Type	Required	Description
id	string (uuid)	yes
slug	string	yes
name	string	yes
domains	string[]	yes	Approved domains; allowed origins once the site is approved
locales	string[]	yes
approvedAt	string (date-time) or null	yes	Null while the site waits for staff (ADR 0015); then its domains are not allowed origins
pendingDomains	string[]	yes	Domains the owner proposed; approval moves them into domains
firstParty	boolean	yes	The owner’s own site: lists any approved game, whatever its distribution
accountsAllowed	boolean	yes
personalizedAdsAllowed	boolean	yes
ageBand	AgeBand	yes
cdnPullZoneId	string or null	no	Bunny pull zone in front of the site; publish purges it
navCategories	string[]	yes	Category slugs of the top menu, in order
otherSites	OtherSite[]	yes
causalitDomain	string or null	no	Domain registered at CausalIT; null means the first domain
causalitKeys	object	yes	Whether each key is stored. The keys themselves are never returned.
causalitKeys.read	boolean	yes
causalitKeys.write	boolean	yes
createdAt	string (date-time)	no
updatedAt	string (date-time)	no

SiteInput

On PATCH the slug may be repeated unchanged; the API refuses a different slug. slug, domains, firstParty and cdnPullZoneId are for staff only; owners and members write pendingDomains and the CausalIT fields (ADR 0015). A key field set to null clears the stored key; absent leaves it.

Property	Type	Required	Description
slug	string	no	pattern ^[a-z][a-z0-9-]{1,39}$
name	string	no	1 to 80 characters
domains	string[]	no	Lowercase hostnames, the first is canonical. Staff only.; at least 1 item
pendingDomains	string[]	no	Lowercase hostnames the owner proposes; each works once staff approves it. Replaces the whole list.; at most 10 items
firstParty	boolean	no	Staff only
locales	string[]	no	Lowercase BCP 47, unique, the first is the default; at least 1 item
accountsAllowed	boolean	no
personalizedAdsAllowed	boolean	no
ageBand	AgeBand	no
cdnPullZoneId	string or null	no	pattern ^[0-9]{1,12}$
navCategories	string[]	no	Slugs of existing categories of the site, unique, in menu order; at most 12 items
otherSites	OtherSite[]	no	at most 10 items
causalitDomain	string or null	no	pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$
causalitReadKey	string or null	no	8 to 200 characters; write only
causalitWriteKey	string or null	no	8 to 200 characters; write only

PublishResult

Property	Type	Required	Description
purged	boolean	yes
reason	one of "no_zone", "no_key"	no	Why nothing was purged; absent when purged is true
at	string (date-time)	yes

Distribution

Where a game may be listed (ADR 0015). first_party: sites with firstParty only. any_portal: any approved site.

Type: one of "first_party", "any_portal".

Game

Property	Type	Required	Description
id	string (uuid)	yes
slug	string	yes
name	string	yes
orientation	one of "portrait", "landscape", "any"	yes
minutes	integer or null	yes	Typical run length in minutes; null when not set
mobile	boolean	yes
daily	boolean	yes
coverColor	string or null	no
approvedAt	string (date-time) or null	yes	Null while the game waits for staff (ADR 0015): no live version, no listing on an approved site
distribution	Distribution	yes	Where a game may be listed (ADR 0015). first_party: sites with firstParty only. any_portal: any approved site.
listedOn	object[]	yes	Sites whose catalog carries the game
listedOn[].siteId	string (uuid)	yes
listedOn[].slug	string	yes
listedOn[].name	string	yes
versions	GameVersion[]	yes
media	GameMedia	yes	Filled slots only; a missing key is an empty slot
sites	string[]	no	Slugs of sites listing this game
createdAt	string (date-time)	yes
updatedAt	string (date-time)	yes

GameInput

Property	Type	Required	Description
slug	string	no	pattern ^[a-z][a-z0-9-]{1,39}$
name	string	no
orientation	one of "portrait", "landscape", "any"	no
minutes	integer or null	no	1 to 600
mobile	boolean	no
daily	boolean	no
coverColor	string or null	no	pattern ^#[0-9A-Fa-f]{6}$
distribution	Distribution	no	Where a game may be listed (ADR 0015). first_party: sites with firstParty only. any_portal: any approved site.

GameVersion

Property	Type	Required	Description
id	string (uuid)	yes
version	string	yes
state	one of "draft", "live", "retired"	yes
bundlePath	string	yes
entry	string	yes
sizeBytes	integer	yes
fileCount	integer	yes
notes	string or null	no
createdBy	string	yes
createdAt	string (date-time)	yes
activatedAt	string (date-time) or null	no
retiredAt	string (date-time) or null	no
reviewRequestedAt	string (date-time) or null	yes	Set by POST /v1/admin/versions/{versionId}/review; cleared on activate, retire and review reject

SiteGame

Property	Type	Required	Description
gameId	string (uuid)	yes
slug	string	yes
order	integer	yes
featured	boolean	yes
visible	boolean	yes
categories	string[]	yes
tags	string[]	yes
texts	object	yes
texts.*	GameTexts	no
liveVersion	string or null	no
updatedAt	string (date-time)	no

SiteGameInput

Property	Type	Required	Description
featured	boolean	no
visible	boolean	no
categories	string[]	no
tags	string[]	no
texts	object	no
texts.*	GameTexts	no

Leaderboard

Property	Type	Required	Description
id	string (uuid)	yes
name	string	yes
sort	one of "desc", "asc"	yes
min	integer	yes
max	integer	yes
keep	one of "best", "latest"	yes
ratePerMinute	integer	yes

LeaderboardInput

Property	Type	Required	Description
name	string	yes	pattern ^[a-z][a-z0-9_]{0,31}$
sort	one of "desc", "asc"	yes
min	integer	yes
max	integer	yes
keep	one of "best", "latest"	no	default "best"
ratePerMinute	integer	no	default 10

ScoreAdmin

A developer who does not edit the player’s site gets no playerId, site, hiddenBy or sessionId (ADR 0014).

Property	Type	Required	Description
id	string	yes
playerId	string (uuid)	no
nickname	string	yes
site	string	no
score	integer	yes
meta	object or null	no
hidden	boolean	yes
hiddenBy	string or null	no
sessionId	string (uuid)	no
createdAt	string (date-time)	yes

PlayerAdmin

Property	Type	Required	Description
id	string (uuid)	yes
site	string	yes
nickname	string	yes
guest	boolean	yes
emailMasked	string or null	no
externalId	string or null	no	A portal backend’s own user id, set through POST /v1/server/players; null otherwise
hasPassword	boolean	yes	Whether the account set a password; the admin cannot set one
locale	string	no
createdAt	string (date-time)	yes
lastSeenAt	string (date-time)	yes
deleteAt	string (date-time) or null	no
mergedIntoId	string (uuid) or null	no
saves	SaveMeta[]	no
bestScores	object[]	no
bestScores[].game	string	yes
bestScores[].board	string	yes
bestScores[].score	integer	yes
bestScores[].createdAt	string (date-time)	yes

PlayerPage

Property	Type	Required	Description
items	PlayerAdmin[]	yes
nextCursor	string or null	yes	Null on the last page
total	integer	yes	Rows matching the filters

PlayerExport

Property	Type	Required	Description
exportedAt	string (date-time)	yes
player	Player	yes
email	string or null	no
saves	Save[]	yes
scores	object[]	yes
events	object[]	yes	Most recent 20 000 of the last 13 months
eventsTruncated	boolean	no	True when older events were left out
ratings	object[]	yes	The player’s ratings on the site (ADR 0012)
ratings[].game	string	yes	Game slug
ratings[].stars	integer	yes	1 to 5
ratings[].createdAt	string (date-time)	yes
ratings[].updatedAt	string (date-time)	yes
comments	object[]	yes	Every comment of the player, hidden ones included
comments[].id	string (uuid)	yes
comments[].game	string	yes	Game slug
comments[].body	string	yes
comments[].hidden	boolean	yes
comments[].createdAt	string (date-time)	yes
comments[].editedAt	string (date-time) or null	yes
feedback	object[]	yes	Feedback the player sent with a token
feedback[].id	string (uuid)	yes
feedback[].kind	FeedbackKind	yes
feedback[].status	FeedbackStatus	yes
feedback[].message	string	yes
feedback[].game	string or null	yes	Game slug; null for the site or a deleted game
feedback[].page	string or null	yes
feedback[].createdAt	string (date-time)	yes

EventCount

Property	Type	Required	Description
game	string or null	no
name	string	yes
host	string	yes
count	integer	yes
players	integer	yes

EventDaily

Type: EventCount + object.

Property	Type	Required	Description
game	string or null	no
name	string	yes
host	string	yes
count	integer	yes
players	integer	yes
day	string (date)	yes

StatsTotals

Counts over a range of days. Players and accounts count rows created in the range.

Property	Type	Required	Description
players	integer	yes	Players created
accounts	integer	yes	Players that linked an email
activePlayers	integer	yes	Distinct players with a play session
sessions	integer	yes
scores	integer	yes
saves	integer	yes	Saves written or updated
linksSent	integer	yes	Magic links created
linksConsumed	integer	yes
events	integer	yes	Rows of event_daily summed
avgSessionSec	number or null	yes	Mean of last_seen_at minus started_at
medianSessionSec	number or null	yes	Median of the same lengths
returningPlayers	integer	yes	Players of the range with a session on at least two distinct days
retentionD1	RetentionShare or null	yes	Share of new players who played again in the window; null below 10 players old enough to be counted; 0 to 1
retentionD7	RetentionShare or null	yes	Share of new players who played again in the window; null below 10 players old enough to be counted; 0 to 1
retentionD30	RetentionShare or null	yes	Share of new players who played again in the window; null below 10 players old enough to be counted; 0 to 1

StatsDay

Property	Type	Required	Description
day	string (date)	yes
players	integer	yes
accounts	integer	yes
activePlayers	integer	yes
wau	integer	yes	Distinct players with a session in the 7 days ending that day
mau	integer	yes	Distinct players with a session in the 30 days ending that day
returningPlayers	integer	yes	Active players whose first session is before that day
sessions	integer	yes
scores	integer	yes
saves	integer	yes
linksSent	integer	yes
linksConsumed	integer	yes
events	integer	yes
medianSessionSec	number or null	yes

StatsGameRow

Property	Type	Required	Description
gameId	string (uuid)	yes
slug	string	yes
name	string	yes	The game’s internal name
sessions	integer	yes
players	integer	yes	Distinct players
scores	integer	yes
avgSessionSec	number or null	no

StatsKeyCount

Property	Type	Required	Description
key	string	yes
count	integer	yes
players	integer	no	Players, when the dimension has them. For event names: distinct players per day, summed over the range

StatsOverview

Property	Type	Required	Description
from	string (date)	yes
to	string (date)	yes
days	StatsDay[]	yes	One per day of the range
totals	StatsTotals	yes	Counts over a range of days. Players and accounts count rows created in the range.
previous	StatsTotals	yes	Counts over a range of days. Players and accounts count rows created in the range.
cohorts	StatsCohort[]	yes
funnel	StatsFunnel	yes	Distinct players of the range at each step
devices	StatsKeyCount[]	yes	Sessions per device: phone, tablet, desktop, unknown
games	StatsGameRow[]	yes	Every game of the site catalog, most sessions first
hosts	StatsKeyCount[]	yes	Sessions per host
locales	StatsKeyCount[]	yes	Players per locale, all time
events	StatsKeyCount[]	yes	event_daily counts per event name, top 20
catalog	object	yes
catalog.games	integer	yes	Games in the site catalog
catalog.visible	integer	yes
catalog.live	integer	yes	Visible games with a live version
catalog.categories	integer	yes
catalog.tags	integer	yes
generatedAt	string (date-time)	yes

GameStatsDay

Property	Type	Required	Description
day	string (date)	yes
sessions	integer	yes
players	integer	yes	Distinct players with a session
wau	integer	yes	Distinct players with a session in the 7 days ending that day
mau	integer	yes	Distinct players with a session in the 30 days ending that day
newPlayers	integer	yes	Players whose first session on this game is that day
returningPlayers	integer	yes	Players with a session that day and a first session before it
scores	integer	yes
saves	integer	yes	Saves written or updated
events	integer	yes
avgSessionSec	number or null	no
medianSessionSec	number or null	yes

GameStatsTotals

Property	Type	Required	Description
sessions	integer	yes
players	integer	yes
newPlayers	integer	yes
returningPlayers	integer	yes	Players of the range with a session on at least two distinct days
scores	integer	yes
saves	integer	yes
events	integer	yes
avgSessionSec	number or null	no
medianSessionSec	number or null	yes
retentionD1	number or null	no	Share (0 to 1) of the range’s new players who played again the next day, counting only players whose first day is at least two days before the current UTC day; null below 10 such players
retentionD7	number or null	no	Share of the range’s new players who played again between day 2 and day 7, counting only players whose first day is at least eight days before the current UTC day; null below 10 such players
retentionD30	number or null	yes	Share of the range’s new players who played again between day 8 and day 30, counting only players whose first day is at least 31 days before the current UTC day; null below 10 such players

GameStatsBoard

Property	Type	Required	Description
name	string	yes
sort	one of "desc", "asc"	yes
scores	integer	yes
players	integer	yes
best	integer or null	no	Best score of the range by the board’s sort
median	number or null	no

GameStats

Property	Type	Required	Description
gameId	string (uuid)	yes
slug	string	yes
from	string (date)	yes
to	string (date)	yes
days	GameStatsDay[]	yes
totals	GameStatsTotals	yes
previous	GameStatsTotals	yes
cohorts	StatsCohort[]	yes
funnel	StatsFunnel	yes	Distinct players of the range at each step
hosts	StatsKeyCount[]	yes	Sessions per host
locales	StatsKeyCount[]	yes	Sessions per player locale
devices	StatsKeyCount[]	yes	Sessions per device: phone, tablet, desktop, unknown
boards	GameStatsBoard[]	yes
events	StatsKeyCount[]	yes	Per event name, top 20
versions	StatsKeyCount[]	yes	Sessions per bundle version
generatedAt	string (date-time)	yes

WebStatsRow

Property	Type	Required	Description
key	string	yes
visitors	integer	yes
pageviews	integer	yes

WebStats

When configured is false every other field is absent.

Property	Type	Required	Description
configured	boolean	yes	False when the site has no CausalIT read key
domain	string	no
period	string	no
start	string (date-time)	no
end	string (date-time)	no
summary	object	no
summary.visitors	integer	yes
summary.pageviews	integer	yes
summary.sessions	integer	yes
summary.bounceRate	number or null	no	Percentage, 0 to 100
summary.avgDurationSec	number or null	no
series	object[]	no
series[].bucket	string	yes
series[].visitors	integer	yes
series[].pageviews	integer	yes
pages	WebStatsRow[]	no
sources	WebStatsRow[]	no
countries	WebStatsRow[]	no
devices	WebStatsRow[]	no
goals	object[]	no
goals[].name	string	yes
goals[].kind	one of "path", "event"	yes
goals[].pattern	string	no
goals[].conversions	integer	yes
goals[].visitors	integer	yes
goals[].rate	number or null	no	Conversion rate, percentage, 0 to 100

AuditEntry

Property	Type	Required	Description
id	string	yes
actor	string	yes	The account’s email (ADR 0015)
actorEmail	string or null	no
impersonator	string or null	no	The staff member’s email when the row was written under impersonation; null otherwise
site	string or null	no	Site slug
action	string	yes
targetType	string	yes
targetId	string	yes
before	object or null	no
after	object or null	no
createdAt	string (date-time)	yes

GameToken

What POST /v1/sdk/game-tokens and POST /v1/server/game-tokens answer (ADR 0013)

Property	Type	Required	Description
token	string	yes	fg1.<payload>.<hmac>, valid 24 hours
expiresAt	string (date-time)	yes

AccountName

Display name, shown to other members and in the audit log

Type: string; 1 to 80 characters.

NewPassword

The policy of PUT /v1/account/password: 8 to 128 characters after NFC normalization, not equal to the email

Type: string; 8 to 128 characters; write only.

TotpCode

Six digits, “123456” or “123 456”

Type: string; pattern ^[0-9 ]{6,7}$.

MembershipRole

A member has every right of the owner except membership changes

Type: one of "owner", "member".

Scope

One game or site of the account, for the console’s scope switcher

Property	Type	Required	Description
kind	one of "game", "site"	yes
id	string (uuid)	yes
slug	string	yes
name	string	yes
role	MembershipRole	yes	A member has every right of the owner except membership changes
approved	boolean	yes	False while the game or site waits for staff

ConsoleMe

The signed-in account, as GET /v1/admin/me and GET /v1/console/me answer it (ADR 0015)

Property	Type	Required	Description
accountId	string (uuid)	yes
name	string	yes
email	string (email)	yes
staff	boolean	yes
totpEnabled	boolean	yes
canCreateGames	boolean	yes
canCreatePortals	boolean	yes
roles	object	yes	The identity shape of ADR 0014, computed from staff and the memberships
roles.admin	boolean	yes	True for staff with TOTP enabled
roles.editorOf	string[]	yes	Slugs of the sites the account is a member of
roles.developerOf	string[]	yes	Slugs of the games the account is a member of
scopes	Scope[]	yes
impersonatedBy	object or null	yes	The staff member behind this session; null outside impersonation

SignInResult

Property	Type	Required	Description
totpRequired	boolean	yes	True when a code is due on POST /v1/console/sign-in/totp; me is then absent
me	ConsoleMe	no	The signed-in account, as GET /v1/admin/me and GET /v1/console/me answer it (ADR 0015)

TotpEnrolment

Property	Type	Required	Description
secret	string	yes	Base32, for manual entry; shown once, not active until confirmed
otpauthUrl	string (uri)	yes	otpauth://totp/... for the QR code

ConsoleSessionInfo

Property	Type	Required	Description
id	string (uuid)	yes
current	boolean	yes	The session that made this request
impersonation	boolean	yes	Opened by a staff member on this account
userAgent	string or null	yes	First 300 characters of the browser’s User-Agent
createdAt	string (date-time)	yes
lastSeenAt	string (date-time)	yes	Written at most once a minute
expiresAt	string (date-time)	yes

InvitationPreview

What the accept page shows before the invitee sets a name and a password

Property	Type	Required	Description
emailMasked	string	yes	a***@example.com
inviterName	string or null	yes	Null when the inviter’s account is gone
staff	boolean	yes
canCreateGames	boolean	yes
canCreatePortals	boolean	yes
grants	object[]	yes
grants[].kind	one of "game", "site"	yes
grants[].slug	string	yes
grants[].name	string	yes
grants[].role	MembershipRole	yes	A member has every right of the owner except membership changes
expiresAt	string (date-time)	yes

InvitationRequestInput

Property	Type	Required	Description
email	string (email)	yes	at most 254 characters
wants	array of one of "games", "portals"	yes	What they build; 1 to 2 items; unique items
message	string	yes	Counted after trim; 1 to 500 characters

InvitationRequestStatus

Type: one of "new", "invited", "dismissed".

InvitationRequest

Property	Type	Required	Description
id	string (uuid)	yes
emailMasked	string	yes
email	string (email)	yes	In clear
wants	array of one of "games", "portals"	yes
message	string	yes
status	InvitationRequestStatus	yes
handledBy	string or null	yes	Name of the staff member who invited or dismissed
handledAt	string (date-time) or null	yes
createdAt	string (date-time)	yes

InvitationRequestPage

Property	Type	Required	Description
items	InvitationRequest[]	yes
nextCursor	string or null	yes	Null on the last page
total	integer	yes	Rows matching the filter

Membership

One right of an account, as the staff account page lists them

Property	Type	Required	Description
id	string (uuid)	yes
kind	one of "game", "site"	yes
targetId	string (uuid)	yes
slug	string	yes
name	string	yes
role	MembershipRole	yes	A member has every right of the owner except membership changes
approved	boolean	yes	False while the game or site waits for staff

AccountAdmin

Property	Type	Required	Description
id	string (uuid)	yes
emailMasked	string	yes
email	string (email)	yes	In clear; staff only
name	string	yes
staff	boolean	yes
totpEnabled	boolean	yes
canCreateGames	boolean	yes
canCreatePortals	boolean	yes
disabledAt	string (date-time) or null	yes
lastSignInAt	string (date-time) or null	yes
createdAt	string (date-time)	yes
memberships	Membership[]	yes
sessions	integer	yes	Open sessions

AccountPage

Property	Type	Required	Description
items	AccountAdmin[]	yes
nextCursor	string or null	yes	Null on the last page
total	integer	yes	Rows matching the search

AccountPatch

At least one field; an empty body is a 400.

Property	Type	Required	Description
name	AccountName	no	Display name, shown to other members and in the audit log; 1 to 80 characters
email	string (email)	no	Changed at once
staff	boolean	no	A new staff member gets admin rights once TOTP is enabled
canCreateGames	boolean	no
canCreatePortals	boolean	no
disabled	boolean	no	True revokes every session and refuses sign-in; false enables again

ImpersonationStarted

Property	Type	Required	Description
consoleUrl	string (uri)	yes	The console (CONSOLE_URL), to open in a new tab
expiresAt	string (date-time)	yes	One hour after the start

InvitationGrant

Property	Type	Required	Description
kind	one of "game", "site"	yes
targetId	string (uuid)	yes
slug	string	yes
name	string	yes
role	MembershipRole	yes	A member has every right of the owner except membership changes

Invitation

Property	Type	Required	Description
id	string (uuid)	yes
emailMasked	string	yes
staff	boolean	yes
canCreateGames	boolean	yes
canCreatePortals	boolean	yes
grants	InvitationGrant[]	yes
createdBy	string or null	yes	Name of the inviter; null when the account is gone
expiresAt	string (date-time)	yes
acceptedAt	string (date-time) or null	yes
revokedAt	string (date-time) or null	yes
createdAt	string (date-time)	yes

InvitationInput

Property	Type	Required	Description
email	string (email)	yes	at most 254 characters
staff	boolean	no	default false
canCreateGames	boolean	no	default false
canCreatePortals	boolean	no	default false
grants	object[]	no	Memberships created on accept. Each item names exactly one of game and site.; at most 50 items
grants[].game	string (uuid)	no
grants[].site	string (uuid)	no
grants[].role	MembershipRole	yes	A member has every right of the owner except membership changes

ApprovalOwner

Property	Type	Required	Description
accountId	string (uuid)	yes
name	string	yes
email	string (email)	yes

ApprovalGame

Property	Type	Required	Description
gameId	string (uuid)	yes
slug	string	yes
name	string	yes
owners	ApprovalOwner[]	yes
createdAt	string (date-time)	yes

ApprovalSite

Property	Type	Required	Description
siteId	string (uuid)	yes
slug	string	yes
name	string	yes
owners	ApprovalOwner[]	yes
pendingDomains	string[]	yes	The domains the owner proposed. Approving the site does not approve them; they move to the domains queue, decided one by one
createdAt	string (date-time)	yes

ApprovalDomains

The proposed domains of one approved site

Property	Type	Required	Description
siteId	string (uuid)	yes
slug	string	yes
name	string	yes
domains	string[]	yes

ApprovalVersion

Property	Type	Required	Description
versionId	string (uuid)	yes
gameId	string (uuid)	yes
slug	string	yes
version	string	yes
reviewRequestedAt	string (date-time)	yes
createdBy	string	yes

Approvals

Every list is oldest first

Property	Type	Required	Description
games	ApprovalGame[]	yes
sites	ApprovalSite[]	yes
domains	ApprovalDomains[]	yes
versions	ApprovalVersion[]	yes

RejectInput

Property	Type	Required	Description
reason	string	yes	Sent to the owners by email; 1 to 1000 characters

Member

Property	Type	Required	Description
accountId	string (uuid) or null	yes	Null while the invitation is not accepted
invitationId	string (uuid) or null	yes	Set while the invitation is not accepted; DELETE .../members/invitations/{invitationId} withdraws it
emailMasked	string	yes
name	string or null	yes	Null while the invitation is not accepted
role	MembershipRole	yes	A member has every right of the owner except membership changes
invited	boolean	yes	True for an invitation not accepted yet
createdAt	string (date-time)	yes

MemberInput

Property	Type	Required	Description
email	string (email)	yes	at most 254 characters
role	MembershipRole	yes	A member has every right of the owner except membership changes

SiteKeyScope

Each /v1/server/* route says which scope it needs

Type: one of "catalog", "players", "tokens", "leaderboards", "stats".

SiteKey

Property	Type	Required	Description
id	string (uuid)	yes
name	string	yes
prefix	string	yes	The first 12 characters of the key, to tell keys apart
scopes	SiteKeyScope[]	yes
createdBy	string or null	yes	Name of the account that created it
createdAt	string (date-time)	yes
lastUsedAt	string (date-time) or null	yes	Written at most once a minute
revokedAt	string (date-time) or null	yes

SiteKeyCreated

Type: SiteKey + object.

Property	Type	Required	Description
id	string (uuid)	yes
name	string	yes
prefix	string	yes	The first 12 characters of the key, to tell keys apart
scopes	SiteKeyScope[]	yes
createdBy	string or null	yes	Name of the account that created it
createdAt	string (date-time)	yes
lastUsedAt	string (date-time) or null	yes	Written at most once a minute
revokedAt	string (date-time) or null	yes
key	string	yes	fsk_<site slug>_<32 base62>. Shown once; the API stores a hash

SiteKeyInput

Property	Type	Required	Description
name	string	yes	1 to 60 characters
scopes	SiteKeyScope[]	yes	at least 1 item; unique items

RetentionShare

Share of new players who played again in the window; null below 10 players old enough to be counted

Type: number or null; 0 to 1.

StatsCohort

Players by the ISO week of their first play

Property	Type	Required	Description
week	string	yes	ISO week; pattern ^\d{4}-W\d{2}$
players	integer	yes	Players whose first session is in that week
d1	RetentionShare or null	yes	Share of new players who played again in the window; null below 10 players old enough to be counted; 0 to 1
d7	RetentionShare or null	yes	Share of new players who played again in the window; null below 10 players old enough to be counted; 0 to 1
d30	RetentionShare or null	yes	Share of new players who played again in the window; null below 10 players old enough to be counted; 0 to 1

StatsFunnel

Distinct players of the range at each step

Property	Type	Required	Description
loaded	integer	yes	Sent frame_loaded from the hub
started	integer	yes	Opened a play session
saved	integer	yes	Wrote a save
scored	integer	yes	Sent a score
linked	integer	yes	Linked an email

ConsoleStatsDay

Property	Type	Required	Description
day	string (date)	yes
dau	integer	yes	Distinct players with a session that day
wau	integer	yes	Distinct players with a session in the 7 days ending that day
mau	integer	yes	Distinct players with a session in the 30 days ending that day
newPlayers	integer	yes	Players whose first session on this game is that day
returningPlayers	integer	yes	Players with a session that day and a first session before it
sessions	integer	yes
scores	integer	yes
saves	integer	yes	Saves written or updated
events	integer	yes
meanSessionSec	number or null	yes
medianSessionSec	number or null	yes

ConsoleStatsTotals

Property	Type	Required	Description
players	integer	yes	Distinct players with a session
newPlayers	integer	yes
returningPlayers	integer	yes	Players of the range with a session on at least two distinct days
sessions	integer	yes
scores	integer	yes
saves	integer	yes
events	integer	yes
meanSessionSec	number or null	yes
medianSessionSec	number or null	yes
retentionD1	RetentionShare or null	yes	Share of new players who played again in the window; null below 10 players old enough to be counted; 0 to 1
retentionD7	RetentionShare or null	yes	Share of new players who played again in the window; null below 10 players old enough to be counted; 0 to 1
retentionD30	RetentionShare or null	yes	Share of new players who played again in the window; null below 10 players old enough to be counted; 0 to 1

ConsoleGameStats

A game’s numbers across every site that lists it (ADR 0015)

Property	Type	Required	Description
gameId	string (uuid)	yes
slug	string	yes
from	string (date)	yes
to	string (date)	yes
days	ConsoleStatsDay[]	yes
totals	ConsoleStatsTotals	yes
previous	ConsoleStatsTotals	yes
cohorts	StatsCohort[]	yes
funnel	StatsFunnel	yes	Distinct players of the range at each step
sites	object[]	yes	Every site that lists the game, most sessions first
sites[].siteId	string (uuid)	yes
sites[].slug	string	yes
sites[].name	string	yes
sites[].sessions	integer	yes
sites[].players	integer	yes	Distinct players
hosts	StatsKeyCount[]	yes	Sessions per host
versions	StatsKeyCount[]	yes	Sessions per bundle version
locales	StatsKeyCount[]	yes	Sessions per player locale
devices	StatsKeyCount[]	yes	Sessions per device: phone, tablet, desktop, unknown
boards	GameStatsBoard[]	yes
events	StatsKeyCount[]	yes	Per event name with distinct players, top 20
generatedAt	string (date-time)	yes

ServerPlayerInput

Property	Type	Required	Description
externalId	string	yes	Your own user id; 1 to 128 characters
nickname	string	no	3 to 20 characters; pattern ^[\p{L}\p{N} _.-]+$
locale	string	no	Defaults to the site’s first locale

ServerPlayer

Property	Type	Required	Description
id	string (uuid)	yes
externalId	string	yes
nickname	string	yes
locale	string	yes
hasAccount	boolean	yes	True once the player linked an email on your site
createdAt	string (date-time)	yes
lastSeenAt	string (date-time)	yes