# Filudi developer docs

How a game runs on filudi.com and on portals, the SDK and API references, and how a portal builds on the Filudi API.

Four sections. Read the one that matches what you build; the references serve both.

- [Games](/docs/games/): from the invitation to a version under review, and everything a game can do on filudi.com and on portals.
- [SDK](/docs/sdk/): `@filudi/game-sdk`, one page per module, with the rules the host applies.
- [Portals](/docs/portals/): the three ways to run a site on the catalog, approval, domains, server keys.
- [API reference](/docs/api/): every route of the API, generated from the file the API runs on.

## Reading a page

Code samples sit in the right column on a wide screen and under the text on a narrow one. The language tabs
switch every sample on the site at once; the choice is kept in your browser.

<CodePanel title="Initialise the SDK">
  <Fragment slot="javascript">
    ```js
    import { sdk } from '@filudi/game-sdk';

    const { player, locale } = await sdk.init({ gameId: 'gloop' });
    sdk.ready();
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import { sdk, type InitResult } from '@filudi/game-sdk';

    const result: InitResult = await sdk.init({ gameId: 'gloop' });
    sdk.ready();
    ```

  </Fragment>
</CodePanel>

Every page is also served as Markdown: add `index.md` to its address. [`/llms.txt`](/llms.txt) lists every page
and [`/llms-full.txt`](/llms-full.txt) holds them all, for an agent that reads the docs in one go.

Source: https://developers.filudi.com/docs/

---

# API reference

Every route of the Filudi API with its parameters, bodies, responses and request samples, generated from openapi.yaml.

Every route of the API, grouped by tag, with parameters, request bodies, responses and samples in curl,
JavaScript and Python. The reference pages are generated at build time from `apps/api/openapi.yaml`, the
file the API runs on, so what you read here is what the API answers.

Start with the introduction pages, then the group that matches what you build.

- [Authentication](/docs/api/authentication/): the four credentials and where each one is valid.
- [Errors](/docs/api/errors/): the `{ error, message }` shape and every code.
- [Rate limits](/docs/api/rate-limits/): what is limited, by what, and the 429 answer.
- [Versioning](/docs/api/versioning/): the `/v1` prefix and how the API changes.
- [CORS and origins](/docs/api/cors-and-origins/): which origins may call the API from a browser and frame a game.

The reference itself:

- [SDK](/docs/api/reference/sdk/): what a game or a hub calls with a player or game token: players, sessions,
  saves, leaderboards, events.
- [Catalog](/docs/api/reference/catalog/) and [Bundles](/docs/api/reference/bundles/): public, cacheable.
- [Account](/docs/api/reference/account/): sign-in by link, code or password, export, deletion.
- [Community](/docs/api/reference/community/) and [Feedback](/docs/api/reference/feedback/): ratings, comments,
  bug reports.
- [Console](/docs/api/reference/console/): sign-in to the developer console, invitations, sessions.
- [Admin](/docs/api/reference/admin/): the console API, for developers and staff, on the session cookie.
- [Server](/docs/api/reference/server/): for portal backends, on a server key.
- [Schemas](/docs/api/reference/schemas/): every named object the routes read or answer.

A route heading is a link: `/docs/api/reference/sdk/#post-v1-sdk-game-tokens` opens
`POST /v1/sdk/game-tokens`. The anchor is the method and the path, lowercase, with dashes.

Source: https://developers.filudi.com/docs/api/

---

# Authentication

The four credentials of the Filudi API, where each one is valid, and how it travels.

Four credentials open the API. Each one opens one group of routes and nothing else. The reference says, under
every route, which one it takes.

| Credential      | Looks like                    | Sent as                                   | Valid on                                                  |
| --------------- | ----------------------------- | ----------------------------------------- | --------------------------------------------------------- |
| Player token    | `fp1.<payload>.<hmac>`        | `Authorization: Bearer`                   | `/v1/sdk/*`, `/v1/account/*`, ratings, comments, feedback |
| Game token      | `fg1.<payload>.<hmac>`        | `Authorization: Bearer`                   | Five `/v1/sdk/*` routes, for its own game                 |
| Console session | cookie `filudi_console`       | the cookie, with `credentials: 'include'` | `/v1/console/*`, `/v1/admin/*`                            |
| Server key      | `fsk_<site slug>_<32 base62>` | `Authorization: Bearer`                   | `/v1/server/*`                                            |

## Player token

A player is a guest from the first page view. `POST /v1/sdk/players` creates one for a site and answers
`{ player, token }`; the magic link, its 6-digit code and the password sign-in answer the same shape for an
account. The token has no expiry. It opens the player's saves, scores, events, profile and the whole
`/v1/account/*` group, deletion included.

<CodePanel title="Create a guest and read it back">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/players' \
      -H 'content-type: application/json' \
      -d '{ "site": "filudi", "locale": "en" }'

    curl 'https://api.filudi.com/v1/sdk/players/me' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const created = await fetch('https://api.filudi.com/v1/sdk/players', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ site: 'filudi', locale: 'en' }),
    });
    const { token } = await created.json();
    localStorage.setItem('filudi:player:filudi', token);

    const me = await fetch('https://api.filudi.com/v1/sdk/players/me', {
      headers: { authorization: `Bearer ${token}` },
    });
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # From a server, every visitor shares your IP and the 21st guest of the hour is refused.
    # Create guests in the browser, or use a server key and POST /v1/server/players.
    created = requests.post(
        'https://api.filudi.com/v1/sdk/players',
        json={'site': 'filudi', 'locale': 'en'},
    )
    token = created.json()['token']
    me = requests.get(
        'https://api.filudi.com/v1/sdk/players/me',
        headers={'authorization': f'Bearer {token}'},
    )
    ```

  </Fragment>
</CodePanel>

Rules for the token:

- It lives in the browser, in `localStorage`. `PlayerClient` of `@filudi/hub-core` uses the key
  `filudi:player:<site>`. Never a cookie, never a URL, never a log.
- It never enters a game frame. A game gets a game token instead.
- A 401 means the API refused it: forget it and create a new guest. When the owner rotates the API's token
  secret, every player is signed out this way.
- A player belongs to one site. The same email on two sites makes two players.

## Game token

A game is untrusted. The page that frames it exchanges the player token with `POST /v1/sdk/game-tokens { game }`
and passes the result in the `filudi:init` message of the handshake. The token is `fg1`, valid 24 hours, and
opens these routes for the game it names:

| Route                                         | With a game token                                          |
| --------------------------------------------- | ---------------------------------------------------------- |
| `GET /v1/sdk/players/me`                      | Allowed; `emailMasked` is null and `hasPassword` false     |
| `GET`, `PUT`, `DELETE /v1/sdk/saves/{gameId}` | Its own game                                               |
| `POST /v1/sdk/sessions`                       | Its own game                                               |
| `/v1/sdk/leaderboards/{gameId}/*`             | Its own game                                               |
| `POST /v1/sdk/events`                         | An item that names another game refuses the batch with 403 |

Every other route answers 401 to a game token. The exchange is limited to 240 per player per hour. A hub sends
a fresh token to the frame every 12 hours as `filudi:token`; the SDK swaps it without a reload. A portal backend
gets the same token for one of its players with `POST /v1/server/game-tokens`.

<CodePanel title="Exchange a player token for a game token">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/game-tokens' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{ "game": "gloop" }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/sdk/game-tokens', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({ game: 'gloop' }),
    });
    const { token, expiresAt } = await response.json();
    // Post `token` to the frame in filudi:init; keep playerToken on your origin.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # A backend uses its server key instead: POST /v1/server/game-tokens { playerId, game }.
    response = requests.post(
        'https://api.filudi.com/v1/server/game-tokens',
        headers={'authorization': f'Bearer {site_key}'},
        json={'playerId': player_id, 'game': 'gloop'},
    )
    game_token = response.json()['token']
    ```

  </Fragment>
</CodePanel>

## Console session

The developer console and the back office sign in with `POST /v1/console/sign-in` (email, password), then
`POST /v1/console/sign-in/totp` when the account has an authenticator. The answer sets the cookie
`filudi_console`: HttpOnly, Secure, SameSite Strict, host-only on the API, 14 days. The browser sends it on its
own; a script adds `credentials: 'include'` to each `fetch`.

Every non-GET request under `/v1/console/*` and `/v1/admin/*` must carry an `Origin` header listed in the
API's console origins (developers.filudi.com and admin.filudi.com). A browser sets it. A request without one,
or with another, answers 403 `forbidden`.

Staff without an authenticator gets 403 on every `/v1/admin/*` route except `GET /v1/admin/me`. A staff member
who opens an impersonation gets a second cookie, `filudi_impersonation`, valid one hour; a request with the
header `X-Filudi-Impersonation: 1` is read from that cookie instead.

<CodePanel title="Sign in and read the account">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/sign-in' \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -c cookies.txt \
      -d '{ "email": "you@example.com", "password": "string" }'

    curl 'https://api.filudi.com/v1/console/me' -b cookies.txt
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const signIn = await fetch('https://api.filudi.com/v1/console/sign-in', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ email, password }),
    });
    const { totpRequired, me } = await signIn.json();
    // totpRequired: finish with POST /v1/console/sign-in/totp { code }

    const account = await fetch('https://api.filudi.com/v1/console/me', { credentials: 'include' });
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # The console API is made for a browser. A script keeps the cookie in a session.
    session = requests.Session()
    session.headers['origin'] = 'https://developers.filudi.com'
    session.post(
        'https://api.filudi.com/v1/console/sign-in',
        json={'email': 'you@example.com', 'password': password},
    ).raise_for_status()
    me = session.get('https://api.filudi.com/v1/console/me').json()
    ```

  </Fragment>
</CodePanel>

## Server key

A portal backend calls `/v1/server/*` with a key created in the console, under the site, Keys. The key is
`fsk_<site slug>_<32 base62 characters>`, shown once; the API stores a hash and the console shows the first 12
characters. Each key carries scopes (`catalog`, `players`, `tokens`, `leaderboards`, `stats`) and each route says
which one it needs. 600 requests a minute per key; over that, 429 with `Retry-After`. Only an approved site has
keys, and a revoked key answers 403.

A server key never reaches a browser: `/v1/server/*` sends no CORS headers, so a page cannot call it. The key
sits in your backend's environment.

<CodePanel title="Read the catalog with a server key">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/server/catalog?locale=en' \
      -H "authorization: Bearer $FILUDI_SITE_KEY"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // Node, in your backend. siteKey comes from the environment.
    const response = await fetch('https://api.filudi.com/v1/server/catalog?locale=en', {
      headers: { authorization: `Bearer ${siteKey}` },
    });
    const catalog = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import os
    import requests

    response = requests.get(
        'https://api.filudi.com/v1/server/catalog',
        params={'locale': 'en'},
        headers={'authorization': f"Bearer {os.environ['FILUDI_SITE_KEY']}"},
    )
    catalog = response.json()
    ```

  </Fragment>
</CodePanel>

## Public routes

`GET /v1/catalog/{site}`, `GET /v1/catalog/{site}/games/{slug}`, the reviews of a game, the bundle and media
files, `POST /v1/sdk/players`, `POST /v1/feedback`, `POST /v1/console/invitation-requests` and the health routes
take no credential. A few routes accept a player token and answer without one too; the reference marks them
"Credential, optional".

Source: https://developers.filudi.com/docs/api/authentication/

---

# CORS and origins

Which origins may call the Filudi API from a browser and frame a game, how a site's domains join that list, and what a game origin may do.

A browser call reaches the API only from an origin the API allows. The same list is the `frame-ancestors` of
every game bundle: an origin that may call the API may frame a game, and no other.

## The list

The allowed origins are the union of:

- `https://<domain>` for every entry of `domains` of every approved site. A pending site has no origin, and a
  proposed domain (`pendingDomains`) joins the list once staff approves it.
- The hub origins the API is started with (`HUB_URLS`): filudi.com, the playground and the local ports of the
  monorepo, `http://localhost:4321` and `http://localhost:5173`.
- The console origins (`CONSOLE_URLS`), for `/v1/console/*` and `/v1/admin/*` only, with credentials.

Each API pod reloads the site domains every 60 seconds. A domain approved in the back office works within a
minute, on every pod, without a redeploy.

`localhost` is never a site domain. For local work, run the API from the monorepo, which allows the two local
ports above, or add your port to `HUB_URLS` on that API.

## Credentials and the console

`/v1/console/*` and `/v1/admin/*` answer the console origins with `Access-Control-Allow-Credentials: true`,
so the `filudi_console` cookie travels with `credentials: 'include'`. Every non-GET request there must carry an
`Origin` from that list; otherwise 403 `forbidden`. A browser sets `Origin` on its own. A `curl` adds it by hand.

## Game origins

Each live game runs on its own origin, `https://<slug>.<play domain>`. That origin gets CORS on the five
routes a game token opens (`GET /v1/sdk/players/me`, `/v1/sdk/saves/{gameId}`, `POST /v1/sdk/sessions`,
`/v1/sdk/leaderboards/{gameId}/*`, `POST /v1/sdk/events`) and on nothing else. A game cannot read a fresh
guest token, a sign-in answer, a rating or a feedback route from its frame.

A bundle answers with a Content Security Policy that lets it fetch its own origin and the API only, with no
remote script and no frame. `frame-ancestors` lists the allowed origins, so your page frames a game only once
your domain is approved.

## Server routes

`/v1/server/*` sends no CORS headers at all. A browser cannot call it, which is the point: the server key stays
in your backend. Call these routes from your servers and hand the browser a player token
(`POST /v1/server/players/{playerId}/tokens`) or a game token (`POST /v1/server/game-tokens`) over your own
authenticated channel.

## Your page's policy

Your pages send a CSP of their own. The one that lets a frame load and the page call the API:

```
frame-src https://play.filudi.com https://*.<play domain>
connect-src 'self' https://api.filudi.com
img-src 'self' data: https://play.filudi.com
media-src https://play.filudi.com
```

Never serve a bundle from your own origin: the frame has `allow-same-origin`, so a bundle on your origin could
read your `localStorage`, where the player's token sits. `GameFrame` throws on a bundle from the page's origin.

Source: https://developers.filudi.com/docs/api/cors-and-origins/

---

# Errors

The error body of the Filudi API, its nine codes and the status of each, and the two routes that answer another shape.

Every error is JSON with two fields and sometimes a third:

```json
{
  "error": "invalid",
  "message": "nickname: 3 to 20 characters.",
  "details": { "field": "nickname" }
}
```

`error` is one of nine codes. `message` is written for the developer who reads the response, in English, and
says what failed. `details` is present when the API has something structured to add, such as the field at
fault.

<CodePanel title="Read an error">
  <Fragment slot="curl">

    ```sh
    curl -s -o body.json -w '%{http_code}\n' \
      -X PATCH 'https://api.filudi.com/v1/sdk/players/me' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{ "nickname": "a" }'
    cat body.json
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/sdk/players/me', {
      method: 'PATCH',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({ nickname: 'a' }),
    });
    if (!response.ok) {
      const { error, message, details } = await response.json();
      if (error === 'unauthorized') forgetToken();
      if (error === 'rate_limited') waitSeconds(Number(response.headers.get('retry-after')));
      console.warn(error, message, details);
    }
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.patch(
        'https://api.filudi.com/v1/sdk/players/me',
        headers={'authorization': f'Bearer {player_token}'},
        json={'nickname': 'a'},
    )
    if not response.ok:
        body = response.json()
        print(response.status_code, body['error'], body['message'])
        if body['error'] == 'rate_limited':
            retry_after = int(response.headers['retry-after'])
    ```

  </Fragment>
</CodePanel>

## Codes

| Code           | Status | When                                                                                                                           |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `invalid`      | 400    | The body or a parameter breaks the schema. `message` names the field                                                           |
| `unauthorized` | 401    | No credential, or one the API refuses. For a player token: forget it and create a new guest                                    |
| `forbidden`    | 403    | The credential is valid and does not open this action: another game's token, a role, a scope, an origin                        |
| `not_found`    | 404    | Unknown resource, or one your credential may not see. An unknown site slug and a game outside a site's catalog answer this too |
| `conflict`     | 409    | The state refuses the change: a slug taken, a version already live, a quota reached                                            |
| `too_large`    | 413    | The body is over the route's limit (64 kB for a save or an event batch)                                                        |
| `rate_limited` | 429    | Too many requests. `Retry-After` says how many seconds to wait; see [Rate limits](/docs/api/rate-limits/)                      |
| `unavailable`  | 503    | A dependency is down, usually Redis. Retry in a few seconds; `Retry-After` is set when the API knows                           |
| `internal`     | 500    | An unexpected failure. The API logged it                                                                                       |

The write routes of the admin API answer 400 `invalid`, 403 `forbidden`, 404 `not_found` and 409 `conflict`
with this shape even where the reference lists only the success code.

## Two routes with another body

`PUT /v1/sdk/saves/{gameId}` answers 409 with the server's copy of the save, not an error: `{ gameId, version,
etag, bytes, updatedAt, data }`, with `version` 0 and `data` null when nothing is stored yet. Take it, merge if
the game can, and write again with `If-Match` set to that version.

`POST /v1/sdk/leaderboards/{gameId}/{board}/scores` answers 400 with `{ error: "invalid", reason, message }`.
`reason` is one of `bounds`, `signature`, `session`, `board`, `nonce`, `clock`, `meta`, so a game logs why a
score was refused.

## Details worth reading

- `details.field: "current"` on a 401 of `PUT /v1/account/password` and `PUT /v1/console/password`: the
  session or token is fine, the current password is wrong. Keep the token.
- The issue code `game_host` on a 400 of `POST /v1/admin/sites` and its PATCH: a domain is on or under the
  play domain, where no site may run.
- A 403 of `PUT /v1/admin/sites/{siteId}/catalog/{gameId}` carries in `message` why the site may not list the
  game: pending, no live version, or `first_party` on a site that is not first-party.

Source: https://developers.filudi.com/docs/api/errors/

---

# Rate limits

What the Filudi API limits, by IP, player, email or key, and how a client reads the 429 answer.

Limits live in Redis and count per IP, per player, per email or per key, depending on the route. Over a limit
the API answers 429 `rate_limited` with a `Retry-After` header in seconds. When Redis is down, a limited write
route answers 503 `unavailable` instead of guessing.

## Per route

| Route                                                  | Limit                                                                                                        |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `POST /v1/sdk/players`                                 | 20 per hour per IP. Create guests in the browser, where each visitor has their own IP                        |
| `POST /v1/sdk/game-tokens`                             | 240 per player per hour                                                                                      |
| `POST /v1/sdk/leaderboards/{gameId}/{board}/scores`    | `ratePerMinute` of the board, 10 by default; a nonce is accepted once per session                            |
| `POST /v1/sdk/events`                                  | 50 items per batch, 64 kB per body                                                                           |
| `PUT /v1/sdk/games/{gameId}/rating`                    | 60 ratings per player per hour                                                                               |
| `POST /v1/sdk/games/{gameId}/comments`                 | 5 comments per player per hour                                                                               |
| `PATCH /v1/sdk/comments/{commentId}`                   | 30 edits per player per hour                                                                                 |
| `POST /v1/account/magic-link`                          | 3 links per email per hour                                                                                   |
| `POST /v1/account/magic-link/consume-code`             | 20 attempts per IP per hour; the fifth wrong code burns the link                                             |
| `POST /v1/account/sign-in`, `POST /v1/console/sign-in` | Attempts counted per email and per IP; unknown email and wrong password answer the same 401 in the same time |
| `POST /v1/feedback`                                    | 5 per IP per hour and 10 per player per day                                                                  |
| `POST /v1/console/invitation-requests`                 | 5 per IP per day                                                                                             |
| `/v1/server/*`                                         | 600 requests a minute per key; no IP limit                                                                   |

The admin API has no request limit beyond the quotas of the data itself: 10 pending games and 3 pending sites
per account, 20 keys per site, 10 proposed domains, 50 grants per invitation.

## What a client does

Read `Retry-After` and wait that long before the same request. Do not retry a 429 in a loop: the counter does
not reset on refused requests.

```js
async function withRetry(request) {
  const response = await request();
  if (response.status !== 429) return response;
  const seconds = Number(response.headers.get('retry-after') ?? '1');
  await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  return request();
}
```

`@filudi/hub-core` and `@filudi/game-sdk` follow this rule on their own. A score refused for rate reasons comes
back to the SDK as `rejected`, never as an exception.

## Caches you can lean on

Public reads carry `Cache-Control` and an `ETag`. `GET /v1/catalog/{site}` is `public, max-age=300,
stale-while-revalidate=600`; the reviews of a game are `public, max-age=60`; a leaderboard top is `public,
max-age=30`. Send `If-None-Match` and a 304 costs nothing. The statistics routes are cached 60 s in Redis per
set of filters, so two identical calls in a minute return the same numbers.

Source: https://developers.filudi.com/docs/api/rate-limits/

---

# Account routes

The account routes of games-api, with parameters, bodies, responses and request samples.

Generated from `openapi.yaml` of games-api 0.7.0: 8 routes.

- [`POST /v1/account/magic-link`](#post-v1-account-magic-link): Email a sign-in link
- [`POST /v1/account/magic-link/consume`](#post-v1-account-magic-link-consume): Exchange the link token for an account player token
- [`POST /v1/account/magic-link/consume-code`](#post-v1-account-magic-link-consume-code): Exchange the code of a sign-in email for an account player token
- [`POST /v1/account/sign-in`](#post-v1-account-sign-in): Sign in with email and password
- [`PUT /v1/account/password`](#put-v1-account-password): Set or change the account's password
- [`DELETE /v1/account/password`](#delete-v1-account-password): Remove the password; the account signs in by link or code only
- [`GET /v1/account/export`](#get-v1-account-export): Everything stored about the player
- [`DELETE /v1/account`](#delete-v1-account): Delete the player and all data

<RouteHeading id="post-v1-account-magic-link" method="POST" path="/v1/account/magic-link" />

<CodePanel title="POST /v1/account/magic-link">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/account/magic-link' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "email": "you@example.com",
      "redirect": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/account/magic-link', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        email: 'you@example.com',
        redirect: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.post(
        'https://api.filudi.com/v1/account/magic-link',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'email': 'you@example.com',
            'redirect': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Email a sign-in link**

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `redirect` | string | no | Path on the site to return to after verification |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 202 | none | Sent, or silently not sent for an unknown reason the client must not learn. |
| 403 | none | Accounts are off for this site. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

<RouteHeading id="post-v1-account-magic-link-consume" method="POST" path="/v1/account/magic-link/consume" />

<CodePanel title="POST /v1/account/magic-link/consume">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/account/magic-link/consume' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "token": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/account/magic-link/consume', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        token: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.post(
        'https://api.filudi.com/v1/account/magic-link/consume',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'token': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Exchange the link token for an account player token**

With a guest token, the API merges the guest into the account player (ADR 0005).

Credential, optional: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here. Without a token the answer is the anonymous one.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ConsumeResponse](/docs/api/reference/schemas/#schema-consumeresponse) | Account player and token. |
| 400 | none | Link expired, used or unknown. |
| 403 | none | Accounts are off for this site. |

<RouteHeading id="post-v1-account-magic-link-consume-code" method="POST" path="/v1/account/magic-link/consume-code" />

<CodePanel title="POST /v1/account/magic-link/consume-code">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/account/magic-link/consume-code' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "email": "you@example.com",
      "code": "string",
      "site": "filudi"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/account/magic-link/consume-code', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        email: 'you@example.com',
        code: 'string',
        site: 'filudi',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.post(
        'https://api.filudi.com/v1/account/magic-link/consume-code',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'email': 'you@example.com',
            'code': 'string',
            'site': 'filudi',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Exchange the code of a sign-in email for an account player token**

Same effect as consuming the link (ADR 0011). The page that asked for the link sends the 6-digit
code the email shows; spaces are ignored. The API checks it against the most recent link of this
email on the site that is neither consumed nor expired. The fifth wrong code burns that link.
The site is the token's; without a token, `site` names it. An invalid or dead bearer counts as no
token, and `site` is then required. `redirect` is never set: it travels inside the link, not with
the code. 20 attempts per IP per hour.

Credential, optional: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here. Without a token the answer is the anonymous one.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `code` | string | yes | Six digits, "123456" or "123 456"; pattern `^[0-9 ]{6,7}$` |
| `site` | string | no | Site slug. Required without a player token; with one, it must be the token's site |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ConsumeResponse](/docs/api/reference/schemas/#schema-consumeresponse) | Account player and token. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | "This code is wrong, expired or already used. Ask for a new email." Also a missing or mismatched `site`, and an account scheduled for deletion. |
| 403 | none | Accounts are off for this site. |
| 404 | none | Unknown site slug. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |
| 503 | none | Redis is down; the rate limit cannot be checked. |

<RouteHeading id="post-v1-account-sign-in" method="POST" path="/v1/account/sign-in" />

<CodePanel title="POST /v1/account/sign-in">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/account/sign-in' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "email": "you@example.com",
      "password": "string",
      "site": "filudi"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/account/sign-in', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        email: 'you@example.com',
        password: 'string',
        site: 'filudi',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.post(
        'https://api.filudi.com/v1/account/sign-in',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'email': 'you@example.com',
            'password': 'string',
            'site': 'filudi',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Sign in with email and password**

For an account that set a password (ADR 0011). With a guest token of the site, the API merges the
guest into the account as consume does. An unknown email, an account without a password and a
wrong password get the same 401 in the same time. The site is the token's; without a token,
`site` names it. An invalid or dead bearer counts as no token, and `site` is then required.
10 attempts per email per 15 minutes and 30 per IP per hour, right or wrong.

Credential, optional: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here. Without a token the answer is the anonymous one.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `password` | string | yes | A password over 128 characters answers 401; the 8 to 128 rule applies when it is set; 1 to 1024 characters; write only |
| `site` | string | no | Site slug. Required without a player token; with one, it must be the token's site |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ConsumeResponse](/docs/api/reference/schemas/#schema-consumeresponse) | Account player and token. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | A missing or mismatched `site`, or an account scheduled for deletion. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | "Email or password is wrong.". |
| 403 | none | Accounts are off for this site. |
| 404 | none | Unknown site slug. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |
| 503 | none | Redis is down; the rate limit cannot be checked. |

<RouteHeading id="put-v1-account-password" method="PUT" path="/v1/account/password" />

<CodePanel title="PUT /v1/account/password">
  <Fragment slot="curl">

    ```sh
    curl -X PUT 'https://api.filudi.com/v1/account/password' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "password": "string",
      "current": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/account/password', {
      method: 'PUT',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        password: 'string',
        current: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.put(
        'https://api.filudi.com/v1/account/password',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'password': 'string',
            'current': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Set or change the account's password**

Account players only (ADR 0011). 8 to 128 characters after NFC normalization, not equal to the
account's email (case-insensitive), no other rule. When a password exists, `current` is required
and checked. 20 attempts per player per hour, right or wrong. Other devices stay signed in.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `password` | string | yes | 8 to 128 characters; write only |
| `current` | string | no | Required when the account has a password; 1 to 128 characters; write only |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Saved. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token, or `current` is wrong; then the body carries `details: { field: "current" }`. |
| 403 | none | A guest: "Add your email first: a password needs an account.". |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |
| 503 | none | Redis is down; the rate limit cannot be checked. |

<RouteHeading id="delete-v1-account-password" method="DELETE" path="/v1/account/password" />

<CodePanel title="DELETE /v1/account/password">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/account/password' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/account/password', {
      method: 'DELETE',
      headers: { authorization: `Bearer ${playerToken}` },
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.delete(
        'https://api.filudi.com/v1/account/password',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Remove the password; the account signs in by link or code only**

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Removed. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 403 | none | A guest has no password. |

<RouteHeading id="get-v1-account-export" method="GET" path="/v1/account/export" />

<CodePanel title="GET /v1/account/export">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/account/export' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/account/export', {
      headers: { authorization: `Bearer ${playerToken}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.get(
        'https://api.filudi.com/v1/account/export',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Everything stored about the player**

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [PlayerExport](/docs/api/reference/schemas/#schema-playerexport) | JSON file. Headers: `Content-Disposition`. |

<RouteHeading id="delete-v1-account" method="DELETE" path="/v1/account" />

<CodePanel title="DELETE /v1/account">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/account' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/account', {
      method: 'DELETE',
      headers: { authorization: `Bearer ${playerToken}` },
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.delete(
        'https://api.filudi.com/v1/account',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Delete the player and all data**

Scheduled; `cron:purge` removes the rows within 24 hours. The token stops working now.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 202 | none | Deletion scheduled. |

Source: https://developers.filudi.com/docs/api/reference/account/

---

# Admin routes

The admin routes of games-api, with parameters, bodies, responses and request samples.

Generated from `openapi.yaml` of games-api 0.7.0: 93 routes.

- [`GET /v1/admin/me`](#get-v1-admin-me): Who am I and what can I edit
- [`GET /v1/admin/accounts`](#get-v1-admin-accounts): Staff only. Accounts, newest first
- [`GET /v1/admin/accounts/{accountId}`](#get-v1-admin-accounts-accountid): Staff only. One account with its memberships
- [`PATCH /v1/admin/accounts/{accountId}`](#patch-v1-admin-accounts-accountid): Staff only. Change name, email, flags, or disable the account
- [`POST /v1/admin/accounts/{accountId}/reset-link`](#post-v1-admin-accounts-accountid-reset-link): Staff only. Email the account a password reset link
- [`DELETE /v1/admin/accounts/{accountId}/totp`](#delete-v1-admin-accounts-accountid-totp): Staff only. Remove the account's TOTP
- [`DELETE /v1/admin/accounts/{accountId}/sessions`](#delete-v1-admin-accounts-accountid-sessions): Staff only. Revoke every session of the account
- [`POST /v1/admin/accounts/{accountId}/impersonate`](#post-v1-admin-accounts-accountid-impersonate): Staff only. Open a one-hour session on a developer's account
- [`GET /v1/admin/invitations`](#get-v1-admin-invitations): Staff only. Invitations, newest first
- [`POST /v1/admin/invitations`](#post-v1-admin-invitations): Staff only. Invite an email address
- [`DELETE /v1/admin/invitations/{invitationId}`](#delete-v1-admin-invitations-invitationid): Staff only. Revoke an invitation; its link stops working
- [`POST /v1/admin/invitations/{invitationId}/resend`](#post-v1-admin-invitations-invitationid-resend): Staff only. Send the invitation email again with a fresh 7-day token
- [`GET /v1/admin/invitation-requests`](#get-v1-admin-invitation-requests): Staff only. Requests from the form on developers.filudi.com, newest first
- [`PATCH /v1/admin/invitation-requests/{requestId}`](#patch-v1-admin-invitation-requests-requestid): Staff only. Dismiss a request
- [`GET /v1/admin/approvals`](#get-v1-admin-approvals): Staff only. Everything that waits for approval, oldest first
- [`GET /v1/admin/sites`](#get-v1-admin-sites): Sites the account can see; an account with no site membership gets an empty list
- [`POST /v1/admin/sites`](#post-v1-admin-sites): Create a site
- [`GET /v1/admin/sites/{siteId}`](#get-v1-admin-sites-siteid): One site
- [`PATCH /v1/admin/sites/{siteId}`](#patch-v1-admin-sites-siteid): Update policy, domains, locales, name
- [`POST /v1/admin/sites/{siteId}/approve`](#post-v1-admin-sites-siteid-approve): Staff only. Approve a pending site
- [`POST /v1/admin/sites/{siteId}/reject`](#post-v1-admin-sites-siteid-reject): Staff only. Send the owners a reason; the site stays pending
- [`POST /v1/admin/sites/{siteId}/domains/approve`](#post-v1-admin-sites-siteid-domains-approve): Staff only. Move proposed domains into the site's domains
- [`POST /v1/admin/sites/{siteId}/domains/reject`](#post-v1-admin-sites-siteid-domains-reject): Staff only. Remove proposed domains and send the owners the reason
- [`GET /v1/admin/sites/{siteId}/members`](#get-v1-admin-sites-siteid-members): Members of a site
- [`POST /v1/admin/sites/{siteId}/members`](#post-v1-admin-sites-siteid-members): Add a member by email
- [`DELETE /v1/admin/sites/{siteId}/members/{accountId}`](#delete-v1-admin-sites-siteid-members-accountid): Remove a member
- [`DELETE /v1/admin/sites/{siteId}/members/invitations/{invitationId}`](#delete-v1-admin-sites-siteid-members-invitations-invitationid): Withdraw an invitation
- [`GET /v1/admin/sites/{siteId}/keys`](#get-v1-admin-sites-siteid-keys): Server keys of a site, revoked ones included
- [`POST /v1/admin/sites/{siteId}/keys`](#post-v1-admin-sites-siteid-keys): Create a server key; the answer shows it once
- [`DELETE /v1/admin/sites/{siteId}/keys/{keyId}`](#delete-v1-admin-sites-siteid-keys-keyid): Revoke a server key
- [`GET /v1/admin/sites/{siteId}/categories`](#get-v1-admin-sites-siteid-categories): Categories of a site, in site order, with the number of games in each
- [`POST /v1/admin/sites/{siteId}/categories`](#post-v1-admin-sites-siteid-categories): Add a category at the end of the site order
- [`PUT /v1/admin/sites/{siteId}/categories/order`](#put-v1-admin-sites-siteid-categories-order): Reorder the categories
- [`GET /v1/admin/sites/{siteId}/categories/{slug}`](#get-v1-admin-sites-siteid-categories-slug): One category
- [`PATCH /v1/admin/sites/{siteId}/categories/{slug}`](#patch-v1-admin-sites-siteid-categories-slug): Update texts and icon
- [`DELETE /v1/admin/sites/{siteId}/categories/{slug}`](#delete-v1-admin-sites-siteid-categories-slug): Remove the category from the site, from its games and from the top menu
- [`GET /v1/admin/sites/{siteId}/tags`](#get-v1-admin-sites-siteid-tags): Tags of a site, in site order, with the number of games carrying each
- [`POST /v1/admin/sites/{siteId}/tags`](#post-v1-admin-sites-siteid-tags): Add a tag at the end of the site order
- [`PUT /v1/admin/sites/{siteId}/tags/order`](#put-v1-admin-sites-siteid-tags-order): Reorder the tags
- [`GET /v1/admin/sites/{siteId}/tags/{slug}`](#get-v1-admin-sites-siteid-tags-slug): One tag
- [`PATCH /v1/admin/sites/{siteId}/tags/{slug}`](#patch-v1-admin-sites-siteid-tags-slug): Update the titles
- [`DELETE /v1/admin/sites/{siteId}/tags/{slug}`](#delete-v1-admin-sites-siteid-tags-slug): Remove the tag from the site and from its games
- [`GET /v1/admin/sites/{siteId}/catalog`](#get-v1-admin-sites-siteid-catalog): Site catalog entries with every locale
- [`PUT /v1/admin/sites/{siteId}/catalog/order`](#put-v1-admin-sites-siteid-catalog-order): Reorder the catalog
- [`PUT /v1/admin/sites/{siteId}/catalog/{gameId}`](#put-v1-admin-sites-siteid-catalog-gameid): Add or update a game in the site catalog
- [`DELETE /v1/admin/sites/{siteId}/catalog/{gameId}`](#delete-v1-admin-sites-siteid-catalog-gameid): Remove a game from the site catalog
- [`POST /v1/admin/sites/{siteId}/publish`](#post-v1-admin-sites-siteid-publish): Make the catalog changes visible on the site front
- [`GET /v1/admin/games`](#get-v1-admin-games): Every game with its versions
- [`POST /v1/admin/games`](#post-v1-admin-games): Create a game
- [`GET /v1/admin/games/{gameId}`](#get-v1-admin-games-gameid): One game
- [`PATCH /v1/admin/games/{gameId}`](#patch-v1-admin-games-gameid): Update a game
- [`DELETE /v1/admin/games/{gameId}`](#delete-v1-admin-games-gameid): Delete a game and everything attached to it (staff only)
- [`POST /v1/admin/games/{gameId}/approve`](#post-v1-admin-games-gameid-approve): Staff only. Approve a pending game
- [`POST /v1/admin/games/{gameId}/reject`](#post-v1-admin-games-gameid-reject): Staff only. Send the owners a reason; the game stays pending
- [`GET /v1/admin/games/{gameId}/members`](#get-v1-admin-games-gameid-members): Members of a game
- [`POST /v1/admin/games/{gameId}/members`](#post-v1-admin-games-gameid-members): Add a member by email
- [`DELETE /v1/admin/games/{gameId}/members/{accountId}`](#delete-v1-admin-games-gameid-members-accountid): Remove a member
- [`DELETE /v1/admin/games/{gameId}/members/invitations/{invitationId}`](#delete-v1-admin-games-gameid-members-invitations-invitationid): Withdraw an invitation
- [`GET /v1/admin/games/{gameId}/stats`](#get-v1-admin-games-gameid-stats): One game's numbers across every site that lists it, for a range of UTC days
- [`POST /v1/admin/games/{gameId}/versions`](#post-v1-admin-games-gameid-versions): Start a version upload
- [`POST /v1/admin/games/{gameId}/media/{slot}`](#post-v1-admin-games-gameid-media-slot): Start a media upload
- [`DELETE /v1/admin/games/{gameId}/media/{slot}`](#delete-v1-admin-games-gameid-media-slot): Empty the slot
- [`POST /v1/admin/games/{gameId}/media/{slot}/finalize`](#post-v1-admin-games-gameid-media-slot-finalize): Check the uploaded file and put it in the slot
- [`POST /v1/admin/versions/{versionId}/finalize`](#post-v1-admin-versions-versionid-finalize): Unpack the uploaded zip into the bundle prefix
- [`POST /v1/admin/versions/{versionId}/activate`](#post-v1-admin-versions-versionid-activate): Make this version live; the previous live one goes back to draft (staff only)
- [`POST /v1/admin/versions/{versionId}/retire`](#post-v1-admin-versions-versionid-retire): Retire a version; its bundle stops being served (staff only)
- [`POST /v1/admin/versions/{versionId}/review`](#post-v1-admin-versions-versionid-review): Ask staff to review a draft and make it live
- [`POST /v1/admin/versions/{versionId}/review/reject`](#post-v1-admin-versions-versionid-review-reject): Staff only. Decline a review request and send the owners the reason
- [`GET /v1/admin/versions/{versionId}/preview`](#get-v1-admin-versions-versionid-preview): Signed URL to play a draft version for 1 hour
- [`GET /v1/admin/games/{gameId}/leaderboards`](#get-v1-admin-games-gameid-leaderboards): Boards of a game
- [`PUT /v1/admin/games/{gameId}/leaderboards`](#put-v1-admin-games-gameid-leaderboards): Replace the boards of a game
- [`GET /v1/admin/games/{gameId}/leaderboards/{board}/scores`](#get-v1-admin-games-gameid-leaderboards-board-scores): Scores for moderation
- [`POST /v1/admin/scores/{scoreId}`](#post-v1-admin-scores-scoreid): Unhide a score
- [`DELETE /v1/admin/scores/{scoreId}`](#delete-v1-admin-scores-scoreid): Hide a score
- [`GET /v1/admin/sites/{siteId}/players`](#get-v1-admin-sites-siteid-players): List the players of a site, with an optional search
- [`GET /v1/admin/players/{playerId}`](#get-v1-admin-players-playerid): Player detail with saves metadata and best scores
- [`DELETE /v1/admin/players/{playerId}`](#delete-v1-admin-players-playerid): Schedule deletion (GDPR request handled by support)
- [`GET /v1/admin/players/{playerId}/export`](#get-v1-admin-players-playerid-export): Export a player's data
- [`GET /v1/admin/sites/{siteId}/comments`](#get-v1-admin-sites-siteid-comments): Comments of a site for moderation, newest first
- [`DELETE /v1/admin/comments/{commentId}`](#delete-v1-admin-comments-commentid): Delete a comment for good
- [`POST /v1/admin/comments/{commentId}/hide`](#post-v1-admin-comments-commentid-hide): Hide a comment from every player route
- [`POST /v1/admin/comments/{commentId}/unhide`](#post-v1-admin-comments-commentid-unhide): Show a hidden comment again
- [`GET /v1/admin/sites/{siteId}/ratings`](#get-v1-admin-sites-siteid-ratings): Rating of every rated game of a site
- [`GET /v1/admin/sites/{siteId}/feedback`](#get-v1-admin-sites-siteid-feedback): Feedback of a site, newest first
- [`GET /v1/admin/feedback/{feedbackId}`](#get-v1-admin-feedback-feedbackid): One feedback message
- [`PATCH /v1/admin/feedback/{feedbackId}`](#patch-v1-admin-feedback-feedbackid): Change the status or the note
- [`DELETE /v1/admin/feedback/{feedbackId}`](#delete-v1-admin-feedback-feedbackid): Delete a feedback message for good
- [`GET /v1/admin/sites/{siteId}/events/today`](#get-v1-admin-sites-siteid-events-today): Counts since midnight UTC, live from the events table
- [`GET /v1/admin/sites/{siteId}/events/daily`](#get-v1-admin-sites-siteid-events-daily): Daily aggregates
- [`GET /v1/admin/sites/{siteId}/stats/overview`](#get-v1-admin-sites-siteid-stats-overview): The site dashboard numbers for a range of UTC days
- [`GET /v1/admin/sites/{siteId}/stats/games/{gameId}`](#get-v1-admin-sites-siteid-stats-games-gameid): One game's numbers on this site for a range of UTC days
- [`GET /v1/admin/sites/{siteId}/stats/web`](#get-v1-admin-sites-siteid-stats-web): Web audience from CausalIT (ADR 0009)
- [`GET /v1/admin/audit`](#get-v1-admin-audit): Audit log

<RouteHeading id="get-v1-admin-me" method="GET" path="/v1/admin/me" />

<CodePanel title="GET /v1/admin/me">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/me' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/me', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/me',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Who am I and what can I edit**

The one `/v1/admin/*` route that answers for staff without TOTP. `roles.admin` is true for staff with TOTP enabled.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ConsoleMe](/docs/api/reference/schemas/#schema-consoleme) | Identity. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |

<RouteHeading id="get-v1-admin-accounts" method="GET" path="/v1/admin/accounts" />

<CodePanel title="GET /v1/admin/accounts">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/accounts' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/accounts', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/accounts',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Accounts, newest first**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | no | Case-insensitive substring of the name, or an email matched by its hash; 2 to 100 characters |
| `cursor` | query | string | no | Opaque; the `nextCursor` of the previous page, with the same filters and sort; at most 200 characters |
| `limit` | query | integer | no | 1 to 500; default `100` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [AccountPage](/docs/api/reference/schemas/#schema-accountpage) | Accounts. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |

<RouteHeading id="get-v1-admin-accounts-accountid" method="GET" path="/v1/admin/accounts/{accountId}" />

<CodePanel title="GET /v1/admin/accounts/{accountId}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. One account with its memberships**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `accountId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [AccountAdmin](/docs/api/reference/schemas/#schema-accountadmin) | Account. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="patch-v1-admin-accounts-accountid" method="PATCH" path="/v1/admin/accounts/{accountId}" />

<CodePanel title="PATCH /v1/admin/accounts/{accountId}">
  <Fragment slot="curl">

    ```sh
    curl -X PATCH 'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "name": "string",
      "email": "you@example.com",
      "staff": true,
      "canCreateGames": true,
      "canCreatePortals": true,
      "disabled": true
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000', {
      method: 'PATCH',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        name: 'string',
        email: 'you@example.com',
        staff: true,
        canCreateGames: true,
        canCreatePortals: true,
        disabled: true,
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.patch(
        'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'name': 'string',
            'email': 'you@example.com',
            'staff': True,
            'canCreateGames': True,
            'canCreatePortals': True,
            'disabled': True,
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Change name, email, flags, or disable the account**

Disabling an account revokes its sessions. Every change writes an audit row.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `accountId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [AccountPatch](/docs/api/reference/schemas/#schema-accountpatch). At least one field; an empty body is a 400.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | [AccountName](/docs/api/reference/schemas/#schema-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 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [AccountAdmin](/docs/api/reference/schemas/#schema-accountadmin) | Account. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | The email is on another account. |

<RouteHeading id="post-v1-admin-accounts-accountid-reset-link" method="POST" path="/v1/admin/accounts/{accountId}/reset-link" />

<CodePanel title="POST /v1/admin/accounts/{accountId}/reset-link">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/reset-link' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/reset-link', {
      method: 'POST',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/reset-link',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Staff only. Email the account a password reset link**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `accountId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 202 | none | Sent. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="delete-v1-admin-accounts-accountid-totp" method="DELETE" path="/v1/admin/accounts/{accountId}/totp" />

<CodePanel title="DELETE /v1/admin/accounts/{accountId}/totp">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/totp' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/totp', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/totp',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Staff only. Remove the account's TOTP**

For a lost authenticator. A staff account loses its admin rights until it enrols again.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `accountId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Removed, or there was none. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="delete-v1-admin-accounts-accountid-sessions" method="DELETE" path="/v1/admin/accounts/{accountId}/sessions" />

<CodePanel title="DELETE /v1/admin/accounts/{accountId}/sessions">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/sessions' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/sessions', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/sessions',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Staff only. Revoke every session of the account**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `accountId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Revoked. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="post-v1-admin-accounts-accountid-impersonate" method="POST" path="/v1/admin/accounts/{accountId}/impersonate" />

<CodePanel title="POST /v1/admin/accounts/{accountId}/impersonate">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/impersonate' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/impersonate', {
      method: 'POST',
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/accounts/00000000-0000-0000-0000-000000000000/impersonate',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Open a one-hour session on a developer's account**

Sets the `filudi_impersonation` cookie; the console sends `X-Filudi-Impersonation: 1` to use it, the
admin tab keeps acting as the staff member. Every audit row written during it carries the developer
as `actor` and the staff member as `impersonator`. Refused on a staff account and on oneself.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `accountId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ImpersonationStarted](/docs/api/reference/schemas/#schema-impersonationstarted) | Where to open the console. Headers: `Set-Cookie` (`filudi_impersonation`). |
| 403 | none | Not staff, a staff account, or your own account. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-admin-invitations" method="GET" path="/v1/admin/invitations" />

<CodePanel title="GET /v1/admin/invitations">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/invitations' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/invitations', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/invitations',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Invitations, newest first**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | one of `"pending"`, `"accepted"`, `"revoked"`, `"expired"` | no | default `"pending"` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Invitation](/docs/api/reference/schemas/#schema-invitation)[] | Invitations. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |

<RouteHeading id="post-v1-admin-invitations" method="POST" path="/v1/admin/invitations" />

<CodePanel title="POST /v1/admin/invitations">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/invitations' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "email": "you@example.com",
      "staff": false,
      "canCreateGames": false,
      "canCreatePortals": false,
      "grants": [
        {
          "game": "00000000-0000-0000-0000-000000000000",
          "site": "00000000-0000-0000-0000-000000000000",
          "role": "owner"
        }
      ]
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/invitations', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        email: 'you@example.com',
        staff: false,
        canCreateGames: false,
        canCreatePortals: false,
        grants: [{
          game: '00000000-0000-0000-0000-000000000000',
          site: '00000000-0000-0000-0000-000000000000',
          role: 'owner',
        }],
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/invitations',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'email': 'you@example.com',
            'staff': False,
            'canCreateGames': False,
            'canCreatePortals': False,
            'grants': [{
                'game': '00000000-0000-0000-0000-000000000000',
                'site': '00000000-0000-0000-0000-000000000000',
                'role': 'owner',
            }],
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Invite an email address**

The `notify` service sends the link, valid 7 days. A pending invitation for the same email is revoked
first. An open invitation request for the email moves to `invited`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Request body

`application/json`, required. The body is a [InvitationInput](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-membershiprole) | yes | A member has every right of the owner except membership changes |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [Invitation](/docs/api/reference/schemas/#schema-invitation) | Invitation. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 409 | none | An account with that email exists. |

<RouteHeading id="delete-v1-admin-invitations-invitationid" method="DELETE" path="/v1/admin/invitations/{invitationId}" />

<CodePanel title="DELETE /v1/admin/invitations/{invitationId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/invitations/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/invitations/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/invitations/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Staff only. Revoke an invitation; its link stops working**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `invitationId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Revoked. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | Already accepted. |

<RouteHeading id="post-v1-admin-invitations-invitationid-resend" method="POST" path="/v1/admin/invitations/{invitationId}/resend" />

<CodePanel title="POST /v1/admin/invitations/{invitationId}/resend">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/invitations/00000000-0000-0000-0000-000000000000/resend' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/invitations/00000000-0000-0000-0000-000000000000/resend', {
      method: 'POST',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/invitations/00000000-0000-0000-0000-000000000000/resend',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Staff only. Send the invitation email again with a fresh 7-day token**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `invitationId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 202 | none | Sent. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | Accepted or revoked. |

<RouteHeading id="get-v1-admin-invitation-requests" method="GET" path="/v1/admin/invitation-requests" />

<CodePanel title="GET /v1/admin/invitation-requests">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/invitation-requests' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/invitation-requests', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/invitation-requests',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Requests from the form on developers.filudi.com, newest first**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | one of `"new"`, `"invited"`, `"dismissed"` | no | Default `new` |
| `cursor` | query | string | no | Opaque; the `nextCursor` of the previous page, with the same filters and sort; at most 200 characters |
| `limit` | query | integer | no | 1 to 500; default `100` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [InvitationRequestPage](/docs/api/reference/schemas/#schema-invitationrequestpage) | Requests. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |

<RouteHeading id="patch-v1-admin-invitation-requests-requestid" method="PATCH" path="/v1/admin/invitation-requests/{requestId}" />

<CodePanel title="PATCH /v1/admin/invitation-requests/{requestId}">
  <Fragment slot="curl">

    ```sh
    curl -X PATCH 'https://api.filudi.com/v1/admin/invitation-requests/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "status": "dismissed"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/invitation-requests/00000000-0000-0000-0000-000000000000', {
      method: 'PATCH',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        status: 'dismissed',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.patch(
        'https://api.filudi.com/v1/admin/invitation-requests/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'status': 'dismissed',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Dismiss a request**

The `invited` status is set by the API when an invitation is created for the email.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `requestId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | one of `"dismissed"` | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [InvitationRequest](/docs/api/reference/schemas/#schema-invitationrequest) | Request. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-admin-approvals" method="GET" path="/v1/admin/approvals" />

<CodePanel title="GET /v1/admin/approvals">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/approvals' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/approvals', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/approvals',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Everything that waits for approval, oldest first**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Approvals](/docs/api/reference/schemas/#schema-approvals) | Pending games, sites, domains and versions. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |

<RouteHeading id="get-v1-admin-sites" method="GET" path="/v1/admin/sites" />

<CodePanel title="GET /v1/admin/sites">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Sites the account can see; an account with no site membership gets an empty list**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Site](/docs/api/reference/schemas/#schema-site)[] | Sites. |

<RouteHeading id="post-v1-admin-sites" method="POST" path="/v1/admin/sites" />

<CodePanel title="POST /v1/admin/sites">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "slug": "gloop",
      "name": "string",
      "domains": [
        "string"
      ],
      "pendingDomains": [
        "string"
      ],
      "firstParty": true,
      "locales": [
        "string"
      ],
      "accountsAllowed": true,
      "personalizedAdsAllowed": true,
      "ageBand": "all",
      "cdnPullZoneId": "string",
      "navCategories": [
        "string"
      ],
      "otherSites": [
        {
          "name": "string",
          "url": "https://example.com/",
          "description": "string"
        }
      ],
      "causalitDomain": "string",
      "causalitReadKey": "string",
      "causalitWriteKey": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        slug: 'gloop',
        name: 'string',
        domains: ['string'],
        pendingDomains: ['string'],
        firstParty: true,
        locales: ['string'],
        accountsAllowed: true,
        personalizedAdsAllowed: true,
        ageBand: 'all',
        cdnPullZoneId: 'string',
        navCategories: ['string'],
        otherSites: [{
          name: 'string',
          url: 'https://example.com/',
          description: 'string',
        }],
        causalitDomain: 'string',
        causalitReadKey: 'string',
        causalitWriteKey: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/sites',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'slug': 'gloop',
            'name': 'string',
            'domains': ['string'],
            'pendingDomains': ['string'],
            'firstParty': True,
            'locales': ['string'],
            'accountsAllowed': True,
            'personalizedAdsAllowed': True,
            'ageBand': 'all',
            'cdnPullZoneId': 'string',
            'navCategories': ['string'],
            'otherSites': [{
                'name': 'string',
                'url': 'https://example.com/',
                'description': 'string',
            }],
            'causalitDomain': 'string',
            'causalitReadKey': 'string',
            'causalitWriteKey': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Create a site**

Staff, or an account with `canCreatePortals`; anyone else gets 403. A staff creation is approved at once.
A developer's site is created with `approvedAt` null and the creator as owner; staff approves it from the
Approvals screen. A developer writes `pendingDomains`, never `domains`. One account holds at most
3 pending sites (409). A reserved slug answers 400: `admin`, `api`, `play`, `developers`, `filudi`,
`www`, `static`. This route and PATCH answer 400 with issue code `game_host` when a domain is on or
under the play domain, the `PLAY_URL` host or the preview host (ADR 0013).

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | yes | pattern `^[a-z][a-z0-9-]{1,39}$` |
| `name` | string | yes | 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[] | yes | Lowercase BCP 47, unique, the first is the default; at least 1 item |
| `accountsAllowed` | boolean | no |  |
| `personalizedAdsAllowed` | boolean | no |  |
| `ageBand` | [AgeBand](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [Site](/docs/api/reference/schemas/#schema-site) | Created. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 409 | none | Slug taken, or the account already holds 3 pending sites. |

<RouteHeading id="get-v1-admin-sites-siteid" method="GET" path="/v1/admin/sites/{siteId}" />

<CodePanel title="GET /v1/admin/sites/{siteId}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**One site**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Site](/docs/api/reference/schemas/#schema-site) | Site. |

<RouteHeading id="patch-v1-admin-sites-siteid" method="PATCH" path="/v1/admin/sites/{siteId}" />

<CodePanel title="PATCH /v1/admin/sites/{siteId}">
  <Fragment slot="curl">

    ```sh
    curl -X PATCH 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "slug": "gloop",
      "name": "string",
      "domains": [
        "string"
      ],
      "pendingDomains": [
        "string"
      ],
      "firstParty": true,
      "locales": [
        "string"
      ],
      "accountsAllowed": true,
      "personalizedAdsAllowed": true,
      "ageBand": "all",
      "cdnPullZoneId": "string",
      "navCategories": [
        "string"
      ],
      "otherSites": [
        {
          "name": "string",
          "url": "https://example.com/",
          "description": "string"
        }
      ],
      "causalitDomain": "string",
      "causalitReadKey": "string",
      "causalitWriteKey": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000', {
      method: 'PATCH',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        slug: 'gloop',
        name: 'string',
        domains: ['string'],
        pendingDomains: ['string'],
        firstParty: true,
        locales: ['string'],
        accountsAllowed: true,
        personalizedAdsAllowed: true,
        ageBand: 'all',
        cdnPullZoneId: 'string',
        navCategories: ['string'],
        otherSites: [{
          name: 'string',
          url: 'https://example.com/',
          description: 'string',
        }],
        causalitDomain: 'string',
        causalitReadKey: 'string',
        causalitWriteKey: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.patch(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'slug': 'gloop',
            'name': 'string',
            'domains': ['string'],
            'pendingDomains': ['string'],
            'firstParty': True,
            'locales': ['string'],
            'accountsAllowed': True,
            'personalizedAdsAllowed': True,
            'ageBand': 'all',
            'cdnPullZoneId': 'string',
            'navCategories': ['string'],
            'otherSites': [{
                'name': 'string',
                'url': 'https://example.com/',
                'description': 'string',
            }],
            'causalitDomain': 'string',
            'causalitReadKey': 'string',
            'causalitWriteKey': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Update policy, domains, locales, name**

Owners and members of the site write `pendingDomains`; a domain works once staff approves it. `domains`
and `firstParty` are for staff (ADR 0015).

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [SiteInput](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Site](/docs/api/reference/schemas/#schema-site) | Updated. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |

<RouteHeading id="post-v1-admin-sites-siteid-approve" method="POST" path="/v1/admin/sites/{siteId}/approve" />

<CodePanel title="POST /v1/admin/sites/{siteId}/approve">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/approve' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/approve', {
      method: 'POST',
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/approve',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Approve a pending site**

Sets `approvedAt`. Its approved domains become allowed origins within 60 s; the owners get an email.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Site](/docs/api/reference/schemas/#schema-site) | Site. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | Already approved. |

<RouteHeading id="post-v1-admin-sites-siteid-reject" method="POST" path="/v1/admin/sites/{siteId}/reject" />

<CodePanel title="POST /v1/admin/sites/{siteId}/reject">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/reject' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "reason": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/reject', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        reason: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/reject',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'reason': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Staff only. Send the owners a reason; the site stays pending**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [RejectInput](/docs/api/reference/schemas/#schema-rejectinput).

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

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Reason sent. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | The site is approved. |

<RouteHeading id="post-v1-admin-sites-siteid-domains-approve" method="POST" path="/v1/admin/sites/{siteId}/domains/approve" />

<CodePanel title="POST /v1/admin/sites/{siteId}/domains/approve">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/domains/approve' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "domains": [
        "string"
      ]
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/domains/approve', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        domains: ['string'],
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/domains/approve',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'domains': ['string'],
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Move proposed domains into the site's domains**

Each listed domain must be in `pendingDomains`, else 400. The `game_host` rule of site creation applies.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `domains` | string[] | yes | at least 1 item |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Site](/docs/api/reference/schemas/#schema-site) | Site. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="post-v1-admin-sites-siteid-domains-reject" method="POST" path="/v1/admin/sites/{siteId}/domains/reject" />

<CodePanel title="POST /v1/admin/sites/{siteId}/domains/reject">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/domains/reject' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "domains": [
        "string"
      ],
      "reason": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/domains/reject', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        domains: ['string'],
        reason: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/domains/reject',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'domains': ['string'],
            'reason': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Remove proposed domains and send the owners the reason**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `domains` | string[] | yes | at least 1 item |
| `reason` | string | yes | 1 to 1000 characters |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Site](/docs/api/reference/schemas/#schema-site) | Site. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-admin-sites-siteid-members" method="GET" path="/v1/admin/sites/{siteId}/members" />

<CodePanel title="GET /v1/admin/sites/{siteId}/members">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Members of a site**

Owner of the site or staff. Invited emails without an account yet are listed with `invited` true.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Member](/docs/api/reference/schemas/#schema-member)[] | Members. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="post-v1-admin-sites-siteid-members" method="POST" path="/v1/admin/sites/{siteId}/members" />

<CodePanel title="POST /v1/admin/sites/{siteId}/members">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "email": "you@example.com",
      "role": "owner"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        email: 'you@example.com',
        role: 'owner',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'email': 'you@example.com',
            'role': 'owner',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Add a member by email**

Owner of the site or staff. An existing account gets the membership at once. An unknown email gets an
invitation that carries it; the membership exists once the invitation is accepted.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [MemberInput](/docs/api/reference/schemas/#schema-memberinput).

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes | at most 254 characters |
| `role` | [MembershipRole](/docs/api/reference/schemas/#schema-membershiprole) | yes | A member has every right of the owner except membership changes |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [Member](/docs/api/reference/schemas/#schema-member) | Member. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | Already a member. |

<RouteHeading id="delete-v1-admin-sites-siteid-members-accountid" method="DELETE" path="/v1/admin/sites/{siteId}/members/{accountId}" />

<CodePanel title="DELETE /v1/admin/sites/{siteId}/members/{accountId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Remove a member**

Owner of the site or staff. The last owner cannot be removed.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `accountId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Removed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | `conflict`: "A site keeps at least one owner.". |

<RouteHeading id="delete-v1-admin-sites-siteid-members-invitations-invitationid" method="DELETE" path="/v1/admin/sites/{siteId}/members/invitations/{invitationId}" />

<CodePanel title="DELETE /v1/admin/sites/{siteId}/members/invitations/{invitationId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members/invitations/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members/invitations/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/members/invitations/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Withdraw an invitation**

Owner of the site or staff. Removes this site from the invitation's grants; an invitation left with no grant is revoked.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `invitationId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Withdrawn. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | none | No pending invitation to this site has this id. |

<RouteHeading id="get-v1-admin-sites-siteid-keys" method="GET" path="/v1/admin/sites/{siteId}/keys" />

<CodePanel title="GET /v1/admin/sites/{siteId}/keys">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/keys' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/keys', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/keys',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Server keys of a site, revoked ones included**

Owner or member of the site, or staff. Approved sites only (409). The key itself is never returned again.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [SiteKey](/docs/api/reference/schemas/#schema-sitekey)[] | Keys. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | The site is not approved. |

<RouteHeading id="post-v1-admin-sites-siteid-keys" method="POST" path="/v1/admin/sites/{siteId}/keys" />

<CodePanel title="POST /v1/admin/sites/{siteId}/keys">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/keys' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "name": "string",
      "scopes": [
        "catalog"
      ]
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/keys', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        name: 'string',
        scopes: ['catalog'],
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/keys',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'name': 'string',
            'scopes': ['catalog'],
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Create a server key; the answer shows it once**

Owner or member of the site, or staff. Approved sites only. 20 keys per site at most, revoked ones included.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [SiteKeyInput](/docs/api/reference/schemas/#schema-sitekeyinput).

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | 1 to 60 characters |
| `scopes` | [SiteKeyScope](/docs/api/reference/schemas/#schema-sitekeyscope)[] | yes | at least 1 item; unique items |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [SiteKeyCreated](/docs/api/reference/schemas/#schema-sitekeycreated) | The key, shown once. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | The site is not approved, or already has 20 keys. |

<RouteHeading id="delete-v1-admin-sites-siteid-keys-keyid" method="DELETE" path="/v1/admin/sites/{siteId}/keys/{keyId}" />

<CodePanel title="DELETE /v1/admin/sites/{siteId}/keys/{keyId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/keys/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/keys/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/keys/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Revoke a server key**

The row stays with `revokedAt`; `/v1/server/*` answers 403 to the key from now on.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `keyId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Revoked, or already revoked. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-admin-sites-siteid-categories" method="GET" path="/v1/admin/sites/{siteId}/categories" />

<CodePanel title="GET /v1/admin/sites/{siteId}/categories">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Categories of a site, in site order, with the number of games in each**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Category](/docs/api/reference/schemas/#schema-category)[] | Categories. |

<RouteHeading id="post-v1-admin-sites-siteid-categories" method="POST" path="/v1/admin/sites/{siteId}/categories" />

<CodePanel title="POST /v1/admin/sites/{siteId}/categories">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "slug": "gloop",
      "icon": "puzzle",
      "texts": {
        "en": {
          "title": "string",
          "navTitle": "string",
          "description": "string"
        }
      }
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        slug: 'gloop',
        icon: 'puzzle',
        texts: {
          en: {
            title: 'string',
            navTitle: 'string',
            description: 'string',
          },
        },
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'slug': 'gloop',
            'icon': 'puzzle',
            'texts': {
                'en': {
                    'title': 'string',
                    'navTitle': 'string',
                    'description': 'string',
                },
            },
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Add a category at the end of the site order**

The default locale needs a title. A category slug never changes once created (ADR 0008).
Slugs the fronts use as routes are refused: `categories`, `game`, `games`, `search`, `account`, `privacy`,
`terms`, `cookies`, `stats`, `cmp`, `api`, `assets`, and every locale of the site.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | yes | On create only; ignored on PATCH; pattern `^[a-z][a-z0-9-]{0,39}$` |
| `icon` | [CategoryIcon](/docs/api/reference/schemas/#schema-categoryicon) or null | no |  |
| `texts` | object | yes | 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 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [Category](/docs/api/reference/schemas/#schema-category) | Created. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 409 | none | Slug taken on this site. |

<RouteHeading id="put-v1-admin-sites-siteid-categories-order" method="PUT" path="/v1/admin/sites/{siteId}/categories/order" />

<CodePanel title="PUT /v1/admin/sites/{siteId}/categories/order">
  <Fragment slot="curl">

    ```sh
    curl -X PUT 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/order' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "slugs": [
        "string"
      ]
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/order', {
      method: 'PUT',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        slugs: ['string'],
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.put(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/order',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'slugs': ['string'],
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Reorder the categories**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `slugs` | string[] | yes | Every category of the site exactly once |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Reordered. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |

<RouteHeading id="get-v1-admin-sites-siteid-categories-slug" method="GET" path="/v1/admin/sites/{siteId}/categories/{slug}" />

<CodePanel title="GET /v1/admin/sites/{siteId}/categories/{slug}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/gloop' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/gloop', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/gloop',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**One category**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `slug` | path | string | yes | pattern `^[a-z][a-z0-9-]{0,39}$` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Category](/docs/api/reference/schemas/#schema-category) | Category. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="patch-v1-admin-sites-siteid-categories-slug" method="PATCH" path="/v1/admin/sites/{siteId}/categories/{slug}" />

<CodePanel title="PATCH /v1/admin/sites/{siteId}/categories/{slug}">
  <Fragment slot="curl">

    ```sh
    curl -X PATCH 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/gloop' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "slug": "gloop",
      "icon": "puzzle",
      "texts": {
        "en": {
          "title": "string",
          "navTitle": "string",
          "description": "string"
        }
      }
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/gloop', {
      method: 'PATCH',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        slug: 'gloop',
        icon: 'puzzle',
        texts: {
          en: {
            title: 'string',
            navTitle: 'string',
            description: 'string',
          },
        },
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.patch(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/gloop',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'slug': 'gloop',
            'icon': 'puzzle',
            'texts': {
                'en': {
                    'title': 'string',
                    'navTitle': 'string',
                    'description': 'string',
                },
            },
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Update texts and icon**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `slug` | path | string | yes | pattern `^[a-z][a-z0-9-]{0,39}$` |

### Request body

`application/json`, required. The body is a [CategoryInput](/docs/api/reference/schemas/#schema-categoryinput).

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | no | On create only; ignored on PATCH; pattern `^[a-z][a-z0-9-]{0,39}$` |
| `icon` | [CategoryIcon](/docs/api/reference/schemas/#schema-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 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Category](/docs/api/reference/schemas/#schema-category) | Updated. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="delete-v1-admin-sites-siteid-categories-slug" method="DELETE" path="/v1/admin/sites/{siteId}/categories/{slug}" />

<CodePanel title="DELETE /v1/admin/sites/{siteId}/categories/{slug}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/gloop' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/gloop', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/categories/gloop',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Remove the category from the site, from its games and from the top menu**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `slug` | path | string | yes | pattern `^[a-z][a-z0-9-]{0,39}$` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Removed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-admin-sites-siteid-tags" method="GET" path="/v1/admin/sites/{siteId}/tags" />

<CodePanel title="GET /v1/admin/sites/{siteId}/tags">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Tags of a site, in site order, with the number of games carrying each**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Tag](/docs/api/reference/schemas/#schema-tag)[] | Tags. |

<RouteHeading id="post-v1-admin-sites-siteid-tags" method="POST" path="/v1/admin/sites/{siteId}/tags" />

<CodePanel title="POST /v1/admin/sites/{siteId}/tags">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "slug": "gloop",
      "texts": {
        "en": {
          "title": "string"
        }
      }
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        slug: 'gloop',
        texts: {
          en: {
            title: 'string',
          },
        },
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'slug': 'gloop',
            'texts': {
                'en': {
                    'title': 'string',
                },
            },
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Add a tag at the end of the site order**

The default locale needs a title. A tag slug never changes once created (ADR 0008).

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

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

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [Tag](/docs/api/reference/schemas/#schema-tag) | Created. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 409 | none | Slug taken on this site. |

<RouteHeading id="put-v1-admin-sites-siteid-tags-order" method="PUT" path="/v1/admin/sites/{siteId}/tags/order" />

<CodePanel title="PUT /v1/admin/sites/{siteId}/tags/order">
  <Fragment slot="curl">

    ```sh
    curl -X PUT 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/order' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "slugs": [
        "string"
      ]
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/order', {
      method: 'PUT',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        slugs: ['string'],
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.put(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/order',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'slugs': ['string'],
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Reorder the tags**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `slugs` | string[] | yes | Every tag of the site exactly once |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Reordered. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |

<RouteHeading id="get-v1-admin-sites-siteid-tags-slug" method="GET" path="/v1/admin/sites/{siteId}/tags/{slug}" />

<CodePanel title="GET /v1/admin/sites/{siteId}/tags/{slug}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/gloop' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/gloop', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/gloop',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**One tag**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `slug` | path | string | yes | pattern `^[a-z][a-z0-9-]{0,39}$` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Tag](/docs/api/reference/schemas/#schema-tag) | Tag. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="patch-v1-admin-sites-siteid-tags-slug" method="PATCH" path="/v1/admin/sites/{siteId}/tags/{slug}" />

<CodePanel title="PATCH /v1/admin/sites/{siteId}/tags/{slug}">
  <Fragment slot="curl">

    ```sh
    curl -X PATCH 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/gloop' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "slug": "gloop",
      "texts": {
        "en": {
          "title": "string"
        }
      }
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/gloop', {
      method: 'PATCH',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        slug: 'gloop',
        texts: {
          en: {
            title: 'string',
          },
        },
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.patch(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/gloop',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'slug': 'gloop',
            'texts': {
                'en': {
                    'title': 'string',
                },
            },
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Update the titles**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `slug` | path | string | yes | pattern `^[a-z][a-z0-9-]{0,39}$` |

### Request body

`application/json`, required. The body is a [TagInput](/docs/api/reference/schemas/#schema-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 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Tag](/docs/api/reference/schemas/#schema-tag) | Updated. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="delete-v1-admin-sites-siteid-tags-slug" method="DELETE" path="/v1/admin/sites/{siteId}/tags/{slug}" />

<CodePanel title="DELETE /v1/admin/sites/{siteId}/tags/{slug}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/gloop' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/gloop', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/tags/gloop',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Remove the tag from the site and from its games**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `slug` | path | string | yes | pattern `^[a-z][a-z0-9-]{0,39}$` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Removed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-admin-sites-siteid-catalog" method="GET" path="/v1/admin/sites/{siteId}/catalog" />

<CodePanel title="GET /v1/admin/sites/{siteId}/catalog">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Site catalog entries with every locale**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [SiteGame](/docs/api/reference/schemas/#schema-sitegame)[] | Entries in order. |

<RouteHeading id="put-v1-admin-sites-siteid-catalog-order" method="PUT" path="/v1/admin/sites/{siteId}/catalog/order" />

<CodePanel title="PUT /v1/admin/sites/{siteId}/catalog/order">
  <Fragment slot="curl">

    ```sh
    curl -X PUT 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog/order' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "gameIds": [
        "00000000-0000-0000-0000-000000000000"
      ]
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog/order', {
      method: 'PUT',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        gameIds: ['00000000-0000-0000-0000-000000000000'],
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.put(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog/order',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'gameIds': ['00000000-0000-0000-0000-000000000000'],
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Reorder the catalog**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `gameIds` | array of string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Reordered. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |

<RouteHeading id="put-v1-admin-sites-siteid-catalog-gameid" method="PUT" path="/v1/admin/sites/{siteId}/catalog/{gameId}" />

<CodePanel title="PUT /v1/admin/sites/{siteId}/catalog/{gameId}">
  <Fragment slot="curl">

    ```sh
    curl -X PUT 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "featured": true,
      "visible": true,
      "categories": [
        "string"
      ],
      "tags": [
        "string"
      ],
      "texts": {
        "en": {
          "title": "string",
          "tagline": "string",
          "description": "string",
          "howToPlay": [
            "string"
          ],
          "controls": [
            {
              "keys": [
                "string"
              ],
              "does": "string"
            }
          ],
          "seoTitle": "string",
          "seoDescription": "string"
        }
      }
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog/00000000-0000-0000-0000-000000000000', {
      method: 'PUT',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        featured: true,
        visible: true,
        categories: ['string'],
        tags: ['string'],
        texts: {
          en: {
            title: 'string',
            tagline: 'string',
            description: 'string',
            howToPlay: ['string'],
            controls: [{
              keys: ['string'],
              does: 'string',
            }],
            seoTitle: 'string',
            seoDescription: 'string',
          },
        },
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.put(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'featured': True,
            'visible': True,
            'categories': ['string'],
            'tags': ['string'],
            'texts': {
                'en': {
                    'title': 'string',
                    'tagline': 'string',
                    'description': 'string',
                    'howToPlay': ['string'],
                    'controls': [{
                        'keys': ['string'],
                        'does': 'string',
                    }],
                    'seoTitle': 'string',
                    'seoDescription': 'string',
                },
            },
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Add or update a game in the site catalog**

Adding a game the site may not list answers 403 with the reason in `message`: the game is pending, it has
no live version, or it is `first_party` and the site is not first-party (ADR 0015). A pending site of the
game's own developer may list the developer's pending games.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `gameId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [SiteGameInput](/docs/api/reference/schemas/#schema-sitegameinput).

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `featured` | boolean | no |  |
| `visible` | boolean | no |  |
| `categories` | string[] | no |  |
| `tags` | string[] | no |  |
| `texts` | object | no |  |
| `texts.*` | [GameTexts](/docs/api/reference/schemas/#schema-gametexts) | no |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [SiteGame](/docs/api/reference/schemas/#schema-sitegame) | Entry. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | The site may not list this game; `message` says why. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="delete-v1-admin-sites-siteid-catalog-gameid" method="DELETE" path="/v1/admin/sites/{siteId}/catalog/{gameId}" />

<CodePanel title="DELETE /v1/admin/sites/{siteId}/catalog/{gameId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Remove a game from the site catalog**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `gameId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Removed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="post-v1-admin-sites-siteid-publish" method="POST" path="/v1/admin/sites/{siteId}/publish" />

<CodePanel title="POST /v1/admin/sites/{siteId}/publish">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/publish' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/publish', {
      method: 'POST',
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/publish',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Make the catalog changes visible on the site front**

Drops the API's cached catalog of the site, then purges the site's CDN pull zone (ADR 0010)
when the site has `cdnPullZoneId` and the API has `BUNNY_API_KEY`. Without one of them nothing
is purged and the answer says why: the front picks the change up on its own within its
revalidation delay. Writes an audit row `site.publish`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [PublishResult](/docs/api/reference/schemas/#schema-publishresult) | What was purged. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 503 | [Error](/docs/api/reference/schemas/#schema-error) | The CDN did not accept the purge; retry in a minute. |

<RouteHeading id="get-v1-admin-games" method="GET" path="/v1/admin/games" />

<CodePanel title="GET /v1/admin/games">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/games' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/games',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Every game with its versions**

Staff and a game's members get the full game. A site member gets a reader view of the others:
the live version only, `notes` null, `createdBy` empty, `sites` limited to its own.
An account with no site membership gets only its own games, and 403 on another game's id.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `available` | query | string (uuid) | no | A site id. Lists only the games that site may add: approved, with a live version, `any_portal` or the site is first-party. A pending site of the caller also gets the caller's own pending games. |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Game](/docs/api/reference/schemas/#schema-game)[] | Games. |

<RouteHeading id="post-v1-admin-games" method="POST" path="/v1/admin/games" />

<CodePanel title="POST /v1/admin/games">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/games' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "slug": "gloop",
      "name": "string",
      "orientation": "portrait",
      "minutes": 1,
      "mobile": true,
      "daily": true,
      "coverColor": "string",
      "distribution": "first_party"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        slug: 'gloop',
        name: 'string',
        orientation: 'portrait',
        minutes: 1,
        mobile: true,
        daily: true,
        coverColor: 'string',
        distribution: 'first_party',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/games',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'slug': 'gloop',
            'name': 'string',
            'orientation': 'portrait',
            'minutes': 1,
            'mobile': True,
            'daily': True,
            'coverColor': 'string',
            'distribution': 'first_party',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Create a game**

Staff, or an account with `canCreateGames`; anyone else gets 403. A staff creation is approved at once.
A developer's game is created with `approvedAt` null and the creator as owner; staff approves it from
the Approvals screen. One account holds at most 10 pending games (409). A reserved slug answers 400:
`admin`, `api`, `play`, `developers`, `filudi`, `www`, `static`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | yes | pattern `^[a-z][a-z0-9-]{1,39}$` |
| `name` | string | yes |  |
| `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](/docs/api/reference/schemas/#schema-distribution) | no | Where a game may be listed (ADR 0015). `first_party`: sites with `firstParty` only. `any_portal`: any approved site. |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [Game](/docs/api/reference/schemas/#schema-game) | Created. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 409 | none | Slug taken, or the account already holds 10 pending games. |

<RouteHeading id="get-v1-admin-games-gameid" method="GET" path="/v1/admin/games/{gameId}" />

<CodePanel title="GET /v1/admin/games/{gameId}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**One game**

Members and staff get `listedOn`, the sites whose catalog carries the game.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Game](/docs/api/reference/schemas/#schema-game) | Game. |

<RouteHeading id="patch-v1-admin-games-gameid" method="PATCH" path="/v1/admin/games/{gameId}" />

<CodePanel title="PATCH /v1/admin/games/{gameId}">
  <Fragment slot="curl">

    ```sh
    curl -X PATCH 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "slug": "gloop",
      "name": "string",
      "orientation": "portrait",
      "minutes": 1,
      "mobile": true,
      "daily": true,
      "coverColor": "string",
      "distribution": "first_party"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000', {
      method: 'PATCH',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        slug: 'gloop',
        name: 'string',
        orientation: 'portrait',
        minutes: 1,
        mobile: true,
        daily: true,
        coverColor: 'string',
        distribution: 'first_party',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.patch(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'slug': 'gloop',
            'name': 'string',
            'orientation': 'portrait',
            'minutes': 1,
            'mobile': True,
            'daily': True,
            'coverColor': 'string',
            'distribution': 'first_party',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Update a game**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [GameInput](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-distribution) | no | Where a game may be listed (ADR 0015). `first_party`: sites with `firstParty` only. `any_portal`: any approved site. |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Game](/docs/api/reference/schemas/#schema-game) | Updated. |

<RouteHeading id="delete-v1-admin-games-gameid" method="DELETE" path="/v1/admin/games/{gameId}" />

<CodePanel title="DELETE /v1/admin/games/{gameId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Delete a game and everything attached to it (staff only)**

Refused while a version of the game is live. Deletes the versions, media, saves, scores, leaderboards,
ratings, comments and catalog entries of every site, and sets `game` to null on its feedback (ADR 0012).
Then removes the files under `games/<slug>/` from the files service (best effort: a failure is logged,
the deletion stands), removes the game's Redis leaderboard sets and drops the catalog cache of every site
that listed it. Events and daily aggregates keep the game's id. Writes an audit row `game.delete`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Deleted. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | [Error](/docs/api/reference/schemas/#schema-error) | `conflict`: "Retire the live version first.". |

<RouteHeading id="post-v1-admin-games-gameid-approve" method="POST" path="/v1/admin/games/{gameId}/approve" />

<CodePanel title="POST /v1/admin/games/{gameId}/approve">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/approve' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/approve', {
      method: 'POST',
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/approve',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Approve a pending game**

Sets `approvedAt`. The game may now have a live version and be listed by approved sites; the owners get an email.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Game](/docs/api/reference/schemas/#schema-game) | Game. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | Already approved. |

<RouteHeading id="post-v1-admin-games-gameid-reject" method="POST" path="/v1/admin/games/{gameId}/reject" />

<CodePanel title="POST /v1/admin/games/{gameId}/reject">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/reject' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "reason": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/reject', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        reason: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/reject',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'reason': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Staff only. Send the owners a reason; the game stays pending**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [RejectInput](/docs/api/reference/schemas/#schema-rejectinput).

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

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Reason sent. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | The game is approved. |

<RouteHeading id="get-v1-admin-games-gameid-members" method="GET" path="/v1/admin/games/{gameId}/members" />

<CodePanel title="GET /v1/admin/games/{gameId}/members">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Members of a game**

Owner of the game or staff. Invited emails without an account yet are listed with `invited` true.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Member](/docs/api/reference/schemas/#schema-member)[] | Members. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="post-v1-admin-games-gameid-members" method="POST" path="/v1/admin/games/{gameId}/members" />

<CodePanel title="POST /v1/admin/games/{gameId}/members">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "email": "you@example.com",
      "role": "owner"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        email: 'you@example.com',
        role: 'owner',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'email': 'you@example.com',
            'role': 'owner',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Add a member by email**

Owner of the game or staff. An existing account gets the membership at once. An unknown email gets an
invitation that carries it; the membership exists once the invitation is accepted.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [MemberInput](/docs/api/reference/schemas/#schema-memberinput).

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes | at most 254 characters |
| `role` | [MembershipRole](/docs/api/reference/schemas/#schema-membershiprole) | yes | A member has every right of the owner except membership changes |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [Member](/docs/api/reference/schemas/#schema-member) | Member. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | Already a member. |

<RouteHeading id="delete-v1-admin-games-gameid-members-accountid" method="DELETE" path="/v1/admin/games/{gameId}/members/{accountId}" />

<CodePanel title="DELETE /v1/admin/games/{gameId}/members/{accountId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Remove a member**

Owner of the game or staff. The last owner cannot be removed.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |
| `accountId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Removed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | `conflict`: "A game keeps at least one owner.". |

<RouteHeading id="delete-v1-admin-games-gameid-members-invitations-invitationid" method="DELETE" path="/v1/admin/games/{gameId}/members/invitations/{invitationId}" />

<CodePanel title="DELETE /v1/admin/games/{gameId}/members/invitations/{invitationId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members/invitations/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members/invitations/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/members/invitations/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Withdraw an invitation**

Owner of the game or staff. Removes this game from the invitation's grants; an invitation left with no grant is revoked.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |
| `invitationId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Withdrawn. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | none | No pending invitation to this game has this id. |

<RouteHeading id="get-v1-admin-games-gameid-stats" method="GET" path="/v1/admin/games/{gameId}/stats" />

<CodePanel title="GET /v1/admin/games/{gameId}/stats">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/stats?from=2026-10-30&to=2026-10-30' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/stats?from=2026-10-30&to=2026-10-30', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/stats?from=2026-10-30&to=2026-10-30',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**One game's numbers across every site that lists it, for a range of UTC days**

Members of the game and staff. Same range rules as the site overview: `from` and `to` included, at most
400 days, `previous` covers the range of the same length that ends the day before `from`. Cached in Redis
for 60 s per game, range and filter set. Nothing about ads or money (ADR 0015).

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |
| `from` | query | string (date) | yes | First UTC day, included |
| `to` | query | string (date) | yes | Last UTC day, included |
| `site` | query | string (uuid) | no | Only the sessions of this site |
| `host` | query | string | no | Only the sessions of this host |
| `version` | query | string | no | Only the sessions of this bundle version. `events` and `funnel.loaded` come from `event_daily`, which has no version, so they ignore this filter |
| `locale` | query | string | no | Only the players of this locale. `events` and `funnel.loaded` come from `event_daily`, which has no locale, so they ignore this filter |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ConsoleGameStats](/docs/api/reference/schemas/#schema-consolegamestats) | Game stats. |
| 400 | none | Range over 400 days, or `to` before `from`. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="post-v1-admin-games-gameid-versions" method="POST" path="/v1/admin/games/{gameId}/versions" />

<CodePanel title="POST /v1/admin/games/{gameId}/versions">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/versions' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "version": "string",
      "sizeBytes": 0,
      "notes": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/versions', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        version: 'string',
        sizeBytes: 0,
        notes: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/versions',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'version': 'string',
            'sizeBytes': 0,
            'notes': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Start a version upload**

Returns a presigned PUT URL from the files service for a zip. 200 MB max. Answers 409 while a finalize runs or once the version is finalized, and 503 with `Retry-After` while Redis is down.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | string | yes | pattern `^\d+\.\d+\.\d+([-.][0-9A-Za-z.-]+)?$` |
| `sizeBytes` | integer | yes | at most 209715200 |
| `notes` | string | no |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | object | Upload slot. |
| 409 | none | Version exists. |

**Body of 201**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `versionId` | string (uuid) | yes |  |
| `uploadUrl` | string (uri) | yes |  |
| `expiresAt` | string (date-time) | yes |  |

<RouteHeading id="post-v1-admin-games-gameid-media-slot" method="POST" path="/v1/admin/games/{gameId}/media/{slot}" />

<CodePanel title="POST /v1/admin/games/{gameId}/media/{slot}">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/media/image-square' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "contentType": "image/avif",
      "sizeBytes": 1
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/media/image-square', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        contentType: 'image/avif',
        sizeBytes: 1,
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/media/image-square',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'contentType': 'image/avif',
            'sizeBytes': 1,
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Start a media upload**

Returns a presigned PUT URL from the files service. The slot keeps its current file until finalize succeeds.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |
| `slot` | path | one of `"image-square"`, `"image-landscape"`, `"image-portrait"`, `"video-landscape"`, `"video-portrait"` | yes | ADR 0007 gives the ratio, pixel range, file types and size limit of each slot |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `contentType` | one of `"image/avif"`, `"image/webp"`, `"image/jpeg"`, `"image/png"`, `"video/mp4"` | yes |  |
| `sizeBytes` | integer | yes | Checked against the slot limit; 1 to 15728640 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | object | Upload slot. |
| 400 | none | Type not allowed in this slot, or file over the slot limit. |

**Body of 201**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `uploadUrl` | string (uri) | yes |  |
| `expiresAt` | string (date-time) | yes |  |

<RouteHeading id="delete-v1-admin-games-gameid-media-slot" method="DELETE" path="/v1/admin/games/{gameId}/media/{slot}" />

<CodePanel title="DELETE /v1/admin/games/{gameId}/media/{slot}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/media/image-square' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/media/image-square', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/media/image-square',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Empty the slot**

The file stays in the files service; built pages may still point to it (ADR 0007).

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |
| `slot` | path | one of `"image-square"`, `"image-landscape"`, `"image-portrait"`, `"video-landscape"`, `"video-portrait"` | yes | ADR 0007 gives the ratio, pixel range, file types and size limit of each slot |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Emptied, or already empty. |

<RouteHeading id="post-v1-admin-games-gameid-media-slot-finalize" method="POST" path="/v1/admin/games/{gameId}/media/{slot}/finalize" />

<CodePanel title="POST /v1/admin/games/{gameId}/media/{slot}/finalize">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/media/image-square/finalize' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/media/image-square/finalize', {
      method: 'POST',
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/media/image-square/finalize',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Check the uploaded file and put it in the slot**

Detects the type from the bytes, checks ratio, pixels, size, and for a video H.264, duration and `moov` before `mdat`. The message of a 400 says what to change in the file.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |
| `slot` | path | one of `"image-square"`, `"image-landscape"`, `"image-portrait"`, `"video-landscape"`, `"video-portrait"` | yes | ADR 0007 gives the ratio, pixel range, file types and size limit of each slot |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [MediaFile](/docs/api/reference/schemas/#schema-mediafile) | The slot's new file. |
| 400 | none | No upload, or a file that breaks the slot rules. |

<RouteHeading id="post-v1-admin-versions-versionid-finalize" method="POST" path="/v1/admin/versions/{versionId}/finalize" />

<CodePanel title="POST /v1/admin/versions/{versionId}/finalize">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/finalize' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/finalize', {
      method: 'POST',
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/finalize',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Unpack the uploaded zip into the bundle prefix**

Checks the entry file exists, rejects paths with `..`, counts files and bytes. The version becomes `draft`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `versionId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [GameVersion](/docs/api/reference/schemas/#schema-gameversion) | Version. |
| 400 | none | Zip missing, invalid or without the entry file. |
| 409 | none | Another finalize or an activation holds this version. |
| 503 | none | Redis is down: the version lock is not available. |

<RouteHeading id="post-v1-admin-versions-versionid-activate" method="POST" path="/v1/admin/versions/{versionId}/activate" />

<CodePanel title="POST /v1/admin/versions/{versionId}/activate">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/activate' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/activate', {
      method: 'POST',
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/activate',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Make this version live; the previous live one goes back to draft (staff only)**

Clears `reviewRequestedAt`. Answers 409 on a game that is not approved, and while a finalize or another
activation holds the version; 503 while Redis is down (ADR 0013).

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `versionId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [GameVersion](/docs/api/reference/schemas/#schema-gameversion) | Version. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 409 | [Error](/docs/api/reference/schemas/#schema-error) | The game is pending approval, or another operation holds the version. |

<RouteHeading id="post-v1-admin-versions-versionid-retire" method="POST" path="/v1/admin/versions/{versionId}/retire" />

<CodePanel title="POST /v1/admin/versions/{versionId}/retire">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/retire' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/retire', {
      method: 'POST',
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/retire',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Retire a version; its bundle stops being served (staff only)**

Retiring the live version takes the game off play: the catalog answers `bundleUrl: null` and
`version: null` until another version goes live. A game is deleted only with no live version.
Clears `reviewRequestedAt`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `versionId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [GameVersion](/docs/api/reference/schemas/#schema-gameversion) | Version. |

<RouteHeading id="post-v1-admin-versions-versionid-review" method="POST" path="/v1/admin/versions/{versionId}/review" />

<CodePanel title="POST /v1/admin/versions/{versionId}/review">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/review' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/review', {
      method: 'POST',
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/review',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Ask staff to review a draft and make it live**

Any member of the game. Sets `reviewRequestedAt` and emails staff. The version shows in the Approvals screen.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `versionId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [GameVersion](/docs/api/reference/schemas/#schema-gameversion) | Version. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | [Error](/docs/api/reference/schemas/#schema-error) | The version is not a draft, or the game is pending approval. |

<RouteHeading id="post-v1-admin-versions-versionid-review-reject" method="POST" path="/v1/admin/versions/{versionId}/review/reject" />

<CodePanel title="POST /v1/admin/versions/{versionId}/review/reject">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/review/reject' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "reason": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/review/reject', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        reason: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/review/reject',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'reason': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Staff only. Decline a review request and send the owners the reason**

Clears `reviewRequestedAt`; the version stays a draft.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `versionId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [RejectInput](/docs/api/reference/schemas/#schema-rejectinput).

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

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [GameVersion](/docs/api/reference/schemas/#schema-gameversion) | Version. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | none | No review was requested. |

<RouteHeading id="get-v1-admin-versions-versionid-preview" method="GET" path="/v1/admin/versions/{versionId}/preview" />

<CodePanel title="GET /v1/admin/versions/{versionId}/preview">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/preview' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/preview', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/versions/00000000-0000-0000-0000-000000000000/preview',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Signed URL to play a draft version for 1 hour**

Built on `PREVIEW_URL` when it is set, else on the API origin, and never on the CDN, so Bunny cannot strip the preview cookie the bundle's other files need. Open it in a new tab (a preview answers `frame-ancestors 'none'`).

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `versionId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | object | URL. |

**Body of 200**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string (uri) | yes |  |
| `expiresAt` | string (date-time) | yes |  |

<RouteHeading id="get-v1-admin-games-gameid-leaderboards" method="GET" path="/v1/admin/games/{gameId}/leaderboards" />

<CodePanel title="GET /v1/admin/games/{gameId}/leaderboards">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/leaderboards' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/leaderboards', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/leaderboards',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Boards of a game**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Leaderboard](/docs/api/reference/schemas/#schema-leaderboard)[] | Boards. |

<RouteHeading id="put-v1-admin-games-gameid-leaderboards" method="PUT" path="/v1/admin/games/{gameId}/leaderboards" />

<CodePanel title="PUT /v1/admin/games/{gameId}/leaderboards">
  <Fragment slot="curl">

    ```sh
    curl -X PUT 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/leaderboards' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '[
      {
        "name": "string",
        "sort": "desc",
        "min": 0,
        "max": 0,
        "keep": "best",
        "ratePerMinute": 10
      }
    ]'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/leaderboards', {
      method: 'PUT',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify([{
        name: 'string',
        sort: 'desc',
        min: 0,
        max: 0,
        keep: 'best',
        ratePerMinute: 10,
      }]),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.put(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/leaderboards',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json=[{
            'name': 'string',
            'sort': 'desc',
            'min': 0,
            'max': 0,
            'keep': 'best',
            'ratePerMinute': 10,
        }],
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Replace the boards of a game**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

An array of [LeaderboardInput](/docs/api/reference/schemas/#schema-leaderboardinput).

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Leaderboard](/docs/api/reference/schemas/#schema-leaderboard)[] | Boards. |

<RouteHeading id="get-v1-admin-games-gameid-leaderboards-board-scores" method="GET" path="/v1/admin/games/{gameId}/leaderboards/{board}/scores" />

<CodePanel title="GET /v1/admin/games/{gameId}/leaderboards/{board}/scores">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/leaderboards/height/scores' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/leaderboards/height/scores', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/games/00000000-0000-0000-0000-000000000000/leaderboards/height/scores',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Scores for moderation**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |
| `board` | path | string | yes | pattern `^[a-z][a-z0-9_]{0,31}$` |
| `period` | query | one of `"day"`, `"week"`, `"all"` | no | default `"all"` |
| `site` | query | string | no | 403 unless the caller is an admin or an editor of that site |
| `hidden` | query | boolean | no |  |
| `limit` | query | integer | no | at most 500; default `100` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ScoreAdmin](/docs/api/reference/schemas/#schema-scoreadmin)[] | Scores with player ids. |

<RouteHeading id="post-v1-admin-scores-scoreid" method="POST" path="/v1/admin/scores/{scoreId}" />

<CodePanel title="POST /v1/admin/scores/{scoreId}">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/scores/string' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/scores/string', {
      method: 'POST',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/scores/string',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Unhide a score**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `scoreId` | path | string | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Visible again. |

<RouteHeading id="delete-v1-admin-scores-scoreid" method="DELETE" path="/v1/admin/scores/{scoreId}" />

<CodePanel title="DELETE /v1/admin/scores/{scoreId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/scores/string' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "reason": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/scores/string', {
      method: 'DELETE',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        reason: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/scores/string',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'reason': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Hide a score**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `scoreId` | path | string | yes |  |

### Request body

`application/json`, optional.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no | Stored in the audit row; at most 200 characters |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Hidden and removed from Redis. |

<RouteHeading id="get-v1-admin-sites-siteid-players" method="GET" path="/v1/admin/sites/{siteId}/players" />

<CodePanel title="GET /v1/admin/sites/{siteId}/players">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/players' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/players', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/players',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**List the players of a site, with an optional search**

Without `q`, every player that matches the filters. With `q`, a player id (a UUID), an email (a value
with `@`, matched by its hash) or a nickname substring, case-insensitive. By default the list shows
account players only: `guests=true` adds guests, and `merged=true` also adds guests already merged
into an account. An id or an email ignores `guests` and `merged`: the one match shows, whatever it is. `lastSeen` and `created` sort newest first, `nickname` alphabetically; ties break on id.
`total` counts every row that matches the filters, across pages.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `q` | query | string | no | at least 2 characters |
| `guests` | query | boolean | no | False hides players without an email; default `false` |
| `merged` | query | boolean | no | False hides guests merged into an account; only matters with `guests=true`; default `false` |
| `sort` | query | one of `"lastSeen"`, `"created"`, `"nickname"` | no | default `"lastSeen"` |
| `cursor` | query | string | no | Opaque; the `nextCursor` of the previous page, with the same filters and sort; at most 200 characters |
| `limit` | query | integer | no | 1 to 500; default `100` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [PlayerPage](/docs/api/reference/schemas/#schema-playerpage) | Players, emails masked. |
| 400 | none | `q` shorter than 2 characters, or a cursor of another sort. |

<RouteHeading id="get-v1-admin-players-playerid" method="GET" path="/v1/admin/players/{playerId}" />

<CodePanel title="GET /v1/admin/players/{playerId}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/players/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/players/00000000-0000-0000-0000-000000000000', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/players/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Player detail with saves metadata and best scores**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `playerId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [PlayerAdmin](/docs/api/reference/schemas/#schema-playeradmin) | Player. |

<RouteHeading id="delete-v1-admin-players-playerid" method="DELETE" path="/v1/admin/players/{playerId}" />

<CodePanel title="DELETE /v1/admin/players/{playerId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/players/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/players/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/players/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Schedule deletion (GDPR request handled by support)**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `playerId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 202 | none | Scheduled. |

<RouteHeading id="get-v1-admin-players-playerid-export" method="GET" path="/v1/admin/players/{playerId}/export" />

<CodePanel title="GET /v1/admin/players/{playerId}/export">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/players/00000000-0000-0000-0000-000000000000/export' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/players/00000000-0000-0000-0000-000000000000/export', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/players/00000000-0000-0000-0000-000000000000/export',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Export a player's data**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `playerId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [PlayerExport](/docs/api/reference/schemas/#schema-playerexport) | JSON file. |

<RouteHeading id="get-v1-admin-sites-siteid-comments" method="GET" path="/v1/admin/sites/{siteId}/comments" />

<CodePanel title="GET /v1/admin/sites/{siteId}/comments">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/comments' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/comments', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/comments',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Comments of a site for moderation, newest first**

Editor of the site or admin. `q` is a case-insensitive substring of the body or of the author's
current nickname. `total` counts every row that matches the filters, across pages.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `gameId` | query | string (uuid) | no |  |
| `hidden` | query | one of `"all"`, `"visible"`, `"hidden"` | no | default `"all"` |
| `q` | query | string | no | 2 to 100 characters |
| `cursor` | query | string | no | Opaque; the `nextCursor` of the previous page, with the same filters and sort; at most 200 characters |
| `limit` | query | integer | no | 1 to 500; default `100` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [CommentPage](/docs/api/reference/schemas/#schema-commentpage) | Comments. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | none | Unknown site. |

<RouteHeading id="delete-v1-admin-comments-commentid" method="DELETE" path="/v1/admin/comments/{commentId}" />

<CodePanel title="DELETE /v1/admin/comments/{commentId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/comments/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/comments/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/comments/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Delete a comment for good**

Editor of the comment's site or admin. Audit row `comment.delete` with the body in `before`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `commentId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Deleted. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="post-v1-admin-comments-commentid-hide" method="POST" path="/v1/admin/comments/{commentId}/hide" />

<CodePanel title="POST /v1/admin/comments/{commentId}/hide">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/comments/00000000-0000-0000-0000-000000000000/hide' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/comments/00000000-0000-0000-0000-000000000000/hide', {
      method: 'POST',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/comments/00000000-0000-0000-0000-000000000000/hide',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Hide a comment from every player route**

Editor of the comment's site or admin. Sets `hiddenBy` and `hiddenAt`. Audit row `comment.hide`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `commentId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Hidden, or already hidden. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="post-v1-admin-comments-commentid-unhide" method="POST" path="/v1/admin/comments/{commentId}/unhide" />

<CodePanel title="POST /v1/admin/comments/{commentId}/unhide">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/comments/00000000-0000-0000-0000-000000000000/unhide' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/comments/00000000-0000-0000-0000-000000000000/unhide', {
      method: 'POST',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/admin/comments/00000000-0000-0000-0000-000000000000/unhide',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Show a hidden comment again**

Editor of the comment's site or admin. Clears `hiddenBy` and `hiddenAt`. Audit row `comment.unhide`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `commentId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Visible, or already visible. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-admin-sites-siteid-ratings" method="GET" path="/v1/admin/sites/{siteId}/ratings" />

<CodePanel title="GET /v1/admin/sites/{siteId}/ratings">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/ratings' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/ratings', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/ratings',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Rating of every rated game of a site**

Games with at least one rating, listed in the catalog or not, most ratings first.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [GameRatingAdmin](/docs/api/reference/schemas/#schema-gameratingadmin)[] | Ratings. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | none | Unknown site. |

<RouteHeading id="get-v1-admin-sites-siteid-feedback" method="GET" path="/v1/admin/sites/{siteId}/feedback" />

<CodePanel title="GET /v1/admin/sites/{siteId}/feedback">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/feedback' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/feedback', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/feedback',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Feedback of a site, newest first**

Editor of the site or admin. `q` is a case-insensitive substring of the message. `total` counts
every row that matches the filters, across pages.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `status` | query | one of `"new"`, `"seen"`, `"done"` | no |  |
| `kind` | query | one of `"bug"`, `"suggestion"`, `"other"` | no |  |
| `gameId` | query | string (uuid) | no |  |
| `q` | query | string | no | 2 to 100 characters |
| `cursor` | query | string | no | Opaque; the `nextCursor` of the previous page, with the same filters and sort; at most 200 characters |
| `limit` | query | integer | no | 1 to 500; default `100` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [FeedbackPage](/docs/api/reference/schemas/#schema-feedbackpage) | Feedback. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | none | Unknown site. |

<RouteHeading id="get-v1-admin-feedback-feedbackid" method="GET" path="/v1/admin/feedback/{feedbackId}" />

<CodePanel title="GET /v1/admin/feedback/{feedbackId}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/feedback/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/feedback/00000000-0000-0000-0000-000000000000', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/feedback/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**One feedback message**

Editor of its site or admin. The reply email is decrypted.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `feedbackId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [FeedbackAdmin](/docs/api/reference/schemas/#schema-feedbackadmin) | Feedback. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="patch-v1-admin-feedback-feedbackid" method="PATCH" path="/v1/admin/feedback/{feedbackId}" />

<CodePanel title="PATCH /v1/admin/feedback/{feedbackId}">
  <Fragment slot="curl">

    ```sh
    curl -X PATCH 'https://api.filudi.com/v1/admin/feedback/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "status": "new",
      "note": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/feedback/00000000-0000-0000-0000-000000000000', {
      method: 'PATCH',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        status: 'new',
        note: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.patch(
        'https://api.filudi.com/v1/admin/feedback/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'status': 'new',
            'note': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Change the status or the note**

Editor of its site or admin. Audit row `feedback.update` with the old and new status and note.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `feedbackId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required. The body is a [FeedbackUpdate](/docs/api/reference/schemas/#schema-feedbackupdate). At least one field; an empty body is a 400.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | [FeedbackStatus](/docs/api/reference/schemas/#schema-feedbackstatus) | no |  |
| `note` | string or null | no | Null clears the note; "" is stored as null; at most 2000 characters |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [FeedbackAdmin](/docs/api/reference/schemas/#schema-feedbackadmin) | Updated. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="delete-v1-admin-feedback-feedbackid" method="DELETE" path="/v1/admin/feedback/{feedbackId}" />

<CodePanel title="DELETE /v1/admin/feedback/{feedbackId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/admin/feedback/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/feedback/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/admin/feedback/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Delete a feedback message for good**

Editor of its site or admin. Audit row `feedback.delete`; the row's email is not copied into it.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `feedbackId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Deleted. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-admin-sites-siteid-events-today" method="GET" path="/v1/admin/sites/{siteId}/events/today" />

<CodePanel title="GET /v1/admin/sites/{siteId}/events/today">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/events/today' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/events/today', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/events/today',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Counts since midnight UTC, live from the events table**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | object | Counts. |

**Body of 200**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `since` | string (date-time) | no |  |
| `rows` | [EventCount](/docs/api/reference/schemas/#schema-eventcount)[] | no |  |

<RouteHeading id="get-v1-admin-sites-siteid-events-daily" method="GET" path="/v1/admin/sites/{siteId}/events/daily" />

<CodePanel title="GET /v1/admin/sites/{siteId}/events/daily">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/events/daily?from=2026-10-30&to=2026-10-30' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/events/daily?from=2026-10-30&to=2026-10-30', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/events/daily?from=2026-10-30&to=2026-10-30',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Daily aggregates**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `from` | query | string (date) | yes |  |
| `to` | query | string (date) | yes |  |
| `game` | query | string | no |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [EventDaily](/docs/api/reference/schemas/#schema-eventdaily)[] | Rows. |

<RouteHeading id="get-v1-admin-sites-siteid-stats-overview" method="GET" path="/v1/admin/sites/{siteId}/stats/overview" />

<CodePanel title="GET /v1/admin/sites/{siteId}/stats/overview">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/stats/overview?from=2026-10-30&to=2026-10-30' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/stats/overview?from=2026-10-30&to=2026-10-30', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/stats/overview?from=2026-10-30&to=2026-10-30',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**The site dashboard numbers for a range of UTC days**

Read from Postgres (players, play_sessions, scores, saves, magic_links, event_daily) and cached
in Redis for 60 s per site and range. `from` and `to` are included; at most 400 days.
`previous` covers the range of the same length that ends the day before `from`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `from` | query | string (date) | yes | First UTC day, included |
| `to` | query | string (date) | yes | Last UTC day, included |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [StatsOverview](/docs/api/reference/schemas/#schema-statsoverview) | Overview. |

<RouteHeading id="get-v1-admin-sites-siteid-stats-games-gameid" method="GET" path="/v1/admin/sites/{siteId}/stats/games/{gameId}" />

<CodePanel title="GET /v1/admin/sites/{siteId}/stats/games/{gameId}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/stats/games/00000000-0000-0000-0000-000000000000?from=2026-10-30&to=2026-10-30' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/stats/games/00000000-0000-0000-0000-000000000000?from=2026-10-30&to=2026-10-30', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/stats/games/00000000-0000-0000-0000-000000000000?from=2026-10-30&to=2026-10-30',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**One game's numbers on this site for a range of UTC days**

Same range rules and cache as the overview. 404 when the game is not in the site catalog.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `gameId` | path | string (uuid) | yes |  |
| `from` | query | string (date) | yes | First UTC day, included |
| `to` | query | string (date) | yes | Last UTC day, included |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [GameStats](/docs/api/reference/schemas/#schema-gamestats) | Game stats. |

<RouteHeading id="get-v1-admin-sites-siteid-stats-web" method="GET" path="/v1/admin/sites/{siteId}/stats/web" />

<CodePanel title="GET /v1/admin/sites/{siteId}/stats/web">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/stats/web' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/stats/web', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/stats/web',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Web audience from CausalIT (ADR 0009)**

Calls the CausalIT read API with the site's read key and answers `configured: false` without one.
Cached in Redis for 120 s per site, period and path. `path` narrows every number to one page path,
for the game screens.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `siteId` | path | string (uuid) | yes |  |
| `period` | query | one of `"day"`, `"yesterday"`, `"7d"`, `"14d"`, `"30d"`, `"90d"`, `"6m"`, `"12m"`, `"custom"` | no | default `"7d"` |
| `from` | query | string (date) | no | With `period=custom` |
| `to` | query | string (date) | no | With `period=custom` |
| `path` | query | string | no | A page path such as `/game/gloop/`; at most 200 characters |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [WebStats](/docs/api/reference/schemas/#schema-webstats) | Web stats. |
| 503 | none | CausalIT did not answer. |

<RouteHeading id="get-v1-admin-audit" method="GET" path="/v1/admin/audit" />

<CodePanel title="GET /v1/admin/audit">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/audit' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/admin/audit', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/admin/audit',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Audit log**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `site` | query | string | no | Site slug |
| `actor` | query | string | no |  |
| `from` | query | string (date-time) | no |  |
| `cursor` | query | string | no |  |
| `limit` | query | integer | no | at most 500; default `100` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | object | Entries, newest first. |

**Body of 200**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [AuditEntry](/docs/api/reference/schemas/#schema-auditentry)[] | no |  |
| `nextCursor` | string or null | no |  |

Source: https://developers.filudi.com/docs/api/reference/admin/

---

# Bundles routes

The bundles routes of games-api, with parameters, bodies, responses and request samples.

Generated from `openapi.yaml` of games-api 0.7.0: 2 routes.

- [`GET /v1/bundles/{slug}/{version}/{path}`](#get-v1-bundles-slug-version-path): Bundle file, CDN origin for the game hosts
- [`GET /v1/bundles/{slug}/media/{file}`](#get-v1-bundles-slug-media-file): Game media file, CDN origin for play.filudi.com (ADR 0007)

<RouteHeading id="get-v1-bundles-slug-version-path" method="GET" path="/v1/bundles/{slug}/{version}/{path}" />

<CodePanel title="GET /v1/bundles/{slug}/{version}/{path}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/bundles/gloop/1.0.0/index.html'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/bundles/gloop/1.0.0/index.html');
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.get('https://api.filudi.com/v1/bundles/gloop/1.0.0/index.html')
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Bundle file, CDN origin for the game hosts**

With `PLAY_GAME_HOST_SUFFIX` set, a request without `X-Play-Host: <slug>.<suffix>` answers the
same 404 as any other miss. A request with any `X-Play-Host` ignores `preview`; a preview is a
direct request with no such header (ADR 0013). The CDN sets that header on the path players use.
With `PREVIEW_URL` set, a preview is served only on that host, which always needs a valid token,
refuses `X-Play-Host`, and answers 404 outside `/v1/bundles/*`. `_upload.zip` is always 404.

Credential: none. The route is public.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `slug` | path | string | yes |  |
| `version` | path | string | yes |  |
| `path` | path | string | yes |  |
| `preview` | query | string | no | Signed, time-limited parameter that allows a draft version |
| `X-Play-Host` | header | string | no | Hostname the player asked the CDN for |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | none | File. Headers: `Cache-Control`, `Content-Security-Policy`, `Cross-Origin-Resource-Policy`. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-bundles-slug-media-file" method="GET" path="/v1/bundles/{slug}/media/{file}" />

<CodePanel title="GET /v1/bundles/{slug}/media/{file}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/bundles/gloop/media/string'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/bundles/gloop/media/string');
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.get('https://api.filudi.com/v1/bundles/gloop/media/string')
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Game media file, CDN origin for play.filudi.com (ADR 0007)**

Serves only final names (`<kind>-<format>-<sha256:16>.<ext>`). Answers a single `Range` with 206.

Credential: none. The route is public.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `slug` | path | string | yes |  |
| `file` | path | string | yes | pattern `^(image-(square\|landscape\|portrait)-[0-9a-f]{16}\.(avif\|webp\|jpg\|png)\|video-(landscape\|portrait)-[0-9a-f]{16}\.mp4)$` |
| `Range` | header | string | no |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | none | File. Headers: `Cache-Control`, `Accept-Ranges`, `Cross-Origin-Resource-Policy`. |
| 206 | none | Requested byte range. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 416 | none | Range outside the file. |

Source: https://developers.filudi.com/docs/api/reference/bundles/

---

# Catalog routes

The catalog routes of games-api, with parameters, bodies, responses and request samples.

Generated from `openapi.yaml` of games-api 0.7.0: 2 routes.

- [`GET /v1/catalog/{site}`](#get-v1-catalog-site): Full catalog of a site
- [`GET /v1/catalog/{site}/games/{slug}`](#get-v1-catalog-site-games-slug): One game of a site

<RouteHeading id="get-v1-catalog-site" method="GET" path="/v1/catalog/{site}" />

<CodePanel title="GET /v1/catalog/{site}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/catalog/filudi'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/catalog/filudi');
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.get('https://api.filudi.com/v1/catalog/filudi')
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Full catalog of a site**

Credential: none. The route is public.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `site` | path | string | yes | Site slug |
| `locale` | query | string | no | Returns texts for one locale only; default returns every locale of the site |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Catalog](/docs/api/reference/schemas/#schema-catalog) | Catalog. Headers: `Cache-Control`, `ETag`. |
| 304 | none | Not modified. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-catalog-site-games-slug" method="GET" path="/v1/catalog/{site}/games/{slug}" />

<CodePanel title="GET /v1/catalog/{site}/games/{slug}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/catalog/filudi/games/gloop'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/catalog/filudi/games/gloop');
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.get('https://api.filudi.com/v1/catalog/filudi/games/gloop')
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**One game of a site**

Credential: none. The route is public.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `site` | path | string | yes | Site slug |
| `slug` | path | string | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [CatalogGame](/docs/api/reference/schemas/#schema-cataloggame) | Game. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

Source: https://developers.filudi.com/docs/api/reference/catalog/

---

# Community routes

Star ratings and comments on games (ADR 0012)

Star ratings and comments on games (ADR 0012). Generated from `openapi.yaml` of games-api 0.7.0: 7 routes.

- [`GET /v1/sdk/games/{gameId}/review`](#get-v1-sdk-games-gameid-review): The player's own rating and comments on a game
- [`PUT /v1/sdk/games/{gameId}/rating`](#put-v1-sdk-games-gameid-rating): Rate a game from 1 to 5 stars, or change the rating
- [`DELETE /v1/sdk/games/{gameId}/rating`](#delete-v1-sdk-games-gameid-rating): Remove the player's rating
- [`POST /v1/sdk/games/{gameId}/comments`](#post-v1-sdk-games-gameid-comments): Post a comment on a game
- [`PATCH /v1/sdk/comments/{commentId}`](#patch-v1-sdk-comments-commentid): Change the body of one of the player's comments
- [`DELETE /v1/sdk/comments/{commentId}`](#delete-v1-sdk-comments-commentid): Delete one of the player's comments
- [`GET /v1/catalog/{site}/games/{slug}/reviews`](#get-v1-catalog-site-games-slug-reviews): Rating and visible comments of a game, newest first

Also tagged `community`, documented with their first tag:

- [`GET /v1/admin/sites/{siteId}/comments`](/docs/api/reference/admin/#get-v1-admin-sites-siteid-comments): Comments of a site for moderation, newest first
- [`DELETE /v1/admin/comments/{commentId}`](/docs/api/reference/admin/#delete-v1-admin-comments-commentid): Delete a comment for good
- [`POST /v1/admin/comments/{commentId}/hide`](/docs/api/reference/admin/#post-v1-admin-comments-commentid-hide): Hide a comment from every player route
- [`POST /v1/admin/comments/{commentId}/unhide`](/docs/api/reference/admin/#post-v1-admin-comments-commentid-unhide): Show a hidden comment again
- [`GET /v1/admin/sites/{siteId}/ratings`](/docs/api/reference/admin/#get-v1-admin-sites-siteid-ratings): Rating of every rated game of a site

<RouteHeading id="get-v1-sdk-games-gameid-review" method="GET" path="/v1/sdk/games/{gameId}/review" />

<CodePanel title="GET /v1/sdk/games/{gameId}/review">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/sdk/games/gloop/review' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/sdk/games/gloop/review', {
      headers: { authorization: `Bearer ${playerToken}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.get(
        'https://api.filudi.com/v1/sdk/games/gloop/review',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**The player's own rating and comments on a game**

`gameId` is the game slug, as in `/v1/sdk/saves/{gameId}`. Hidden comments are left out.
Comments are newest first, all of them (a player posts 5 per hour at most).

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [PlayerReview](/docs/api/reference/schemas/#schema-playerreview) | Rating and comments. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="put-v1-sdk-games-gameid-rating" method="PUT" path="/v1/sdk/games/{gameId}/rating" />

<CodePanel title="PUT /v1/sdk/games/{gameId}/rating">
  <Fragment slot="curl">

    ```sh
    curl -X PUT 'https://api.filudi.com/v1/sdk/games/gloop/rating' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "stars": 1
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/sdk/games/gloop/rating', {
      method: 'PUT',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        stars: 1,
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.put(
        'https://api.filudi.com/v1/sdk/games/gloop/rating',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'stars': 1,
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Rate a game from 1 to 5 stars, or change the rating**

Guests and accounts. One rating per player and game on the token's site (ADR 0012). The game must be
in the site catalog and visible. 60 ratings per player per hour. The catalog shows the new average
within its 60-second cache.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `stars` | integer | yes | 1 to 5 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [RatingSummary](/docs/api/reference/schemas/#schema-ratingsummary) | The game's rating after this one. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 404 | none | Game not in this site's catalog. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |
| 503 | none | Redis is down; the rate limit cannot be checked. |

<RouteHeading id="delete-v1-sdk-games-gameid-rating" method="DELETE" path="/v1/sdk/games/{gameId}/rating" />

<CodePanel title="DELETE /v1/sdk/games/{gameId}/rating">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/sdk/games/gloop/rating' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/sdk/games/gloop/rating', {
      method: 'DELETE',
      headers: { authorization: `Bearer ${playerToken}` },
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.delete(
        'https://api.filudi.com/v1/sdk/games/gloop/rating',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Remove the player's rating**

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Removed. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |

<RouteHeading id="post-v1-sdk-games-gameid-comments" method="POST" path="/v1/sdk/games/{gameId}/comments" />

<CodePanel title="POST /v1/sdk/games/{gameId}/comments">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/games/gloop/comments' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "body": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/sdk/games/gloop/comments', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        body: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.post(
        'https://api.filudi.com/v1/sdk/games/gloop/comments',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'body': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Post a comment on a game**

Account players only (ADR 0012). The comment shows at once. The API converts CRLF to LF, removes
control characters other than newline and tab and the Unicode format characters (category Cf: bidi
controls, zero-width characters) except U+200D, the zero-width joiner combined emoji need, trims, and turns three or more consecutive newlines into two; the result must have 2 to 1000 characters. The comment's locale is the player's locale.
5 comments per player per hour.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | yes | Plain text; 2 to 1000 characters |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [Comment](/docs/api/reference/schemas/#schema-comment) | The comment. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 403 | none | A guest: "Sign in to comment.". |
| 404 | none | Game not in this site's catalog. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |
| 503 | none | Redis is down; the rate limit cannot be checked. |

<RouteHeading id="patch-v1-sdk-comments-commentid" method="PATCH" path="/v1/sdk/comments/{commentId}" />

<CodePanel title="PATCH /v1/sdk/comments/{commentId}">
  <Fragment slot="curl">

    ```sh
    curl -X PATCH 'https://api.filudi.com/v1/sdk/comments/00000000-0000-0000-0000-000000000000' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "body": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/sdk/comments/00000000-0000-0000-0000-000000000000', {
      method: 'PATCH',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        body: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.patch(
        'https://api.filudi.com/v1/sdk/comments/00000000-0000-0000-0000-000000000000',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'body': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Change the body of one of the player's comments**

Same body rules as a new comment. Sets `editedAt`. 30 edits per player per hour.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `commentId` | path | string (uuid) | yes |  |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | yes | Plain text; 2 to 1000 characters |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Comment](/docs/api/reference/schemas/#schema-comment) | The comment. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 404 | none | Unknown, hidden, or written by another player. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |
| 503 | none | Redis is down; the rate limit cannot be checked. |

<RouteHeading id="delete-v1-sdk-comments-commentid" method="DELETE" path="/v1/sdk/comments/{commentId}" />

<CodePanel title="DELETE /v1/sdk/comments/{commentId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/sdk/comments/00000000-0000-0000-0000-000000000000' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/sdk/comments/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      headers: { authorization: `Bearer ${playerToken}` },
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.delete(
        'https://api.filudi.com/v1/sdk/comments/00000000-0000-0000-0000-000000000000',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Delete one of the player's comments**

Works on a hidden comment too.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `commentId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Deleted. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 404 | none | Unknown. |

<RouteHeading id="get-v1-catalog-site-games-slug-reviews" method="GET" path="/v1/catalog/{site}/games/{slug}/reviews" />

<CodePanel title="GET /v1/catalog/{site}/games/{slug}/reviews">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/catalog/filudi/games/gloop/reviews'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/catalog/filudi/games/gloop/reviews');
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.get('https://api.filudi.com/v1/catalog/filudi/games/gloop/reviews')
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Rating and visible comments of a game, newest first**

Public (ADR 0012). Leaves out hidden comments and the comments of players scheduled for deletion.
The nickname is the author's at read time. Every page repeats `rating`.

Credential: none. The route is public.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `site` | path | string | yes | Site slug |
| `slug` | path | string | yes |  |
| `cursor` | query | string | no | Opaque; the `nextCursor` of the previous page, with the same filters and sort; at most 200 characters |
| `limit` | query | integer | no | 1 to 50; default `20` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [GameReviews](/docs/api/reference/schemas/#schema-gamereviews) | Reviews. Headers: `Cache-Control`, `ETag`. |
| 304 | none | Not modified: `If-None-Match` matches the current ETag. |
| 400 | none | Cursor not issued by this route. |
| 404 | none | Unknown site. |

Source: https://developers.filudi.com/docs/api/reference/community/

---

# Console routes

Sign-in, account, invitations and sessions of the console and the back office (ADR 0015)

Sign-in, account, invitations and sessions of the console and the back office (ADR 0015). Generated from `openapi.yaml` of games-api 0.7.0: 19 routes.

- [`POST /v1/console/sign-in`](#post-v1-console-sign-in): Sign in with email and password
- [`POST /v1/console/sign-in/totp`](#post-v1-console-sign-in-totp): Finish a sign-in with the 6-digit code of the authenticator
- [`POST /v1/console/sign-out`](#post-v1-console-sign-out): Sign out
- [`GET /v1/console/me`](#get-v1-console-me): The signed-in account
- [`PATCH /v1/console/me`](#patch-v1-console-me): Change the display name
- [`GET /v1/console/invitations/{token}`](#get-v1-console-invitations-token): What an invitation grants, for the accept page
- [`POST /v1/console/invitations/{token}/accept`](#post-v1-console-invitations-token-accept): Accept an invitation; this creates the account and signs it in
- [`POST /v1/console/password/forgot`](#post-v1-console-password-forgot): Email a password reset link
- [`POST /v1/console/password/reset`](#post-v1-console-password-reset): Set a new password from a reset link
- [`PUT /v1/console/password`](#put-v1-console-password): Change the password
- [`POST /v1/console/email`](#post-v1-console-email): Ask to change the email address
- [`POST /v1/console/email/confirm`](#post-v1-console-email-confirm): Confirm a new email address from its link
- [`POST /v1/console/totp`](#post-v1-console-totp): Start a TOTP enrolment
- [`DELETE /v1/console/totp`](#delete-v1-console-totp): Remove TOTP, with a current code
- [`POST /v1/console/totp/confirm`](#post-v1-console-totp-confirm): Confirm the enrolment with a first code; TOTP is on from here
- [`GET /v1/console/sessions`](#get-v1-console-sessions): The account's sessions, newest first
- [`DELETE /v1/console/sessions/{sessionId}`](#delete-v1-console-sessions-sessionid): Revoke one session; revoking the current one signs this browser out
- [`POST /v1/console/impersonation/end`](#post-v1-console-impersonation-end): End an impersonation
- [`POST /v1/console/invitation-requests`](#post-v1-console-invitation-requests): Ask for an invitation, from the form on developers.filudi.com

<RouteHeading id="post-v1-console-sign-in" method="POST" path="/v1/console/sign-in" />

<CodePanel title="POST /v1/console/sign-in">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/sign-in' \
      -H 'content-type: application/json' \
      -d '{
      "email": "you@example.com",
      "password": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/console/sign-in', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        email: 'you@example.com',
        password: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.post(
        'https://api.filudi.com/v1/console/sign-in',
        json={
            'email': 'you@example.com',
            'password': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Sign in with email and password**

Sets the `filudi_console` cookie (ADR 0015). When the account has TOTP, `totpRequired` is true, `me` is
absent and the cookie holds a pending sign-in for 5 minutes: finish with `POST /v1/console/sign-in/totp`.
An unknown email and a wrong password get the same 401 in the same time. Attempts are limited per email
and per IP in Redis, as `POST /v1/account/sign-in` does.

Credential: none. The route is public.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `password` | string | yes | 1 to 1024 characters; write only |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [SignInResult](/docs/api/reference/schemas/#schema-signinresult) | Signed in, or a TOTP code is due. Headers: `Set-Cookie` (`filudi_console`). |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | "Email or password is wrong.". |
| 403 | none | The account is disabled. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |
| 503 | none | Redis is down; the rate limit cannot be checked. |

<RouteHeading id="post-v1-console-sign-in-totp" method="POST" path="/v1/console/sign-in/totp" />

<CodePanel title="POST /v1/console/sign-in/totp">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/sign-in/totp' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "code": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/sign-in/totp', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        code: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/console/sign-in/totp',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'code': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Finish a sign-in with the 6-digit code of the authenticator**

Needs the pending cookie of `POST /v1/console/sign-in`. The code is RFC 6238, 30-second step, one step
of drift either way; a code is accepted once. The fifth wrong code ends the pending sign-in.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | [TotpCode](/docs/api/reference/schemas/#schema-totpcode) | yes | Six digits, "123456" or "123 456"; pattern `^[0-9 ]{6,7}$` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ConsoleMe](/docs/api/reference/schemas/#schema-consoleme) | Signed in; the cookie now holds a 14-day session. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Wrong code. On the fifth wrong code the pending sign-in is gone, the cookie is cleared and `details.signInEnded` is true. |
| 401 | none | No pending sign-in. |

<RouteHeading id="post-v1-console-sign-out" method="POST" path="/v1/console/sign-out" />

<CodePanel title="POST /v1/console/sign-out">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/sign-out' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/sign-out', {
      method: 'POST',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/console/sign-out',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Sign out**

Deletes the session row and clears the cookie. Answers 204 without a session too.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Signed out. |

<RouteHeading id="get-v1-console-me" method="GET" path="/v1/console/me" />

<CodePanel title="GET /v1/console/me">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/console/me' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/me', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/console/me',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**The signed-in account**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ConsoleMe](/docs/api/reference/schemas/#schema-consoleme) | Account. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |

<RouteHeading id="patch-v1-console-me" method="PATCH" path="/v1/console/me" />

<CodePanel title="PATCH /v1/console/me">
  <Fragment slot="curl">

    ```sh
    curl -X PATCH 'https://api.filudi.com/v1/console/me' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "name": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/me', {
      method: 'PATCH',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        name: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.patch(
        'https://api.filudi.com/v1/console/me',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'name': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Change the display name**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | [AccountName](/docs/api/reference/schemas/#schema-accountname) | yes | Display name, shown to other members and in the audit log; 1 to 80 characters |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ConsoleMe](/docs/api/reference/schemas/#schema-consoleme) | Account. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |

<RouteHeading id="get-v1-console-invitations-token" method="GET" path="/v1/console/invitations/{token}" />

<CodePanel title="GET /v1/console/invitations/{token}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/console/invitations/string'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/console/invitations/string');
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.get('https://api.filudi.com/v1/console/invitations/string')
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**What an invitation grants, for the accept page**

Credential: none. The route is public.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes | The token of the invitation link |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [InvitationPreview](/docs/api/reference/schemas/#schema-invitationpreview) | Invitation. |
| 404 | none | Unknown, expired, accepted or revoked: one answer for the four. |

<RouteHeading id="post-v1-console-invitations-token-accept" method="POST" path="/v1/console/invitations/{token}/accept" />

<CodePanel title="POST /v1/console/invitations/{token}/accept">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/invitations/string/accept' \
      -H 'content-type: application/json' \
      -d '{
      "name": "string",
      "password": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/console/invitations/string/accept', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        name: 'string',
        password: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.post(
        'https://api.filudi.com/v1/console/invitations/string/accept',
        json={
            'name': 'string',
            'password': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Accept an invitation; this creates the account and signs it in**

The password follows the policy of `PUT /v1/account/password`: 8 to 128 characters after NFC
normalization, not equal to the email. The token is single use. Sets the `filudi_console` cookie.

Credential: none. The route is public.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | path | string | yes | The token of the invitation link |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | [AccountName](/docs/api/reference/schemas/#schema-accountname) | yes | Display name, shown to other members and in the audit log; 1 to 80 characters |
| `password` | [NewPassword](/docs/api/reference/schemas/#schema-newpassword) | yes | The policy of `PUT /v1/account/password`: 8 to 128 characters after NFC normalization, not equal to the email; 8 to 128 characters; write only |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ConsoleMe](/docs/api/reference/schemas/#schema-consoleme) | Account created and signed in. Headers: `Set-Cookie` (`filudi_console`). |
| 400 | none | The password breaks the policy. |
| 404 | none | Unknown, expired, accepted or revoked. |

<RouteHeading id="post-v1-console-password-forgot" method="POST" path="/v1/console/password/forgot" />

<CodePanel title="POST /v1/console/password/forgot">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/password/forgot' \
      -H 'content-type: application/json' \
      -d '{
      "email": "you@example.com"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/console/password/forgot', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        email: 'you@example.com',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.post(
        'https://api.filudi.com/v1/console/password/forgot',
        json={
            'email': 'you@example.com',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Email a password reset link**

Answers 202 whether the email is on an account or not. Limited per email and per IP in Redis.

Credential: none. The route is public.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 202 | none | Sent, or silently not sent. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

<RouteHeading id="post-v1-console-password-reset" method="POST" path="/v1/console/password/reset" />

<CodePanel title="POST /v1/console/password/reset">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/password/reset' \
      -H 'content-type: application/json' \
      -d '{
      "token": "string",
      "password": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/console/password/reset', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        token: 'string',
        password: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.post(
        'https://api.filudi.com/v1/console/password/reset',
        json={
            'token': 'string',
            'password': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Set a new password from a reset link**

Same policy as `PUT /v1/account/password`. The token is single use. Other sessions of the account stay signed in.

Credential: none. The route is public.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes |  |
| `password` | [NewPassword](/docs/api/reference/schemas/#schema-newpassword) | yes | The policy of `PUT /v1/account/password`: 8 to 128 characters after NFC normalization, not equal to the email; 8 to 128 characters; write only |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Saved. |
| 400 | none | The password breaks the policy. |
| 404 | none | Unknown, expired or used token. |

<RouteHeading id="put-v1-console-password" method="PUT" path="/v1/console/password" />

<CodePanel title="PUT /v1/console/password">
  <Fragment slot="curl">

    ```sh
    curl -X PUT 'https://api.filudi.com/v1/console/password' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "current": "string",
      "password": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/password', {
      method: 'PUT',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        current: 'string',
        password: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.put(
        'https://api.filudi.com/v1/console/password',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'current': 'string',
            'password': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Change the password**

Same policy as `PUT /v1/account/password`. Other sessions stay signed in.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `current` | string | yes | 1 to 128 characters; write only |
| `password` | [NewPassword](/docs/api/reference/schemas/#schema-newpassword) | yes | The policy of `PUT /v1/account/password`: 8 to 128 characters after NFC normalization, not equal to the email; 8 to 128 characters; write only |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Saved. |
| 400 | none | The password breaks the policy. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing session, or `current` is wrong; then the body carries `details: { field: "current" }`. |

<RouteHeading id="post-v1-console-email" method="POST" path="/v1/console/email" />

<CodePanel title="POST /v1/console/email">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/email' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "password": "string",
      "email": "you@example.com"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/email', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        password: 'string',
        email: 'you@example.com',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/console/email',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'password': 'string',
            'email': 'you@example.com',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Ask to change the email address**

A confirmation link goes to the new address. The account keeps its current email until `POST /v1/console/email/confirm`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `password` | string | yes | 1 to 128 characters; write only |
| `email` | string (email) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 202 | none | Confirmation link sent to the new address. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing session, or the password is wrong. |
| 409 | none | The email is already on an account. |

<RouteHeading id="post-v1-console-email-confirm" method="POST" path="/v1/console/email/confirm" />

<CodePanel title="POST /v1/console/email/confirm">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/email/confirm' \
      -H 'content-type: application/json' \
      -d '{
      "token": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/console/email/confirm', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        token: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.post(
        'https://api.filudi.com/v1/console/email/confirm',
        json={
            'token': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Confirm a new email address from its link**

Credential: none. The route is public.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Email changed. |
| 404 | none | Unknown, expired or used token. |
| 409 | none | The email went on another account in the meantime. |

<RouteHeading id="post-v1-console-totp" method="POST" path="/v1/console/totp" />

<CodePanel title="POST /v1/console/totp">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/totp' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/totp', {
      method: 'POST',
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/console/totp',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Start a TOTP enrolment**

Answers a new secret and its `otpauth://` URL for the authenticator app. The secret is not active until
`POST /v1/console/totp/confirm` accepts a code; starting again replaces an unconfirmed secret. Staff
without TOTP gets 403 on every `/v1/admin/*` route except `GET /v1/admin/me`.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [TotpEnrolment](/docs/api/reference/schemas/#schema-totpenrolment) | Secret to show once. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 409 | none | TOTP is already enabled; remove it first. |

<RouteHeading id="delete-v1-console-totp" method="DELETE" path="/v1/console/totp" />

<CodePanel title="DELETE /v1/console/totp">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/console/totp' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "code": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/totp', {
      method: 'DELETE',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        code: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/console/totp',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'code': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Remove TOTP, with a current code**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | [TotpCode](/docs/api/reference/schemas/#schema-totpcode) | yes | Six digits, "123456" or "123 456"; pattern `^[0-9 ]{6,7}$` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Removed. |
| 400 | none | Wrong code. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |

<RouteHeading id="post-v1-console-totp-confirm" method="POST" path="/v1/console/totp/confirm" />

<CodePanel title="POST /v1/console/totp/confirm">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/totp/confirm' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "code": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/totp/confirm', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        code: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/console/totp/confirm',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
        json={
            'code': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Confirm the enrolment with a first code; TOTP is on from here**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | [TotpCode](/docs/api/reference/schemas/#schema-totpcode) | yes | Six digits, "123456" or "123 456"; pattern `^[0-9 ]{6,7}$` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | TOTP enabled. |
| 400 | none | Wrong code, or no enrolment started. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |

<RouteHeading id="get-v1-console-sessions" method="GET" path="/v1/console/sessions" />

<CodePanel title="GET /v1/console/sessions">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/console/sessions' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/sessions', {
      credentials: 'include',
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.get(
        'https://api.filudi.com/v1/console/sessions',
        cookies={'filudi_console': session},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**The account's sessions, newest first**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ConsoleSessionInfo](/docs/api/reference/schemas/#schema-consolesessioninfo)[] | Sessions. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |

<RouteHeading id="delete-v1-console-sessions-sessionid" method="DELETE" path="/v1/console/sessions/{sessionId}" />

<CodePanel title="DELETE /v1/console/sessions/{sessionId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/console/sessions/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/sessions/00000000-0000-0000-0000-000000000000', {
      method: 'DELETE',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.delete(
        'https://api.filudi.com/v1/console/sessions/00000000-0000-0000-0000-000000000000',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Revoke one session; revoking the current one signs this browser out**

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Revoked. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 404 | none | Not a session of this account. |

<RouteHeading id="post-v1-console-impersonation-end" method="POST" path="/v1/console/impersonation/end" />

<CodePanel title="POST /v1/console/impersonation/end">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/impersonation/end' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // The browser sends the filudi_console cookie and the Origin header itself.
    const response = await fetch('https://api.filudi.com/v1/console/impersonation/end', {
      method: 'POST',
      credentials: 'include',
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # session: the value of the filudi_console cookie set by POST /v1/console/sign-in
    response = requests.post(
        'https://api.filudi.com/v1/console/impersonation/end',
        cookies={'filudi_console': session},
        headers={'origin': 'https://developers.filudi.com'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**End an impersonation**

Send it with `X-Filudi-Impersonation: 1`. Deletes the impersonation session and clears the `filudi_impersonation` cookie.

Credential: the console session cookie `filudi_console`, set by `POST /v1/console/sign-in`. From a browser, send `credentials: 'include'`; on a non-GET request the `Origin` header must be one of the console origins. With `X-Filudi-Impersonation: 1` the API reads the `filudi_impersonation` cookie instead.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Ended. |
| 401 | none | No impersonation session. |

<RouteHeading id="post-v1-console-invitation-requests" method="POST" path="/v1/console/invitation-requests" />

<CodePanel title="POST /v1/console/invitation-requests">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/console/invitation-requests' \
      -H 'content-type: application/json' \
      -d '{
      "email": "you@example.com",
      "wants": [
        "games"
      ],
      "message": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/console/invitation-requests', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        email: 'you@example.com',
        wants: ['games'],
        message: 'string',
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.post(
        'https://api.filudi.com/v1/console/invitation-requests',
        json={
            'email': 'you@example.com',
            'wants': ['games'],
            'message': 'string',
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Ask for an invitation, from the form on developers.filudi.com**

Stored for staff, who invites or dismisses. No email is sent. 5 requests per IP per day.

Credential: none. The route is public.

### Request body

`application/json`, required. The body is a [InvitationRequestInput](/docs/api/reference/schemas/#schema-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 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 202 | none | Stored. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |
| 503 | none | Redis is down; the rate limit cannot be checked. |

Source: https://developers.filudi.com/docs/api/reference/console/

---

# Feedback routes

Bug reports and suggestions, read in the admin (ADR 0012)

Bug reports and suggestions, read in the admin (ADR 0012). Generated from `openapi.yaml` of games-api 0.7.0: 1 route.

- [`POST /v1/feedback`](#post-v1-feedback): Send a bug report, a suggestion or another message about the site or a game

Also tagged `feedback`, documented with their first tag:

- [`GET /v1/admin/sites/{siteId}/feedback`](/docs/api/reference/admin/#get-v1-admin-sites-siteid-feedback): Feedback of a site, newest first
- [`GET /v1/admin/feedback/{feedbackId}`](/docs/api/reference/admin/#get-v1-admin-feedback-feedbackid): One feedback message
- [`PATCH /v1/admin/feedback/{feedbackId}`](/docs/api/reference/admin/#patch-v1-admin-feedback-feedbackid): Change the status or the note
- [`DELETE /v1/admin/feedback/{feedbackId}`](/docs/api/reference/admin/#delete-v1-admin-feedback-feedbackid): Delete a feedback message for good

<RouteHeading id="post-v1-feedback" method="POST" path="/v1/feedback" />

<CodePanel title="POST /v1/feedback">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/feedback' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "site": "filudi",
      "game": "gloop",
      "kind": "bug",
      "message": "string",
      "email": "you@example.com",
      "page": "string",
      "locale": "en"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/feedback', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        site: 'filudi',
        game: 'gloop',
        kind: 'bug',
        message: 'string',
        email: 'you@example.com',
        page: 'string',
        locale: 'en',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.post(
        'https://api.filudi.com/v1/feedback',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'site': 'filudi',
            'game': 'gloop',
            'kind': 'bug',
            'message': 'string',
            'email': 'you@example.com',
            'page': 'string',
            'locale': 'en',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Send a bug report, a suggestion or another message about the site or a game**

Anyone (ADR 0012). With a player token, the row records the player; a token of another site
than `site` answers 400. An invalid or dead bearer counts as no token, as on sign-in: the route
never answers 401. The API stores the user agent (first 300 characters) and an IP hash,
encrypts `email` at rest, and sends no email. `locale` is kept when it is a locale of the site.
`game` must be in the site catalog; a hidden entry is accepted, since a player may report a game
the site just hid. 5 per IP per hour and 10 per player per day.

Credential, optional: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here. Without a token the answer is the anonymous one.

### Request body

`application/json`, required. The body is a [FeedbackInput](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 202 | [FeedbackAccepted](/docs/api/reference/schemas/#schema-feedbackaccepted) | Stored for the team. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 404 | none | Unknown site. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |
| 503 | none | Redis is down; the rate limit cannot be checked. |

Source: https://developers.filudi.com/docs/api/reference/feedback/

---

# Health routes

The health routes of games-api, with parameters, bodies, responses and request samples.

Generated from `openapi.yaml` of games-api 0.7.0: 3 routes.

- [`GET /healthz`](#get-healthz): Liveness, no dependency
- [`GET /api/health`](#get-api-health): Readiness, SELECT 1 and Redis PING
- [`GET /metrics`](#get-metrics): Prometheus metrics

<RouteHeading id="get-healthz" method="GET" path="/healthz" />

<CodePanel title="GET /healthz">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/healthz'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/healthz');
    const text = await response.text();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.get('https://api.filudi.com/healthz')
    response.raise_for_status()
    text = response.text
    ```

  </Fragment>
</CodePanel>

**Liveness, no dependency**

Credential: none. The route is public.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | `"ok"` (`text/plain`) | Process alive. |

<RouteHeading id="get-api-health" method="GET" path="/api/health" />

<CodePanel title="GET /api/health">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/api/health'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/api/health');
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.get('https://api.filudi.com/api/health')
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Readiness, SELECT 1 and Redis PING**

Credential: none. The route is public.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | object | Ready. |
| 503 | none | Database unreachable. |

**Body of 200**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `db` | `"ok"` | no |  |
| `redis` | one of `"ok"`, `"degraded"` | no |  |

<RouteHeading id="get-metrics" method="GET" path="/metrics" />

<CodePanel title="GET /metrics">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/metrics'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/metrics');
    const text = await response.text();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.get('https://api.filudi.com/metrics')
    response.raise_for_status()
    text = response.text
    ```

  </Fragment>
</CodePanel>

**Prometheus metrics**

Credential: none. The route is public.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | `text/plain` | Text exposition format. |

Source: https://developers.filudi.com/docs/api/reference/health/

---

# Schemas

Every named object of the games-api API: the fields each route reads or answers.

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`](#schema-error)
- [`Period`](#schema-period)
- [`AgeBand`](#schema-ageband)
- [`Player`](#schema-player)
- [`PlayerWithToken`](#schema-playerwithtoken)
- [`ConsumeResponse`](#schema-consumeresponse)
- [`SaveMeta`](#schema-savemeta)
- [`SaveServerCopy`](#schema-saveservercopy)
- [`Save`](#schema-save)
- [`LeaderboardEntry`](#schema-leaderboardentry)
- [`LeaderboardTop`](#schema-leaderboardtop)
- [`EventBatch`](#schema-eventbatch)
- [`EventIn`](#schema-eventin)
- [`Catalog`](#schema-catalog)
- [`CatalogGame`](#schema-cataloggame)
- [`CatalogRating`](#schema-catalograting)
- [`RatingSummary`](#schema-ratingsummary)
- [`Comment`](#schema-comment)
- [`GameReviews`](#schema-gamereviews)
- [`PlayerReview`](#schema-playerreview)
- [`CommentAdmin`](#schema-commentadmin)
- [`CommentPage`](#schema-commentpage)
- [`GameRatingAdmin`](#schema-gameratingadmin)
- [`FeedbackKind`](#schema-feedbackkind)
- [`FeedbackStatus`](#schema-feedbackstatus)
- [`FeedbackInput`](#schema-feedbackinput)
- [`FeedbackAccepted`](#schema-feedbackaccepted)
- [`FeedbackAdmin`](#schema-feedbackadmin)
- [`FeedbackUpdate`](#schema-feedbackupdate)
- [`FeedbackPage`](#schema-feedbackpage)
- [`MediaSlot`](#schema-mediaslot)
- [`MediaFile`](#schema-mediafile)
- [`GameMedia`](#schema-gamemedia)
- [`GameTexts`](#schema-gametexts)
- [`CategoryIcon`](#schema-categoryicon)
- [`Category`](#schema-category)
- [`CategoryInput`](#schema-categoryinput)
- [`Tag`](#schema-tag)
- [`TagInput`](#schema-taginput)
- [`OtherSite`](#schema-othersite)
- [`Site`](#schema-site)
- [`SiteInput`](#schema-siteinput)
- [`PublishResult`](#schema-publishresult)
- [`Distribution`](#schema-distribution)
- [`Game`](#schema-game)
- [`GameInput`](#schema-gameinput)
- [`GameVersion`](#schema-gameversion)
- [`SiteGame`](#schema-sitegame)
- [`SiteGameInput`](#schema-sitegameinput)
- [`Leaderboard`](#schema-leaderboard)
- [`LeaderboardInput`](#schema-leaderboardinput)
- [`ScoreAdmin`](#schema-scoreadmin)
- [`PlayerAdmin`](#schema-playeradmin)
- [`PlayerPage`](#schema-playerpage)
- [`PlayerExport`](#schema-playerexport)
- [`EventCount`](#schema-eventcount)
- [`EventDaily`](#schema-eventdaily)
- [`StatsTotals`](#schema-statstotals)
- [`StatsDay`](#schema-statsday)
- [`StatsGameRow`](#schema-statsgamerow)
- [`StatsKeyCount`](#schema-statskeycount)
- [`StatsOverview`](#schema-statsoverview)
- [`GameStatsDay`](#schema-gamestatsday)
- [`GameStatsTotals`](#schema-gamestatstotals)
- [`GameStatsBoard`](#schema-gamestatsboard)
- [`GameStats`](#schema-gamestats)
- [`WebStatsRow`](#schema-webstatsrow)
- [`WebStats`](#schema-webstats)
- [`AuditEntry`](#schema-auditentry)
- [`GameToken`](#schema-gametoken)
- [`AccountName`](#schema-accountname)
- [`NewPassword`](#schema-newpassword)
- [`TotpCode`](#schema-totpcode)
- [`MembershipRole`](#schema-membershiprole)
- [`Scope`](#schema-scope)
- [`ConsoleMe`](#schema-consoleme)
- [`SignInResult`](#schema-signinresult)
- [`TotpEnrolment`](#schema-totpenrolment)
- [`ConsoleSessionInfo`](#schema-consolesessioninfo)
- [`InvitationPreview`](#schema-invitationpreview)
- [`InvitationRequestInput`](#schema-invitationrequestinput)
- [`InvitationRequestStatus`](#schema-invitationrequeststatus)
- [`InvitationRequest`](#schema-invitationrequest)
- [`InvitationRequestPage`](#schema-invitationrequestpage)
- [`Membership`](#schema-membership)
- [`AccountAdmin`](#schema-accountadmin)
- [`AccountPage`](#schema-accountpage)
- [`AccountPatch`](#schema-accountpatch)
- [`ImpersonationStarted`](#schema-impersonationstarted)
- [`InvitationGrant`](#schema-invitationgrant)
- [`Invitation`](#schema-invitation)
- [`InvitationInput`](#schema-invitationinput)
- [`ApprovalOwner`](#schema-approvalowner)
- [`ApprovalGame`](#schema-approvalgame)
- [`ApprovalSite`](#schema-approvalsite)
- [`ApprovalDomains`](#schema-approvaldomains)
- [`ApprovalVersion`](#schema-approvalversion)
- [`Approvals`](#schema-approvals)
- [`RejectInput`](#schema-rejectinput)
- [`Member`](#schema-member)
- [`MemberInput`](#schema-memberinput)
- [`SiteKeyScope`](#schema-sitekeyscope)
- [`SiteKey`](#schema-sitekey)
- [`SiteKeyCreated`](#schema-sitekeycreated)
- [`SiteKeyInput`](#schema-sitekeyinput)
- [`RetentionShare`](#schema-retentionshare)
- [`StatsCohort`](#schema-statscohort)
- [`StatsFunnel`](#schema-statsfunnel)
- [`ConsoleStatsDay`](#schema-consolestatsday)
- [`ConsoleStatsTotals`](#schema-consolestatstotals)
- [`ConsoleGameStats`](#schema-consolegamestats)
- [`ServerPlayerInput`](#schema-serverplayerinput)
- [`ServerPlayer`](#schema-serverplayer)

<h2 id="schema-error"><code>Error</code></h2>

| 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 |  |

<h2 id="schema-period"><code>Period</code></h2>

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

<h2 id="schema-ageband"><code>AgeBand</code></h2>

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

<h2 id="schema-player"><code>Player</code></h2>

| 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 |  |

<h2 id="schema-playerwithtoken"><code>PlayerWithToken</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `player` | [Player](/docs/api/reference/schemas/#schema-player) | yes |  |
| `token` | string | yes |  |

<h2 id="schema-consumeresponse"><code>ConsumeResponse</code></h2>

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

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `player` | [Player](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-savemeta"><code>SaveMeta</code></h2>

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

<h2 id="schema-saveservercopy"><code>SaveServerCopy</code></h2>

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 |  |

<h2 id="schema-save"><code>Save</code></h2>

Type: [SaveMeta](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-leaderboardentry"><code>LeaderboardEntry</code></h2>

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

<h2 id="schema-leaderboardtop"><code>LeaderboardTop</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `period` | [Period](/docs/api/reference/schemas/#schema-period) | yes | default `"all"` |
| `entries` | [LeaderboardEntry](/docs/api/reference/schemas/#schema-leaderboardentry)[] | yes |  |
| `total` | integer | yes |  |
| `me` | [LeaderboardEntry](/docs/api/reference/schemas/#schema-leaderboardentry) or null | no |  |

<h2 id="schema-eventbatch"><code>EventBatch</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | [EventIn](/docs/api/reference/schemas/#schema-eventin)[] | yes | at most 50 items |

<h2 id="schema-eventin"><code>EventIn</code></h2>

| 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 |  |

<h2 id="schema-catalog"><code>Catalog</code></h2>

| 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](/docs/api/reference/schemas/#schema-ageband) | no |  |
| `site.navCategories` | string[] | yes | Category slugs of the top menu, in menu order; only slugs that exist |
| `site.otherSites` | [OtherSite](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-category)[] | yes |  |
| `tags` | [Tag](/docs/api/reference/schemas/#schema-tag)[] | yes | Every tag of the site, in site order; game tags are slugs of this list |
| `games` | [CatalogGame](/docs/api/reference/schemas/#schema-cataloggame)[] | yes |  |

<h2 id="schema-cataloggame"><code>CatalogGame</code></h2>

| 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](/docs/api/reference/schemas/#schema-gametexts) | no |  |
| `media` | [GameMedia](/docs/api/reference/schemas/#schema-gamemedia) | yes | Filled slots only; a missing key is an empty slot |
| `rating` | [CatalogRating](/docs/api/reference/schemas/#schema-catalograting) | yes | Stars of a game on the site (ADR 0012). Follows ratings within the catalog's 60-second cache. |

<h2 id="schema-catalograting"><code>CatalogRating</code></h2>

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 |

<h2 id="schema-ratingsummary"><code>RatingSummary</code></h2>

| 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 |

<h2 id="schema-comment"><code>Comment</code></h2>

| 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 |  |

<h2 id="schema-gamereviews"><code>GameReviews</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `rating` | [RatingSummary](/docs/api/reference/schemas/#schema-ratingsummary) | yes |  |
| `comments` | [Comment](/docs/api/reference/schemas/#schema-comment)[] | yes |  |
| `nextCursor` | string or null | yes | Null on the last page |

<h2 id="schema-playerreview"><code>PlayerReview</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `stars` | integer or null | yes | Null when the player has not rated the game; 1 to 5 |
| `comments` | [Comment](/docs/api/reference/schemas/#schema-comment)[] | yes | The player's visible comments on the game, newest first |

<h2 id="schema-commentadmin"><code>CommentAdmin</code></h2>

| 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 |  |

<h2 id="schema-commentpage"><code>CommentPage</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [CommentAdmin](/docs/api/reference/schemas/#schema-commentadmin)[] | yes |  |
| `nextCursor` | string or null | yes |  |
| `total` | integer | yes |  |

<h2 id="schema-gameratingadmin"><code>GameRatingAdmin</code></h2>

| 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 |

<h2 id="schema-feedbackkind"><code>FeedbackKind</code></h2>

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

<h2 id="schema-feedbackstatus"><code>FeedbackStatus</code></h2>

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

<h2 id="schema-feedbackinput"><code>FeedbackInput</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `site` | string | yes | Site slug |
| `game` | string | no | Game slug; absent when the message is about the site |
| `kind` | [FeedbackKind](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-feedbackaccepted"><code>FeedbackAccepted</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |

<h2 id="schema-feedbackadmin"><code>FeedbackAdmin</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `kind` | [FeedbackKind](/docs/api/reference/schemas/#schema-feedbackkind) | yes |  |
| `status` | [FeedbackStatus](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-feedbackupdate"><code>FeedbackUpdate</code></h2>

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

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | [FeedbackStatus](/docs/api/reference/schemas/#schema-feedbackstatus) | no |  |
| `note` | string or null | no | Null clears the note; "" is stored as null; at most 2000 characters |

<h2 id="schema-feedbackpage"><code>FeedbackPage</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [FeedbackAdmin](/docs/api/reference/schemas/#schema-feedbackadmin)[] | yes |  |
| `nextCursor` | string or null | yes |  |
| `total` | integer | yes |  |

<h2 id="schema-mediaslot"><code>MediaSlot</code></h2>

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"`.

<h2 id="schema-mediafile"><code>MediaFile</code></h2>

| 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 |

<h2 id="schema-gamemedia"><code>GameMedia</code></h2>

Filled slots only; a missing key is an empty slot

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `images` | object | yes |  |
| `images.square` | [MediaFile](/docs/api/reference/schemas/#schema-mediafile) | no |  |
| `images.landscape` | [MediaFile](/docs/api/reference/schemas/#schema-mediafile) | no |  |
| `images.portrait` | [MediaFile](/docs/api/reference/schemas/#schema-mediafile) | no |  |
| `videos` | object | yes |  |
| `videos.landscape` | [MediaFile](/docs/api/reference/schemas/#schema-mediafile) | no |  |
| `videos.portrait` | [MediaFile](/docs/api/reference/schemas/#schema-mediafile) | no |  |

<h2 id="schema-gametexts"><code>GameTexts</code></h2>

| 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 |  |

<h2 id="schema-categoryicon"><code>CategoryIcon</code></h2>

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"`.

<h2 id="schema-category"><code>Category</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | no |  |
| `slug` | string | yes |  |
| `order` | integer | yes |  |
| `icon` | [CategoryIcon](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-categoryinput"><code>CategoryInput</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | no | On create only; ignored on PATCH; pattern `^[a-z][a-z0-9-]{0,39}$` |
| `icon` | [CategoryIcon](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-tag"><code>Tag</code></h2>

| 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 |  |

<h2 id="schema-taginput"><code>TagInput</code></h2>

| 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 |

<h2 id="schema-othersite"><code>OtherSite</code></h2>

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 |

<h2 id="schema-site"><code>Site</code></h2>

| 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](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-siteinput"><code>SiteInput</code></h2>

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](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-publishresult"><code>PublishResult</code></h2>

| 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 |  |

<h2 id="schema-distribution"><code>Distribution</code></h2>

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"`.

<h2 id="schema-game"><code>Game</code></h2>

| 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](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-gameversion)[] | yes |  |
| `media` | [GameMedia](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-gameinput"><code>GameInput</code></h2>

| 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](/docs/api/reference/schemas/#schema-distribution) | no | Where a game may be listed (ADR 0015). `first_party`: sites with `firstParty` only. `any_portal`: any approved site. |

<h2 id="schema-gameversion"><code>GameVersion</code></h2>

| 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 |

<h2 id="schema-sitegame"><code>SiteGame</code></h2>

| 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](/docs/api/reference/schemas/#schema-gametexts) | no |  |
| `liveVersion` | string or null | no |  |
| `updatedAt` | string (date-time) | no |  |

<h2 id="schema-sitegameinput"><code>SiteGameInput</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `featured` | boolean | no |  |
| `visible` | boolean | no |  |
| `categories` | string[] | no |  |
| `tags` | string[] | no |  |
| `texts` | object | no |  |
| `texts.*` | [GameTexts](/docs/api/reference/schemas/#schema-gametexts) | no |  |

<h2 id="schema-leaderboard"><code>Leaderboard</code></h2>

| 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 |  |

<h2 id="schema-leaderboardinput"><code>LeaderboardInput</code></h2>

| 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` |

<h2 id="schema-scoreadmin"><code>ScoreAdmin</code></h2>

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 |  |

<h2 id="schema-playeradmin"><code>PlayerAdmin</code></h2>

| 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](/docs/api/reference/schemas/#schema-savemeta)[] | no |  |
| `bestScores` | object[] | no |  |
| `bestScores[].game` | string | yes |  |
| `bestScores[].board` | string | yes |  |
| `bestScores[].score` | integer | yes |  |
| `bestScores[].createdAt` | string (date-time) | yes |  |

<h2 id="schema-playerpage"><code>PlayerPage</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [PlayerAdmin](/docs/api/reference/schemas/#schema-playeradmin)[] | yes |  |
| `nextCursor` | string or null | yes | Null on the last page |
| `total` | integer | yes | Rows matching the filters |

<h2 id="schema-playerexport"><code>PlayerExport</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `exportedAt` | string (date-time) | yes |  |
| `player` | [Player](/docs/api/reference/schemas/#schema-player) | yes |  |
| `email` | string or null | no |  |
| `saves` | [Save](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-feedbackkind) | yes |  |
| `feedback[].status` | [FeedbackStatus](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-eventcount"><code>EventCount</code></h2>

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

<h2 id="schema-eventdaily"><code>EventDaily</code></h2>

Type: [EventCount](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-statstotals"><code>StatsTotals</code></h2>

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](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-statsday"><code>StatsDay</code></h2>

| 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 |  |

<h2 id="schema-statsgamerow"><code>StatsGameRow</code></h2>

| 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 |  |

<h2 id="schema-statskeycount"><code>StatsKeyCount</code></h2>

| 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 |

<h2 id="schema-statsoverview"><code>StatsOverview</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string (date) | yes |  |
| `to` | string (date) | yes |  |
| `days` | [StatsDay](/docs/api/reference/schemas/#schema-statsday)[] | yes | One per day of the range |
| `totals` | [StatsTotals](/docs/api/reference/schemas/#schema-statstotals) | yes | Counts over a range of days. Players and accounts count rows created in the range. |
| `previous` | [StatsTotals](/docs/api/reference/schemas/#schema-statstotals) | yes | Counts over a range of days. Players and accounts count rows created in the range. |
| `cohorts` | [StatsCohort](/docs/api/reference/schemas/#schema-statscohort)[] | yes |  |
| `funnel` | [StatsFunnel](/docs/api/reference/schemas/#schema-statsfunnel) | yes | Distinct players of the range at each step |
| `devices` | [StatsKeyCount](/docs/api/reference/schemas/#schema-statskeycount)[] | yes | Sessions per device: phone, tablet, desktop, unknown |
| `games` | [StatsGameRow](/docs/api/reference/schemas/#schema-statsgamerow)[] | yes | Every game of the site catalog, most sessions first |
| `hosts` | [StatsKeyCount](/docs/api/reference/schemas/#schema-statskeycount)[] | yes | Sessions per host |
| `locales` | [StatsKeyCount](/docs/api/reference/schemas/#schema-statskeycount)[] | yes | Players per locale, all time |
| `events` | [StatsKeyCount](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-gamestatsday"><code>GameStatsDay</code></h2>

| 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 |  |

<h2 id="schema-gamestatstotals"><code>GameStatsTotals</code></h2>

| 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 |

<h2 id="schema-gamestatsboard"><code>GameStatsBoard</code></h2>

| 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 |  |

<h2 id="schema-gamestats"><code>GameStats</code></h2>

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

<h2 id="schema-webstatsrow"><code>WebStatsRow</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | yes |  |
| `visitors` | integer | yes |  |
| `pageviews` | integer | yes |  |

<h2 id="schema-webstats"><code>WebStats</code></h2>

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](/docs/api/reference/schemas/#schema-webstatsrow)[] | no |  |
| `sources` | [WebStatsRow](/docs/api/reference/schemas/#schema-webstatsrow)[] | no |  |
| `countries` | [WebStatsRow](/docs/api/reference/schemas/#schema-webstatsrow)[] | no |  |
| `devices` | [WebStatsRow](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-auditentry"><code>AuditEntry</code></h2>

| 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 |  |

<h2 id="schema-gametoken"><code>GameToken</code></h2>

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 |  |

<h2 id="schema-accountname"><code>AccountName</code></h2>

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

Type: string; 1 to 80 characters.

<h2 id="schema-newpassword"><code>NewPassword</code></h2>

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.

<h2 id="schema-totpcode"><code>TotpCode</code></h2>

Six digits, "123456" or "123 456"

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

<h2 id="schema-membershiprole"><code>MembershipRole</code></h2>

A member has every right of the owner except membership changes

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

<h2 id="schema-scope"><code>Scope</code></h2>

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](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-consoleme"><code>ConsoleMe</code></h2>

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](/docs/api/reference/schemas/#schema-scope)[] | yes |  |
| `impersonatedBy` | object or null | yes | The staff member behind this session; null outside impersonation |

<h2 id="schema-signinresult"><code>SignInResult</code></h2>

| 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](/docs/api/reference/schemas/#schema-consoleme) | no | The signed-in account, as `GET /v1/admin/me` and `GET /v1/console/me` answer it (ADR 0015) |

<h2 id="schema-totpenrolment"><code>TotpEnrolment</code></h2>

| 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 |

<h2 id="schema-consolesessioninfo"><code>ConsoleSessionInfo</code></h2>

| 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 |  |

<h2 id="schema-invitationpreview"><code>InvitationPreview</code></h2>

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](/docs/api/reference/schemas/#schema-membershiprole) | yes | A member has every right of the owner except membership changes |
| `expiresAt` | string (date-time) | yes |  |

<h2 id="schema-invitationrequestinput"><code>InvitationRequestInput</code></h2>

| 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 |

<h2 id="schema-invitationrequeststatus"><code>InvitationRequestStatus</code></h2>

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

<h2 id="schema-invitationrequest"><code>InvitationRequest</code></h2>

| 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](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-invitationrequestpage"><code>InvitationRequestPage</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [InvitationRequest](/docs/api/reference/schemas/#schema-invitationrequest)[] | yes |  |
| `nextCursor` | string or null | yes | Null on the last page |
| `total` | integer | yes | Rows matching the filter |

<h2 id="schema-membership"><code>Membership</code></h2>

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](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-accountadmin"><code>AccountAdmin</code></h2>

| 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](/docs/api/reference/schemas/#schema-membership)[] | yes |  |
| `sessions` | integer | yes | Open sessions |

<h2 id="schema-accountpage"><code>AccountPage</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | [AccountAdmin](/docs/api/reference/schemas/#schema-accountadmin)[] | yes |  |
| `nextCursor` | string or null | yes | Null on the last page |
| `total` | integer | yes | Rows matching the search |

<h2 id="schema-accountpatch"><code>AccountPatch</code></h2>

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

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | [AccountName](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-impersonationstarted"><code>ImpersonationStarted</code></h2>

| 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 |

<h2 id="schema-invitationgrant"><code>InvitationGrant</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | one of `"game"`, `"site"` | yes |  |
| `targetId` | string (uuid) | yes |  |
| `slug` | string | yes |  |
| `name` | string | yes |  |
| `role` | [MembershipRole](/docs/api/reference/schemas/#schema-membershiprole) | yes | A member has every right of the owner except membership changes |

<h2 id="schema-invitation"><code>Invitation</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `emailMasked` | string | yes |  |
| `staff` | boolean | yes |  |
| `canCreateGames` | boolean | yes |  |
| `canCreatePortals` | boolean | yes |  |
| `grants` | [InvitationGrant](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-invitationinput"><code>InvitationInput</code></h2>

| 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](/docs/api/reference/schemas/#schema-membershiprole) | yes | A member has every right of the owner except membership changes |

<h2 id="schema-approvalowner"><code>ApprovalOwner</code></h2>

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

<h2 id="schema-approvalgame"><code>ApprovalGame</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `gameId` | string (uuid) | yes |  |
| `slug` | string | yes |  |
| `name` | string | yes |  |
| `owners` | [ApprovalOwner](/docs/api/reference/schemas/#schema-approvalowner)[] | yes |  |
| `createdAt` | string (date-time) | yes |  |

<h2 id="schema-approvalsite"><code>ApprovalSite</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `siteId` | string (uuid) | yes |  |
| `slug` | string | yes |  |
| `name` | string | yes |  |
| `owners` | [ApprovalOwner](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-approvaldomains"><code>ApprovalDomains</code></h2>

The proposed domains of one approved site

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

<h2 id="schema-approvalversion"><code>ApprovalVersion</code></h2>

| 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 |  |

<h2 id="schema-approvals"><code>Approvals</code></h2>

Every list is oldest first

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `games` | [ApprovalGame](/docs/api/reference/schemas/#schema-approvalgame)[] | yes |  |
| `sites` | [ApprovalSite](/docs/api/reference/schemas/#schema-approvalsite)[] | yes |  |
| `domains` | [ApprovalDomains](/docs/api/reference/schemas/#schema-approvaldomains)[] | yes |  |
| `versions` | [ApprovalVersion](/docs/api/reference/schemas/#schema-approvalversion)[] | yes |  |

<h2 id="schema-rejectinput"><code>RejectInput</code></h2>

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

<h2 id="schema-member"><code>Member</code></h2>

| 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](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-memberinput"><code>MemberInput</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes | at most 254 characters |
| `role` | [MembershipRole](/docs/api/reference/schemas/#schema-membershiprole) | yes | A member has every right of the owner except membership changes |

<h2 id="schema-sitekeyscope"><code>SiteKeyScope</code></h2>

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

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

<h2 id="schema-sitekey"><code>SiteKey</code></h2>

| 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](/docs/api/reference/schemas/#schema-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 |  |

<h2 id="schema-sitekeycreated"><code>SiteKeyCreated</code></h2>

Type: [SiteKey](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-sitekeyinput"><code>SiteKeyInput</code></h2>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | 1 to 60 characters |
| `scopes` | [SiteKeyScope](/docs/api/reference/schemas/#schema-sitekeyscope)[] | yes | at least 1 item; unique items |

<h2 id="schema-retentionshare"><code>RetentionShare</code></h2>

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.

<h2 id="schema-statscohort"><code>StatsCohort</code></h2>

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](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-statsfunnel"><code>StatsFunnel</code></h2>

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 |

<h2 id="schema-consolestatsday"><code>ConsoleStatsDay</code></h2>

| 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 |  |

<h2 id="schema-consolestatstotals"><code>ConsoleStatsTotals</code></h2>

| 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](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-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 |

<h2 id="schema-consolegamestats"><code>ConsoleGameStats</code></h2>

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](/docs/api/reference/schemas/#schema-consolestatsday)[] | yes |  |
| `totals` | [ConsoleStatsTotals](/docs/api/reference/schemas/#schema-consolestatstotals) | yes |  |
| `previous` | [ConsoleStatsTotals](/docs/api/reference/schemas/#schema-consolestatstotals) | yes |  |
| `cohorts` | [StatsCohort](/docs/api/reference/schemas/#schema-statscohort)[] | yes |  |
| `funnel` | [StatsFunnel](/docs/api/reference/schemas/#schema-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](/docs/api/reference/schemas/#schema-statskeycount)[] | yes | Sessions per host |
| `versions` | [StatsKeyCount](/docs/api/reference/schemas/#schema-statskeycount)[] | yes | Sessions per bundle version |
| `locales` | [StatsKeyCount](/docs/api/reference/schemas/#schema-statskeycount)[] | yes | Sessions per player locale |
| `devices` | [StatsKeyCount](/docs/api/reference/schemas/#schema-statskeycount)[] | yes | Sessions per device: phone, tablet, desktop, unknown |
| `boards` | [GameStatsBoard](/docs/api/reference/schemas/#schema-gamestatsboard)[] | yes |  |
| `events` | [StatsKeyCount](/docs/api/reference/schemas/#schema-statskeycount)[] | yes | Per event name with distinct players, top 20 |
| `generatedAt` | string (date-time) | yes |  |

<h2 id="schema-serverplayerinput"><code>ServerPlayerInput</code></h2>

| 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 |

<h2 id="schema-serverplayer"><code>ServerPlayer</code></h2>

| 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 |  |

Source: https://developers.filudi.com/docs/api/reference/schemas/

---

# SDK routes

The sdk routes of games-api, with parameters, bodies, responses and request samples.

Generated from `openapi.yaml` of games-api 0.7.0: 13 routes.

- [`POST /v1/sdk/players`](#post-v1-sdk-players): Create an anonymous player and its token
- [`POST /v1/sdk/game-tokens`](#post-v1-sdk-game-tokens): Exchange a player token for a token limited to one game (ADR 0013)
- [`GET /v1/sdk/players/me`](#get-v1-sdk-players-me): Current player
- [`PATCH /v1/sdk/players/me`](#patch-v1-sdk-players-me): Change nickname or locale
- [`POST /v1/sdk/sessions`](#post-v1-sdk-sessions): Open a play session and get the score-signing key
- [`GET /v1/sdk/saves`](#get-v1-sdk-saves): List the player's saves (metadata only)
- [`GET /v1/sdk/saves/{gameId}`](#get-v1-sdk-saves-gameid): Read a save
- [`PUT /v1/sdk/saves/{gameId}`](#put-v1-sdk-saves-gameid): Write a save
- [`DELETE /v1/sdk/saves/{gameId}`](#delete-v1-sdk-saves-gameid): Delete a save
- [`GET /v1/sdk/leaderboards/{gameId}/{board}`](#get-v1-sdk-leaderboards-gameid-board): Top entries
- [`GET /v1/sdk/leaderboards/{gameId}/{board}/me`](#get-v1-sdk-leaderboards-gameid-board-me): The player's own entry
- [`POST /v1/sdk/leaderboards/{gameId}/{board}/scores`](#post-v1-sdk-leaderboards-gameid-board-scores): Submit a signed score
- [`POST /v1/sdk/events`](#post-v1-sdk-events): Batch of events

<RouteHeading id="post-v1-sdk-players" method="POST" path="/v1/sdk/players" />

<CodePanel title="POST /v1/sdk/players">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/players' \
      -H 'content-type: application/json' \
      -d '{
      "site": "filudi",
      "locale": "en"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/sdk/players', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        site: 'filudi',
        locale: 'en',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    response = requests.post(
        'https://api.filudi.com/v1/sdk/players',
        json={
            'site': 'filudi',
            'locale': 'en',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Create an anonymous player and its token**

Credential: none. The route is public.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `site` | string | yes | Site slug |
| `locale` | string | no |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [PlayerWithToken](/docs/api/reference/schemas/#schema-playerwithtoken) | Player and token. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

<RouteHeading id="post-v1-sdk-game-tokens" method="POST" path="/v1/sdk/game-tokens" />

<CodePanel title="POST /v1/sdk/game-tokens">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/game-tokens' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "game": "gloop"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/sdk/game-tokens', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        game: 'gloop',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.post(
        'https://api.filudi.com/v1/sdk/game-tokens',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'game': 'gloop',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Exchange a player token for a token limited to one game (ADR 0013)**

Called by the hub, never by a game. Refuses a game token. Limited to 240 per player per hour.
A game token (`fg1`) is valid 24 hours on these routes, for its own game: `GET /v1/sdk/players/me`
(`emailMasked` null, `hasPassword` false), `/v1/sdk/saves/{gameId}`, `POST /v1/sdk/sessions`,
`/v1/sdk/leaderboards/{gameId}/*`, `POST /v1/sdk/events` (403 when an item names another game).
Those routes answer 403 for another game. Every other route that needs a player answers 401.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `game` | string | yes | Game slug |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [GameToken](/docs/api/reference/schemas/#schema-gametoken) | Game token. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

<RouteHeading id="get-v1-sdk-players-me" method="GET" path="/v1/sdk/players/me" />

<CodePanel title="GET /v1/sdk/players/me">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/sdk/players/me' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    const response = await fetch('https://api.filudi.com/v1/sdk/players/me', {
      headers: { authorization: `Bearer ${playerToken}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    response = requests.get(
        'https://api.filudi.com/v1/sdk/players/me',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Current player**

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) also opens this route, for its own game only.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Player](/docs/api/reference/schemas/#schema-player) | Player. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |

<RouteHeading id="patch-v1-sdk-players-me" method="PATCH" path="/v1/sdk/players/me" />

<CodePanel title="PATCH /v1/sdk/players/me">
  <Fragment slot="curl">

    ```sh
    curl -X PATCH 'https://api.filudi.com/v1/sdk/players/me' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "nickname": "string",
      "locale": "en"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/sdk/players/me', {
      method: 'PATCH',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        nickname: 'string',
        locale: 'en',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.patch(
        'https://api.filudi.com/v1/sdk/players/me',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'nickname': 'string',
            'locale': 'en',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Change nickname or locale**

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `nickname` | string | no | 3 to 20 characters; pattern `^[\p{L}\p{N} _.-]+$` |
| `locale` | string | no |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Player](/docs/api/reference/schemas/#schema-player) | Updated player. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |

<RouteHeading id="post-v1-sdk-sessions" method="POST" path="/v1/sdk/sessions" />

<CodePanel title="POST /v1/sdk/sessions">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/sessions' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "gameId": "gloop",
      "gameVersion": "1.0.0",
      "host": "filudi"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    const response = await fetch('https://api.filudi.com/v1/sdk/sessions', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        gameId: 'gloop',
        gameVersion: '1.0.0',
        host: 'filudi',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    response = requests.post(
        'https://api.filudi.com/v1/sdk/sessions',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'gameId': 'gloop',
            'gameVersion': '1.0.0',
            'host': 'filudi',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Open a play session and get the score-signing key**

Called by `gameplay.start()`. The key is HMAC-SHA256(version secret, session id),
base64url. Valid 6 hours. The API rejects scores submitted outside a session.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) also opens this route, for its own game only.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `gameId` | string | yes | Game slug |
| `gameVersion` | string | no | Bundle version; defaults to the live one |
| `host` | string | no | default `"filudi"` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | object | Session. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |
| 503 | none | Redis is down, no session can open. |

**Body of 201**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `sessionId` | string (uuid) | yes |  |
| `sessionKey` | string | yes |  |
| `expiresAt` | string (date-time) | yes |  |

<RouteHeading id="get-v1-sdk-saves" method="GET" path="/v1/sdk/saves" />

<CodePanel title="GET /v1/sdk/saves">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/sdk/saves' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players
    const response = await fetch('https://api.filudi.com/v1/sdk/saves', {
      headers: { authorization: `Bearer ${playerToken}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players
    response = requests.get(
        'https://api.filudi.com/v1/sdk/saves',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**List the player's saves (metadata only)**

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) answers 401 here.

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [SaveMeta](/docs/api/reference/schemas/#schema-savemeta)[] | Saves. |

<RouteHeading id="get-v1-sdk-saves-gameid" method="GET" path="/v1/sdk/saves/{gameId}" />

<CodePanel title="GET /v1/sdk/saves/{gameId}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/sdk/saves/gloop' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    const response = await fetch('https://api.filudi.com/v1/sdk/saves/gloop', {
      headers: { authorization: `Bearer ${playerToken}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    response = requests.get(
        'https://api.filudi.com/v1/sdk/saves/gloop',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Read a save**

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) also opens this route, for its own game only.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Save](/docs/api/reference/schemas/#schema-save) | Save. Headers: `ETag`. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="put-v1-sdk-saves-gameid" method="PUT" path="/v1/sdk/saves/{gameId}" />

<CodePanel title="PUT /v1/sdk/saves/{gameId}">
  <Fragment slot="curl">

    ```sh
    curl -X PUT 'https://api.filudi.com/v1/sdk/saves/gloop' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'if-match: string' \
      -H 'content-type: application/json' \
      -d '{
      "version": 1,
      "data": {}
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    const response = await fetch('https://api.filudi.com/v1/sdk/saves/gloop', {
      method: 'PUT',
      headers: { authorization: `Bearer ${playerToken}`, 'if-match': 'string', 'content-type': 'application/json' },
      body: JSON.stringify({
        version: 1,
        data: {},
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    response = requests.put(
        'https://api.filudi.com/v1/sdk/saves/gloop',
        headers={'authorization': f'Bearer {player_token}', 'if-match': 'string'},
        json={
            'version': 1,
            'data': {},
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Write a save**

`If-Match` carries the version the client last saw (0 for none). The server accepts when
the new version is greater than the stored one and `If-Match` equals the stored version.
Otherwise 409 with the server copy.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) also opens this route, for its own game only.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |
| `If-Match` | header | string | yes | Stored version as a quoted integer, e.g. "12" |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | integer | yes | at least 1 |
| `data` | any | yes | Any JSON value, 64 kB max serialized |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [SaveMeta](/docs/api/reference/schemas/#schema-savemeta) | Saved. Headers: `ETag`. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 409 | [SaveServerCopy](/docs/api/reference/schemas/#schema-saveservercopy) | Server has another version, or none yet (version 0). |
| 413 | [Error](/docs/api/reference/schemas/#schema-error) | Body over the limit. |

<RouteHeading id="delete-v1-sdk-saves-gameid" method="DELETE" path="/v1/sdk/saves/{gameId}" />

<CodePanel title="DELETE /v1/sdk/saves/{gameId}">
  <Fragment slot="curl">

    ```sh
    curl -X DELETE 'https://api.filudi.com/v1/sdk/saves/gloop' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    const response = await fetch('https://api.filudi.com/v1/sdk/saves/gloop', {
      method: 'DELETE',
      headers: { authorization: `Bearer ${playerToken}` },
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    response = requests.delete(
        'https://api.filudi.com/v1/sdk/saves/gloop',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Delete a save**

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) also opens this route, for its own game only.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 204 | none | Deleted or absent. |

<RouteHeading id="get-v1-sdk-leaderboards-gameid-board" method="GET" path="/v1/sdk/leaderboards/{gameId}/{board}" />

<CodePanel title="GET /v1/sdk/leaderboards/{gameId}/{board}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/sdk/leaderboards/gloop/height' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    const response = await fetch('https://api.filudi.com/v1/sdk/leaderboards/gloop/height', {
      headers: { authorization: `Bearer ${playerToken}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    response = requests.get(
        'https://api.filudi.com/v1/sdk/leaderboards/gloop/height',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Top entries**

Credential, optional: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) also opens this route, for its own game only. Without a token the answer is the anonymous one.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |
| `board` | path | string | yes | pattern `^[a-z][a-z0-9_]{0,31}$` |
| `period` | query | one of `"day"`, `"week"`, `"all"` | no | default `"all"` |
| `limit` | query | integer | no | 1 to 50; default `10` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [LeaderboardTop](/docs/api/reference/schemas/#schema-leaderboardtop) | Top entries; `isMe` is set when a token is sent. Headers: `Cache-Control`. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |

<RouteHeading id="get-v1-sdk-leaderboards-gameid-board-me" method="GET" path="/v1/sdk/leaderboards/{gameId}/{board}/me" />

<CodePanel title="GET /v1/sdk/leaderboards/{gameId}/{board}/me">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/sdk/leaderboards/gloop/height/me' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    const response = await fetch('https://api.filudi.com/v1/sdk/leaderboards/gloop/height/me', {
      headers: { authorization: `Bearer ${playerToken}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    response = requests.get(
        'https://api.filudi.com/v1/sdk/leaderboards/gloop/height/me',
        headers={'authorization': f'Bearer {player_token}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**The player's own entry**

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) also opens this route, for its own game only.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |
| `board` | path | string | yes | pattern `^[a-z][a-z0-9_]{0,31}$` |
| `period` | query | one of `"day"`, `"week"`, `"all"` | no | default `"all"` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | object | Entry or null. |

**Body of 200**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `period` | [Period](/docs/api/reference/schemas/#schema-period) | yes | default `"all"` |
| `entry` | [LeaderboardEntry](/docs/api/reference/schemas/#schema-leaderboardentry) or null | yes |  |

<RouteHeading id="post-v1-sdk-leaderboards-gameid-board-scores" method="POST" path="/v1/sdk/leaderboards/{gameId}/{board}/scores" />

<CodePanel title="POST /v1/sdk/leaderboards/{gameId}/{board}/scores">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/leaderboards/gloop/height/scores' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "score": 0,
      "meta": {
        "en": "string"
      },
      "sessionId": "00000000-0000-0000-0000-000000000000",
      "nonce": "string",
      "ts": 0,
      "sig": "string"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    const response = await fetch('https://api.filudi.com/v1/sdk/leaderboards/gloop/height/scores', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        score: 0,
        meta: {
          en: 'string',
        },
        sessionId: '00000000-0000-0000-0000-000000000000',
        nonce: 'string',
        ts: 0,
        sig: 'string',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    response = requests.post(
        'https://api.filudi.com/v1/sdk/leaderboards/gloop/height/scores',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'score': 0,
            'meta': {
                'en': 'string',
            },
            'sessionId': '00000000-0000-0000-0000-000000000000',
            'nonce': 'string',
            'ts': 0,
            'sig': 'string',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Submit a signed score**

`sig` = base64url(HMAC-SHA256(sessionKey, `${playerId}|${gameId}|${board}|${score}|${nonce}|${ts}`)).
`ts` is unix milliseconds, within 5 minutes of server time. The API accepts a nonce once per session.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) also opens this route, for its own game only.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |
| `board` | path | string | yes | pattern `^[a-z][a-z0-9_]{0,31}$` |

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `score` | integer | yes |  |
| `meta` | object | no | 512 bytes max |
| `meta.*` | string or number | no |  |
| `sessionId` | string (uuid) | yes |  |
| `nonce` | string | yes | 16 to 64 characters |
| `ts` | integer | yes |  |
| `sig` | string | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | object | Accepted. |
| 400 | object | Rejected. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

**Body of 201**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `rank` | object | yes | 0 when Redis could not rank the score; the next rebuild fixes it |
| `rank.day` | integer | yes |  |
| `rank.week` | integer | yes |  |
| `rank.all` | integer | yes |  |
| `best` | boolean | yes | New personal best on this board |

**Body of 400**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `"invalid"` | yes |  |
| `reason` | one of `"bounds"`, `"signature"`, `"session"`, `"board"`, `"nonce"`, `"clock"`, `"meta"` | yes |  |
| `message` | string | no |  |

<RouteHeading id="post-v1-sdk-events" method="POST" path="/v1/sdk/events" />

<CodePanel title="POST /v1/sdk/events">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/events' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{
      "events": [
        {
          "name": "string",
          "props": {
            "en": "string"
          },
          "ts": 0,
          "gameId": "gloop",
          "gameVersion": "1.0.0",
          "sessionId": "00000000-0000-0000-0000-000000000000",
          "host": "string",
          "locale": "en"
        }
      ]
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // playerToken: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    const response = await fetch('https://api.filudi.com/v1/sdk/events', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        events: [{
          name: 'string',
          props: {
            en: 'string',
          },
          ts: 0,
          gameId: 'gloop',
          gameVersion: '1.0.0',
          sessionId: '00000000-0000-0000-0000-000000000000',
          host: 'string',
          locale: 'en',
        }],
      }),
    });
    // No body: check response.ok.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # player_token: the fp1 token of POST /v1/sdk/players, or the fg1 game token of this game
    response = requests.post(
        'https://api.filudi.com/v1/sdk/events',
        headers={'authorization': f'Bearer {player_token}'},
        json={
            'events': [{
                'name': 'string',
                'props': {
                    'en': 'string',
                },
                'ts': 0,
                'gameId': 'gloop',
                'gameVersion': '1.0.0',
                'sessionId': '00000000-0000-0000-0000-000000000000',
                'host': 'string',
                'locale': 'en',
            }],
        },
    )
    response.raise_for_status()
    # No body: the status says it all.
    ```

  </Fragment>
</CodePanel>

**Batch of events**

The SDK sends `application/json` normally and the same JSON body as `text/plain` from a
keepalive fetch on page hide (`sendBeacon` only on portals, without a token). The API parses both as JSON. 64 kB max.
With a game token, an item that names another game refuses the whole batch with 403, and an item that names none takes the token's game.

Credential: a player token (`fp1`), sent as `Authorization: Bearer <token>`. A game token (`fg1`) also opens this route, for its own game only.

### Request body

`application/json`, required, also accepted as `text/plain`. The body is a [EventBatch](/docs/api/reference/schemas/#schema-eventbatch).

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | [EventIn](/docs/api/reference/schemas/#schema-eventin)[] | yes | at most 50 items |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 202 | none | Queued for write; the API drops invalid items and counts them in metrics. |
| 400 | none | More than 50 items, or a body that is not a batch. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | Missing or invalid token. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | Not allowed for this role or site. |
| 413 | [Error](/docs/api/reference/schemas/#schema-error) | Body over the limit. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

Source: https://developers.filudi.com/docs/api/reference/sdk/

---

# Server routes

Routes for portal backends, authenticated by a site key (ADR 0015)

Routes for portal backends, authenticated by a site key (ADR 0015). Generated from `openapi.yaml` of games-api 0.7.0: 8 routes.

- [`GET /v1/server/catalog`](#get-v1-server-catalog): The site's catalog
- [`POST /v1/server/players`](#post-v1-server-players): Create or find a player by your own user id
- [`GET /v1/server/players/{playerId}`](#get-v1-server-players-playerid): Profile, saves metadata and best scores of one of the site's players
- [`POST /v1/server/players/{playerId}/tokens`](#post-v1-server-players-playerid-tokens): A player token for that player's browser
- [`POST /v1/server/game-tokens`](#post-v1-server-game-tokens): A game token for a player and a game
- [`GET /v1/server/leaderboards/{gameId}/{board}`](#get-v1-server-leaderboards-gameid-board): Top entries with nicknames
- [`GET /v1/server/stats/overview`](#get-v1-server-stats-overview): The site's numbers for a range of UTC days
- [`GET /v1/server/stats/games/{gameId}`](#get-v1-server-stats-games-gameid): One game's numbers on the site for a range of UTC days

<RouteHeading id="get-v1-server-catalog" method="GET" path="/v1/server/catalog" />

<CodePanel title="GET /v1/server/catalog">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/server/catalog' \
      -H "authorization: Bearer $FILUDI_SITE_KEY"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // siteKey: an fsk_ key of the site, created in the console; server side only
    const response = await fetch('https://api.filudi.com/v1/server/catalog', {
      headers: { authorization: `Bearer ${siteKey}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # site_key: an fsk_ key of the site, created in the console
    response = requests.get(
        'https://api.filudi.com/v1/server/catalog',
        headers={'authorization': f'Bearer {site_key}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**The site's catalog**

Scope `catalog`. Same shape as `GET /v1/catalog/{site}` for the key's site, with `Cache-Control: private, max-age=60`.

Credential: a server key (`fsk_…`), sent as `Authorization: Bearer <key>` from your backend, never from a browser. Scope `catalog`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locale` | query | string | no | Returns texts for one locale only; default returns every locale of the site |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [Catalog](/docs/api/reference/schemas/#schema-catalog) | Catalog. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | No bearer, or a key the API does not know. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | The key lacks the scope of this route, is revoked, or its site is not approved; `message` says which. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

<RouteHeading id="post-v1-server-players" method="POST" path="/v1/server/players" />

<CodePanel title="POST /v1/server/players">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/server/players' \
      -H "authorization: Bearer $FILUDI_SITE_KEY" \
      -H 'content-type: application/json' \
      -d '{
      "externalId": "string",
      "nickname": "string",
      "locale": "en"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // siteKey: an fsk_ key of the site, created in the console; server side only
    const response = await fetch('https://api.filudi.com/v1/server/players', {
      method: 'POST',
      headers: { authorization: `Bearer ${siteKey}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        externalId: 'string',
        nickname: 'string',
        locale: 'en',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # site_key: an fsk_ key of the site, created in the console
    response = requests.post(
        'https://api.filudi.com/v1/server/players',
        headers={'authorization': f'Bearer {site_key}'},
        json={
            'externalId': 'string',
            'nickname': 'string',
            'locale': 'en',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Create or find a player by your own user id**

Scope `players`. `externalId` is unique per site: an existing player answers 200, a new one 201. A player
created here is a guest with no token until `POST /v1/server/players/{playerId}/tokens`. `nickname` and
`locale` are applied on creation only; change them later with the player token on `PATCH /v1/sdk/players/me`.

Credential: a server key (`fsk_…`), sent as `Authorization: Bearer <key>` from your backend, never from a browser. Scope `players`.

### Request body

`application/json`, required. The body is a [ServerPlayerInput](/docs/api/reference/schemas/#schema-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 |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [ServerPlayer](/docs/api/reference/schemas/#schema-serverplayer) | Existing player. |
| 201 | [ServerPlayer](/docs/api/reference/schemas/#schema-serverplayer) | Created. |
| 400 | [Error](/docs/api/reference/schemas/#schema-error) | Validation failed. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | No bearer, or a key the API does not know. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | The key lacks the scope of this route, is revoked, or its site is not approved; `message` says which. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

<RouteHeading id="get-v1-server-players-playerid" method="GET" path="/v1/server/players/{playerId}" />

<CodePanel title="GET /v1/server/players/{playerId}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/server/players/00000000-0000-0000-0000-000000000000' \
      -H "authorization: Bearer $FILUDI_SITE_KEY"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // siteKey: an fsk_ key of the site, created in the console; server side only
    const response = await fetch('https://api.filudi.com/v1/server/players/00000000-0000-0000-0000-000000000000', {
      headers: { authorization: `Bearer ${siteKey}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # site_key: an fsk_ key of the site, created in the console
    response = requests.get(
        'https://api.filudi.com/v1/server/players/00000000-0000-0000-0000-000000000000',
        headers={'authorization': f'Bearer {site_key}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Profile, saves metadata and best scores of one of the site's players**

Scope `players`. 404 for a player of another site.

Credential: a server key (`fsk_…`), sent as `Authorization: Bearer <key>` from your backend, never from a browser. Scope `players`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `playerId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [PlayerAdmin](/docs/api/reference/schemas/#schema-playeradmin) | Player. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | No bearer, or a key the API does not know. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | The key lacks the scope of this route, is revoked, or its site is not approved; `message` says which. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

<RouteHeading id="post-v1-server-players-playerid-tokens" method="POST" path="/v1/server/players/{playerId}/tokens" />

<CodePanel title="POST /v1/server/players/{playerId}/tokens">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/server/players/00000000-0000-0000-0000-000000000000/tokens' \
      -H "authorization: Bearer $FILUDI_SITE_KEY"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // siteKey: an fsk_ key of the site, created in the console; server side only
    const response = await fetch('https://api.filudi.com/v1/server/players/00000000-0000-0000-0000-000000000000/tokens', {
      method: 'POST',
      headers: { authorization: `Bearer ${siteKey}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # site_key: an fsk_ key of the site, created in the console
    response = requests.post(
        'https://api.filudi.com/v1/server/players/00000000-0000-0000-0000-000000000000/tokens',
        headers={'authorization': f'Bearer {site_key}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**A player token for that player's browser**

Scope `tokens`. An `fp1` token, as `POST /v1/sdk/players` answers, so your page runs `GameFrame` or the SDK
as filudi.com does. Hand it to the browser over your own authenticated channel.

Credential: a server key (`fsk_…`), sent as `Authorization: Bearer <key>` from your backend, never from a browser. Scope `tokens`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `playerId` | path | string (uuid) | yes |  |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | object | Token. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | No bearer, or a key the API does not know. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | The key lacks the scope of this route, is revoked, or its site is not approved; `message` says which. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

**Body of 201**

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | yes |  |

<RouteHeading id="post-v1-server-game-tokens" method="POST" path="/v1/server/game-tokens" />

<CodePanel title="POST /v1/server/game-tokens">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/server/game-tokens' \
      -H "authorization: Bearer $FILUDI_SITE_KEY" \
      -H 'content-type: application/json' \
      -d '{
      "playerId": "00000000-0000-0000-0000-000000000000",
      "game": "gloop"
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // siteKey: an fsk_ key of the site, created in the console; server side only
    const response = await fetch('https://api.filudi.com/v1/server/game-tokens', {
      method: 'POST',
      headers: { authorization: `Bearer ${siteKey}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        playerId: '00000000-0000-0000-0000-000000000000',
        game: 'gloop',
      }),
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # site_key: an fsk_ key of the site, created in the console
    response = requests.post(
        'https://api.filudi.com/v1/server/game-tokens',
        headers={'authorization': f'Bearer {site_key}'},
        json={
            'playerId': '00000000-0000-0000-0000-000000000000',
            'game': 'gloop',
        },
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**A game token for a player and a game**

Scope `tokens`. The same token as `POST /v1/sdk/game-tokens` answers (ADR 0013), without the player's own token.

Credential: a server key (`fsk_…`), sent as `Authorization: Bearer <key>` from your backend, never from a browser. Scope `tokens`.

### Request body

`application/json`, required.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `playerId` | string (uuid) | yes |  |
| `game` | string | yes | Game slug |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 201 | [GameToken](/docs/api/reference/schemas/#schema-gametoken) | Game token. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | No bearer, or a key the API does not know. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | The key lacks the scope of this route, is revoked, or its site is not approved; `message` says which. |
| 404 | none | Unknown player on this site, or the game is not on the site catalog. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

<RouteHeading id="get-v1-server-leaderboards-gameid-board" method="GET" path="/v1/server/leaderboards/{gameId}/{board}" />

<CodePanel title="GET /v1/server/leaderboards/{gameId}/{board}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/server/leaderboards/gloop/height' \
      -H "authorization: Bearer $FILUDI_SITE_KEY"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // siteKey: an fsk_ key of the site, created in the console; server side only
    const response = await fetch('https://api.filudi.com/v1/server/leaderboards/gloop/height', {
      headers: { authorization: `Bearer ${siteKey}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # site_key: an fsk_ key of the site, created in the console
    response = requests.get(
        'https://api.filudi.com/v1/server/leaderboards/gloop/height',
        headers={'authorization': f'Bearer {site_key}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**Top entries with nicknames**

Scope `leaderboards`. Same answer as `GET /v1/sdk/leaderboards/{gameId}/{board}`; `isMe` is always false.

Credential: a server key (`fsk_…`), sent as `Authorization: Bearer <key>` from your backend, never from a browser. Scope `leaderboards`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string | yes | Game slug |
| `board` | path | string | yes | pattern `^[a-z][a-z0-9_]{0,31}$` |
| `period` | query | one of `"day"`, `"week"`, `"all"` | no | default `"all"` |
| `limit` | query | integer | no | 1 to 50; default `10` |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [LeaderboardTop](/docs/api/reference/schemas/#schema-leaderboardtop) | Top entries. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | No bearer, or a key the API does not know. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | The key lacks the scope of this route, is revoked, or its site is not approved; `message` says which. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

<RouteHeading id="get-v1-server-stats-overview" method="GET" path="/v1/server/stats/overview" />

<CodePanel title="GET /v1/server/stats/overview">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/server/stats/overview?from=2026-10-30&to=2026-10-30' \
      -H "authorization: Bearer $FILUDI_SITE_KEY"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // siteKey: an fsk_ key of the site, created in the console; server side only
    const response = await fetch('https://api.filudi.com/v1/server/stats/overview?from=2026-10-30&to=2026-10-30', {
      headers: { authorization: `Bearer ${siteKey}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # site_key: an fsk_ key of the site, created in the console
    response = requests.get(
        'https://api.filudi.com/v1/server/stats/overview?from=2026-10-30&to=2026-10-30',
        headers={'authorization': f'Bearer {site_key}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**The site's numbers for a range of UTC days**

Scope `stats`. Same answer and range rules as `GET /v1/admin/sites/{siteId}/stats/overview`.

Credential: a server key (`fsk_…`), sent as `Authorization: Bearer <key>` from your backend, never from a browser. Scope `stats`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date) | yes | First UTC day, included |
| `to` | query | string (date) | yes | Last UTC day, included |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [StatsOverview](/docs/api/reference/schemas/#schema-statsoverview) | Overview. |
| 400 | none | Range over 400 days, or `to` before `from`. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | No bearer, or a key the API does not know. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | The key lacks the scope of this route, is revoked, or its site is not approved; `message` says which. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

<RouteHeading id="get-v1-server-stats-games-gameid" method="GET" path="/v1/server/stats/games/{gameId}" />

<CodePanel title="GET /v1/server/stats/games/{gameId}">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/server/stats/games/00000000-0000-0000-0000-000000000000?from=2026-10-30&to=2026-10-30' \
      -H "authorization: Bearer $FILUDI_SITE_KEY"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // siteKey: an fsk_ key of the site, created in the console; server side only
    const response = await fetch('https://api.filudi.com/v1/server/stats/games/00000000-0000-0000-0000-000000000000?from=2026-10-30&to=2026-10-30', {
      headers: { authorization: `Bearer ${siteKey}` },
    });
    const data = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    # site_key: an fsk_ key of the site, created in the console
    response = requests.get(
        'https://api.filudi.com/v1/server/stats/games/00000000-0000-0000-0000-000000000000?from=2026-10-30&to=2026-10-30',
        headers={'authorization': f'Bearer {site_key}'},
    )
    response.raise_for_status()
    data = response.json()
    ```

  </Fragment>
</CodePanel>

**One game's numbers on the site for a range of UTC days**

Scope `stats`. Same answer as `GET /v1/admin/sites/{siteId}/stats/games/{gameId}`. 404 when the game is not on the site catalog.

Credential: a server key (`fsk_…`), sent as `Authorization: Bearer <key>` from your backend, never from a browser. Scope `stats`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gameId` | path | string (uuid) | yes |  |
| `from` | query | string (date) | yes | First UTC day, included |
| `to` | query | string (date) | yes | Last UTC day, included |

### Responses

| Status | Body | Description |
| --- | --- | --- |
| 200 | [GameStats](/docs/api/reference/schemas/#schema-gamestats) | Game stats. |
| 400 | none | Range over 400 days, or `to` before `from`. |
| 401 | [Error](/docs/api/reference/schemas/#schema-error) | No bearer, or a key the API does not know. |
| 403 | [Error](/docs/api/reference/schemas/#schema-error) | The key lacks the scope of this route, is revoked, or its site is not approved; `message` says which. |
| 404 | [Error](/docs/api/reference/schemas/#schema-error) | Unknown resource. |
| 429 | [Error](/docs/api/reference/schemas/#schema-error) | Too many requests. Headers: `Retry-After`. |

Source: https://developers.filudi.com/docs/api/reference/server/

---

# Versioning

The /v1 prefix, how the Filudi API changes without breaking a client, and where the version of this reference comes from.

Every route starts with `/v1`. The prefix changes only when a route stops answering what it answered before.
Within `/v1` the API grows by addition: a new route, a new optional field in a body, a new field in an answer.
A client that ignores fields it does not know keeps working.

## What a client may rely on

- A field listed as required in a response schema is present. A field marked nullable may be null.
- An enum may gain a value. Treat an unknown value as "other", never as an error. `CategoryIcon` is the usual
  case: hub-core draws nothing for an icon name it does not know yet.
- A route that disappears is announced in the release notes of the platform first and answers 404 afterwards.
- The error body keeps its shape and its codes.

## Where the version comes from

The API is released as `games-api <version>`, the version in `info.version` of `openapi.yaml`. Each reference
page states the version it was generated from, in its first paragraph. The published packages have versions of
their own: `@filudi/game-sdk` and `@filudi/hub-core` on npmjs.com follow semver, with release notes written by
Changesets. Pin them exactly (`pnpm add -E`).

## Development only

`GET`, `PUT` and `HEAD /v1/_local-files/{path}` stand in for the files service on a local API without
`FILES_URL`. They are not part of the API and are not in this reference.

Source: https://developers.filudi.com/docs/api/versioning/

---

# Games

How a game gets on filudi.com and on portals, from the invitation to a version under review.

From the invitation to a version under review, and everything a game can do on filudi.com and on portals.
Start with the account and the console, then build your first bundle.

| Page                                                        | What it covers                                                                         |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Start here](/docs/games/start-here/)                       | The invitation, the account, the console, the review step                              |
| [Your first bundle](/docs/games/first-bundle/)              | The playground and its mock host, the zip, the upload, the preview, the review request |
| [Game lifecycle on filudi.com](/docs/games/lifecycle/)      | The handshake, the game token, the origin per game, the CSP, what a game cannot do     |
| [Saves](/docs/games/saves/)                                 | One blob, a version the game increments, conflicts, the migration of an old save       |
| [Leaderboards](/docs/games/leaderboards/)                   | Declaring boards, picking bounds, signed scores, what the hub draws                    |
| [Events and statistics](/docs/games/events-and-statistics/) | What to track and what the console shows for it                                        |
| [Ads on portals](/docs/games/ads/)                          | Where ads come from, the three rules, filudi.com today                                 |
| [Localization](/docs/games/localization/)                   | Locales on each host, what to translate, what the hub translates                       |
| [Release checklist](/docs/games/release-checklist/)         | The checks to run on a build before zipping it                                         |
| [Portals](/docs/games/portals/)                             | CrazyGames, Poki and Playgama specifics                                                |

The [SDK reference](/docs/sdk/) has one page per module. A coding agent can load the
[`filudi-game-sdk` skill](/skills/) and do the integration with you.

Source: https://developers.filudi.com/docs/games/

---

# Ads on portals

Where ads come from on each host, the three rules a game follows, and the fact that filudi.com has none yet.

filudi.com has no ad network today. Both ad kinds answer `unavailable` with reason `host` there, and the
console shows nothing about revenue. On CrazyGames, Poki and Playgama the same calls show the portal's ads.
Write the game so that it is complete without them.

## Where ads come from

| Host       | Rewarded                                                                          | Interstitial                          | Pacing                                                                                       |
| ---------- | --------------------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------- |
| filudi.com | `unavailable: host`                                                               | `unavailable: host`                   | The SDK keeps a 120 s interval so the day an ad network exists, nothing changes in your game |
| CrazyGames | `requestAd('rewarded')`                                                           | `requestAd('midgame')`                | The portal's                                                                                 |
| Poki       | `rewardedBreak`: `completed` on `true`, `skipped` on `false`                      | `commercialBreak`: always `completed` | The portal's                                                                                 |
| Playgama   | `showRewarded`: `rewarded` then `closed` is `completed`, `closed` alone `skipped` | `showInterstitial`                    | The portal's                                                                                 |
| mock       | What `mock.ads` says: `fill`, `no-fill`, `adblock`, `error`                       | Same                                  | 120 s                                                                                        |

On filudi.com an ad request goes to the hub, which answers with a result. No ad script runs inside your
bundle on any host: the SDK loads the portal's script on the portal's own page.

## The three rules

1. Bracket play with `gameplay.start()` and `stop()`, never around an ad. The SDK stops play before an ad
   and starts it again after.
2. Mute on `sdk.ads.on('start')`, unmute on `sdk.ads.on('end')`. Not when you request the ad: a refused ad
   never starts and the game would stay silent.
3. Grant the reward on `status === 'completed'` only. Hide the button when `sdk.ads.available().rewarded`
   is false, and read that each time you draw the button.

<CodePanel title="The three rules in code">
  <Fragment slot="javascript">
    ```js
    sdk.ads.on('start', () => audio.mute());
    sdk.ads.on('end', () => audio.unmute());

    function showGameOver() {
      lifeButton.hidden = usedLife || !sdk.ads.available().rewarded;
    }

    lifeButton.addEventListener('click', async () => {
      lifeButton.hidden = true;
      if ((await sdk.ads.rewarded()).status === 'completed') secondLife();
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    sdk.ads.on('start', () => audio.mute());
    sdk.ads.on('end', () => audio.unmute());

    function showGameOver(): void {
      lifeButton.hidden = usedLife || !sdk.ads.available().rewarded;
    }

    lifeButton.addEventListener('click', async () => {
      lifeButton.hidden = true;
      if ((await sdk.ads.rewarded()).status === 'completed') secondLife();
    });
    ```

  </Fragment>
</CodePanel>

## Where to put an interstitial

At a natural break, after `gameplay.stop()`: every few game overs, between levels, never in the middle of
play and never before the first frame. The SDK refuses one inside the host's interval with `too-soon`; a
game that asks too often sees that status and nothing else. Keep your own counter (every third game over)
so the game feels the same on every host.

## Policy and consent

`policy.personalizedAds` from `init()` is false on a kids site or without consent; the portal or the hub
applies it, your game does not have to. Without ad consent on filudi.com the answer is `unavailable: policy`.
`sdk.on('consent', ...)` tells you when the player changes it, and `sdk.ads.available()` follows.

## Not offered yet

No ad network on filudi.com, no revenue share, no payment. When that changes, the SDK calls stay the same;
this page and the console will say what is new.

Source: https://developers.filudi.com/docs/games/ads/

---

# Events and statistics

What the console shows about your game, where each number comes from, and what to track yourself.

The console's Statistics screen covers every site that lists your game, filterable by site, host, version
and locale, over a range of up to 400 days. Most of it comes from the SDK calls your game already makes.
`sdk.track()` adds what only your game knows.

## What you see

| Block          | What it counts                                                       | Where it comes from                                                                    |
| -------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Active players | Per day, rolling 7 days, rolling 30 days; new and returning          | A play session: `gameplay.start()`                                                     |
| Sessions       | Count, mean and median length                                        | `gameplay.start()` to the end of the page or the last `stop()`                         |
| Retention      | D1, D7, D30 as cohorts by first-play week; blank under 10 players    | Sessions per player over time                                                          |
| Funnel         | Frame loaded, play started, save written, score sent, account linked | `ready()`, `gameplay.start()`, `save.set()`, `leaderboard.submit()`, the hub's sign-in |
| Events         | By name, with the number of players                                  | `sdk.track()`                                                                          |
| Splits         | Host, version, locale, device                                        | What the SDK sends with each session and event                                         |
| Boards         | Scores, best, median per board                                       | `leaderboard.submit()`                                                                 |
| Sites          | Sessions and players per site that lists the game                    | The site of each session                                                               |

Every table exports as CSV from the console. Nothing here is about money: filudi.com shows usage only.

## What to track

Track the decisions the funnel cannot see: a level cleared, a difficulty chosen, a tutorial skipped, a shop
opened, a run abandoned. Name events in `snake_case`, keep the set small, and keep the names across
versions; a renamed event starts a new line.

<CodePanel title="Events worth having">
  <Fragment slot="javascript">
    ```js
    sdk.track('level_complete', { level, moves, perfect: moves === par });
    sdk.track('level_fail', { level, reason: 'time' });
    sdk.track('tutorial_skip');
    sdk.track('difficulty_set', { difficulty: 'hard' });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    sdk.track('level_complete', { level, moves, perfect: moves === par });
    sdk.track('level_fail', { level, reason: 'time' });
    sdk.track('tutorial_skip');
    sdk.track('difficulty_set', { difficulty: 'hard' });
    ```

  </Fragment>
</CodePanel>

Limits: a name of at most 40 characters, 20 properties, each value at most 200 characters. The SDK sends 50
events or 5 s of them at a time, and the last batch leaves with the page. `frame_loaded` is reserved for
the hub.

## Version and device

Pass the release version to `init({ version })`. Every session and event carries it, and the version split
is how you compare a release with the previous one. The device is read by the API from the user agent at
session open, as `phone`, `tablet` or `desktop`; nothing else about the browser is kept.

## From portals

Sessions and events on CrazyGames, Poki and Playgama do not reach Filudi by default: no player token exists
there. `init({ events: 'always', eventsUrl })` sends events to the API anonymously, counted for the game's
site under the portal's host. Sessions, saves and scores on portals stay with the portal.

## When numbers appear

Today's events are read live; past days come from a daily rollup. Statistics answers are cached for 60 s.
A new version shows in the version filter after its first session.

Source: https://developers.filudi.com/docs/games/events-and-statistics/

---

# Your first bundle

From the sample game in the playground to a zip uploaded in the console, previewed, and sent for review.

A bundle is a folder with `index.html` at its root, zipped. This page takes the playground's sample game
through every step; your own game follows the same path.

## The playground

The playground loads a bundle in an iframe, plays each host around it and logs every SDK call and host
message. Open [developers.filudi.com/playground/](https://developers.filudi.com/playground/): nothing to
install. If you have the Filudi repository, the same app runs locally from `apps/sdk-playground`.

<CodePanel title="Run the playground from the repository">
  <Fragment slot="javascript">
    ```bash
    pnpm install
    pnpm --filter @filudi/game-sdk build         # the sample game loads dist/filudi-sdk.iife.js
    pnpm --filter @filudi/sdk-playground dev     # http://localhost:5173
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```bash
    pnpm install
    pnpm --filter @filudi/game-sdk build         # the sample game loads dist/filudi-sdk.iife.js
    pnpm --filter @filudi/sdk-playground dev     # http://localhost:5173
    ```

  </Fragment>
</CodePanel>

Pick "Sample game" and the `filudi` host, press Load. The log shows the handshake: `filudi:ready` from the
bundle, `filudi:init` from the host with a game token that starts with `fg1.`, then `filudi:loaded` when
the game calls `ready()`. Tap the canvas: `filudi:gameplay { running: true }`. Fall: the score goes out,
the board comes back, every third fall asks for an interstitial and the host answers with the result you
set. Tick "Mock API" so saves and scores hit an in-memory API and show as requests with their bearer.
Untick it to use a real API: type its origin in "API URL", or open the playground with `?api=`:
`/playground/?host=filudi&mockApi=0&api=https://api.filudi.com` for production,
`api=http://localhost:8080` for the API you run. That API must list the playground's origin in its
`HUB_URLS`, and the game slug must exist on the site, else the log says `game token refused`.

The other hosts install the portal's global in the frame before the bundle runs: `CrazyGames.SDK`,
`PokiSDK`, Playgama's `bridge`. Each call the game makes is a `game→host` line, each answer a `host→game`
line. Change the ad outcome, the data module, the leaderboard type, and watch what the game does.

## The sample game

The sample game is two files, [`index.html`](https://developers.filudi.com/playground/sample-game/index.html)
and [`main.js`](https://developers.filudi.com/playground/sample-game/main.js) (`apps/sdk-playground/public/sample-game/`
in the repository). `main.js` calls every SDK method at least once; it is the shortest complete
integration. Read it next to the [SDK overview](/docs/sdk/).

<CodePanel title="The sample game's boot, in short">
  <Fragment slot="javascript">
    ```js
    const sdk = window.FiludiSDK;

    async function boot() {
      await sdk.init({ gameId: 'infinijump', version: '1.0.0' });
      corner = { nickname: sdk.player.get().nickname, locale: sdk.i18n.locale() };
      applySave(await sdk.save.get());
      sdk.save.on('replaced', applySave);
      sdk.ads.on('start', () => (muted = true));
      sdk.ads.on('end', () => (muted = false));
      requestAnimationFrame(frame);        // the first frame calls sdk.ready()
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import { sdk } from '@filudi/game-sdk';

    async function boot(): Promise<void> {
      await sdk.init({ gameId: 'infinijump', version: '1.0.0' });
      corner = { nickname: sdk.player.get().nickname, locale: sdk.i18n.locale() };
      applySave(await sdk.save.get<{ best: number }>());
      sdk.save.on('replaced', applySave);
      sdk.ads.on('start', () => { muted = true; });
      sdk.ads.on('end', () => { muted = false; });
      requestAnimationFrame(frame);        // the first frame calls sdk.ready()
    }
    ```

  </Fragment>
</CodePanel>

## Your own game in the playground

Run your dev server, choose "Bundle URL", paste `http://localhost:5174/index.html`, pick a host, press
Load. The hosted playground frames a `localhost` URL from its https page: browsers treat `localhost` as
secure. Your server must let the playground's origin frame it, `https://developers.filudi.com` (or
`http://localhost:5173` when you run the playground from the repository): no `X-Frame-Options: DENY`,
and `frame-ancestors` must list it if you send a CSP. The portal hosts fetch your `index.html`, so the
server answers that origin with CORS. Vite's default CORS allows `localhost` origins only: add
`server: { cors: { origin: ['https://developers.filudi.com'] } }` to its config while you test.

Add `<script src="https://developers.filudi.com/playground/sdk-trace.js"></script>` after the SDK script
while you work (`http://localhost:5173/sdk-trace.js` for the local playground): the log then shows each
SDK call. Remove it before the build.

Tick "Production CSP" on the `filudi` host. The playground's server then sends the policy filudi.com
applies to bundles it serves itself, and the log gives you the header to send from your own server. Each
violation shows as a `CSP violation` line. An inline script or a call to another host works without it
and fails in production.

## The zip

Build, then zip the content of the build folder, not the folder itself. `index.html` must be at the root
of the archive. Leave the source maps out unless you want them public.

<CodePanel title="Zip the build">
  <Fragment slot="javascript">
    ```bash
    npm run build
    cd dist && zip -r ../gloop-1.4.0.zip . -x '*.map' && cd ..
    unzip -l gloop-1.4.0.zip | head -5          # index.html first, at the root
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```bash
    pnpm build
    cd dist && zip -r ../gloop-1.4.0.zip . -x '*.map' && cd ..
    unzip -l gloop-1.4.0.zip | head -5          # index.html first, at the root
    ```

  </Fragment>
</CodePanel>

Limits: 200 MB for the zip, 500 MB unpacked, 10,000 files, 64 MB per file, no `..` in a path, no symbolic
link, no encrypted entry. The upload refuses a zip that breaks one and names the entry.

## Upload

In the console, open the game, Versions, "Upload a version". The version string follows semantic
versioning (`1.4.0`, `2.0.0-beta.1`) and is unique for the game. Pass the same string to `init({ version })`
in the build so events carry it. The browser uploads the zip straight to the files service; the console
then finalizes: the API unpacks the zip under `games/<slug>/<version>/`, checks `index.html`, counts files
and bytes. The version is a draft.

## Preview

"Preview" opens a signed link, valid one hour, in a new tab. It serves the draft from the preview host
under the same CSP as production, at the top level. The SDK is on its mock there: check loading, layout
and play. Saves and scores need the frame on filudi.com; the playground covers them.

## Request review

When the draft is right, press "Request review" on the version. Staff gets an email, plays the preview and
activates it. A pending game needs its approval first; the overview says which step is next. Once the
version is live, open the game on filudi.com and play it once: saves, the leaderboard and your statistics
now run against production.

## Next

[Game lifecycle on filudi.com](/docs/games/lifecycle/) explains what happened in that frame. The
[release checklist](/docs/games/release-checklist/) is the list to run before every zip.

Source: https://developers.filudi.com/docs/games/first-bundle/

---

# Leaderboards

Declare boards in the console with bounds the API enforces, submit one signed score per run, and draw what the host gives you.

A board is declared in the console before any score reaches it. The API enforces the bounds and the rate;
the SDK signs each score with the play session on filudi.com. The reference is
[leaderboard](/docs/sdk/leaderboard/).

## Declaring a board

In the console, the game, Leaderboards: add a board, then "Save boards".

| Field           | What it is                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `name`          | `^[a-z][a-z0-9_]{0,31}$`, the string you pass to `submit()`. `height`, `crowns`, `time`                                        |
| `sort`          | `desc` for a score to beat, `asc` for a time to beat                                                                           |
| `min`, `max`    | The API rejects a score outside. Pick the real range of your game, not the integer range: a bound is what stops a forged score |
| `keep`          | `best` keeps the player's best entry, `latest` their last one                                                                  |
| `ratePerMinute` | Scores accepted per player per minute, 10 by default                                                                           |

A board or a meta key named `time` is in seconds and the hub formats it as `m:ss`. Scores are integers:
send tenths of a second as an integer if you need them, and say so in the board's name.

## One score per run

Submit once, when the run ends, after `gameplay.stop()`, in a run that called `gameplay.start()`. The
session opened by `start()` gives the key that signs the score; a score outside a session is rejected with
reason `session`.

<CodePanel title="End of a run">
  <Fragment slot="javascript">
    ```js
    async function endRun() {
      sdk.gameplay.stop();
      const result = await sdk.leaderboard.submit('height', metres, { tries: run.tries, route: run.route });
      if (result.status === 'accepted' && result.best) celebrateBest(result.rank.all);
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    async function endRun(): Promise<void> {
      sdk.gameplay.stop();
      const result = await sdk.leaderboard.submit('height', metres, { tries: run.tries, route: run.route });
      if (result.status === 'accepted' && result.best) celebrateBest(result.rank.all);
    }
    ```

  </Fragment>
</CodePanel>

`meta` is up to 512 bytes of JSON with string and number values, shown next to the score as its detail.
Use it for what explains the score (tries, time, the route taken), not for anything the score already says.

## Drawing a board

`top()` gives up to 10 entries and `me()` the player's own; both take a period. The hub draws the top 5 and
the player's row on the game's page, so an in-game board is for what the hub does not show: a per-level
board, a weekly race, a board under the game's own art. Handle `unavailable`: CrazyGames and Poki draw
their own boards and give you nothing to read.

<CodePanel title="A board in the game">
  <Fragment slot="javascript">
    ```js
    async function drawBoard(period) {
      const [top, me] = await Promise.all([
        sdk.leaderboard.top('height', period),
        sdk.leaderboard.me('height', period),
      ]);
      if (top.status !== 'ok') return hideBoard();
      drawRows(top.entries, me.status === 'ok' ? me.entry : null);
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { Period } from '@filudi/game-sdk';

    async function drawBoard(period: Period): Promise<void> {
      const [top, me] = await Promise.all([
        sdk.leaderboard.top('height', period),
        sdk.leaderboard.me('height', period),
      ]);
      if (top.status !== 'ok') return hideBoard();
      drawRows(top.entries, me.status === 'ok' ? me.entry : null);
    }
    ```

  </Fragment>
</CodePanel>

## Signed scores

On filudi.com the SDK signs `pid|gameId|board|score|nonce|ts` with HMAC-SHA256 and the session key. The API
checks the signature, the nonce (once), the clock (within a window) and the bounds. The game does nothing for
this and cannot weaken it: a bundle that posts a score by hand gets `rejected`. What a forged client can
still do is play badly on purpose; the bounds and the rate are your limits on that, and the console lets you
hide a score.

## On portals

CrazyGames takes scores through `user.submitScore` once you pass the key from its developer portal as
`init({ crazygames: { leaderboardKey } })`. Keep the key in a build variable, never in the repository. Poki
has no leaderboard. Playgama takes scores and, when its board type is `in_game`, gives them back. `rank`
values are 0 where the portal reports none.

## Scores in the console

The game's Leaderboards screen lists the boards and their scores with the nickname, the meta and the date.
Hide a score that should not be there; the entry goes out of `top()` and the player keeps their session.
Statistics give each board's count, best and median.

Source: https://developers.filudi.com/docs/games/leaderboards/

---

# Game lifecycle on filudi.com

The frame, the handshake, the game token, the origin per game, the CSP, and what a game cannot do, in plain words.

A game on filudi.com is a static bundle in a sandboxed frame on a page of the hub. The SDK runs inside the
frame; the hub runs outside. Everything between them is a message. This page says what happens, in order,
and what it means for the code you write.

## Where the bundle lives

Every version is unpacked under `games/<slug>/<version>/` and served through the CDN from
`https://<slug>.<play domain>/<slug>/<version>/index.html`. One origin per game: your bundle shares nothing
with another game, not `localStorage`, not a cookie, not a cache. The host must match the path; the API
answers 404 for game A on the origin of game B. Until the play domain is switched on per game, the same
path is served from `https://play.filudi.com`.

The frame is `sandbox="allow-scripts allow-same-origin allow-pointer-lock"` with `allow="fullscreen;
autoplay"`. The page keeps the top-level navigation, the forms, the popups.

## The handshake

1. The hub opens the frame on the version's URL.
2. Your bundle calls `sdk.init({ gameId })`. The SDK posts `filudi:ready` to the parent and waits 1.5 s
   (`handshakeTimeoutMs`) for an answer.
3. The hub answers `filudi:init`: the API URL, a game token, the slug of the game, the player, the locale,
   the site, the age policy, the consent state, the version string. The SDK accepts it only from
   `window.parent`.
4. `init()` resolves. From here the SDK calls the API itself with the game token: saves, scores, events.
5. Your game draws its first frame and calls `sdk.ready()`. The SDK posts `filudi:loaded`; the hub hides
   its loader and counts the first step of your funnel.

No answer within 1.5 s means the bundle is not in a Filudi frame: the SDK runs on the mock and
`result.host` says so. That is what happens in the preview, which runs at the top level.

<CodePanel title="What the frame receives">
  <Fragment slot="javascript">
    ```js
    // filudi:init, posted by the hub. The SDK reads it; the game never does.
    ({
      type: 'filudi:init',
      apiUrl: 'https://api.filudi.com',
      token: 'fg1.…',                      // game token, opaque, 24 hours
      gameId: 'gloop',
      player: { id: '…', nickname: 'Guest-Fox', guest: true },
      locale: 'fr',
      site: 'filudi',
      policy: { personalizedAds: false, ageBand: 'all', accounts: true },
      consent: { ads: false, analytics: true },
      gameVersion: '1.4.0',
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { FiludiInit } from '@filudi/game-sdk';

    // filudi:init, posted by the hub. The SDK reads it; the game never does.
    const message: FiludiInit = {
      type: 'filudi:init',
      apiUrl: 'https://api.filudi.com',
      token: 'fg1.…',                      // game token, opaque, 24 hours
      gameId: 'gloop',
      player: { id: '…', nickname: 'Guest-Fox', guest: true },
      locale: 'fr',
      site: 'filudi',
      policy: { personalizedAds: false, ageBand: 'all', accounts: true },
      consent: { ads: false, analytics: true },
      gameVersion: '1.4.0',
    };
    ```

  </Fragment>
</CodePanel>

## The game token

The player signs in to filudi.com and has a token of their own. That token never enters your frame. The
hub exchanges it for a game token: limited to your game, to that player, for 24 hours. It opens your saves,
your boards and your events and nothing else. The hub sends a fresh one every 12 hours (`filudi:token`) and
the SDK uses it from the next request, without a reload.

When the API refuses the token, the SDK posts `filudi:unauthorized`, keeps saves in `localStorage` and
stops calling the API; the hub fetches a new token and reloads the frame. Your game sees a reload, nothing
else.

## While the game runs

The SDK posts to the hub: `filudi:gameplay { running }` on `gameplay.start()` and `stop()`, `filudi:save
{ version }` after a write, `filudi:score { board, score, rank }` after a submit, `filudi:track { event }`
after an event, `filudi:fullscreen { request: true }` on `sdk.fullscreen()`, `filudi:ad` to request an ad.
The hub treats each as a claim from an untrusted frame: it may update what the page shows for your game,
and nothing else.

The hub posts to the SDK: `filudi:consent`, `filudi:locale`, `filudi:pause`, `filudi:resume`,
`filudi:token`, and the answers to fullscreen and ad requests. They reach your game as the events of
[host events](/docs/sdk/events/), [i18n](/docs/sdk/i18n/) and [ads](/docs/sdk/ads/).

## The CSP

The bundle route sends a Content Security Policy. Scripts, styles, images, media, fonts and workers load from
the bundle's own origin only, with `blob:` and `data:` allowed for assets and `wasm-unsafe-eval` for
WebAssembly. `fetch`, XHR, WebSocket and EventSource reach the bundle's origin and the API only. No frame
inside the frame, no form post. An inline `<script>`, an `onclick=""` attribute, `eval`, `new Function` and
`setTimeout` with a string throw. Inline styles work.

<CodePanel title="The policy, as sent">
  <Fragment slot="javascript">
    ```text
    default-src 'self'; script-src 'self' 'wasm-unsafe-eval' blob:; style-src 'self' 'unsafe-inline';
    img-src 'self' data: blob:; media-src 'self' data: blob:; font-src 'self' data:;
    connect-src 'self' data: blob: https://api.filudi.com; worker-src 'self' blob:; frame-src 'none';
    object-src 'none'; base-uri 'self'; form-action 'none'; frame-ancestors <site origins>
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```text
    default-src 'self'; script-src 'self' 'wasm-unsafe-eval' blob:; style-src 'self' 'unsafe-inline';
    img-src 'self' data: blob:; media-src 'self' data: blob:; font-src 'self' data:;
    connect-src 'self' data: blob: https://api.filudi.com; worker-src 'self' blob:; frame-src 'none';
    object-src 'none'; base-uri 'self'; form-action 'none'; frame-ancestors <site origins>
    ```

  </Fragment>
</CodePanel>

What this rules out: a CDN library, Google Fonts, an analytics script, an error reporter, a call to your own
server. Put fonts, audio and data in the bundle. Report through `sdk.track()`. The portal scripts of
CrazyGames, Poki and Playgama never run on filudi.com; the SDK loads them on their own portals.

## What a game cannot do

- Read the player's own token, the page around it, or another game's storage.
- Navigate the page, open a popup, submit a form.
- Load code or assets from another origin, or call one.
- Submit a score outside a play session, or replay one: scores are signed with a key the session gives.
- Send an event named `frame_loaded`: the hub sends that one.
- Go live by itself: staff activates every version.

## Frame size and orientation

The frame takes the size the page gives it. Read `innerWidth` and `innerHeight` or a `ResizeObserver`, never
`screen.width`, and redraw on `resize`. The orientation you declare on the game (`portrait`, `landscape`,
`any`) tells the hub what to do on a phone held the other way: it shows a hint, your layout does not have to
cope. `mobile` says whether the game is listed on phones at all; `minutes` is the length of a typical
session, shown on the game's page.

Audio starts after a gesture: the frame allows `autoplay`, browsers still block sound before a tap. A
`pointerdown` handler that calls `preventDefault()` keeps the frame from taking keyboard focus; call
`canvas.focus()` in it, with `tabindex="0"` on the canvas, or the arrow keys scroll the hub page.

Source: https://developers.filudi.com/docs/games/lifecycle/

---

# Localization

Which locale your game gets on each host, what the hub translates for you, and what to translate in the game.

filudi.com runs in several languages; every site on the catalog has its own. The hub passes the site's
locale to your game, so a player who reads the page in French gets your game in French when you have it.
The reference is [i18n](/docs/sdk/i18n/).

## What the hub translates

The game's page: your titles, descriptions and categories, written per locale in the console's Settings
screen. Each site writes its own texts; the catalog never shares a description between sites. The hub also
formats the leaderboard, the dates and the `time` meta. None of this is in your bundle.

## What the game translates

Everything drawn inside the frame: menus, tutorial, messages, the `_summary.line` of your save. A game with
no translation runs in its own language on every locale; nothing breaks.

<CodePanel title="Strings per locale">
  <Fragment slot="javascript">
    ```js
    const strings = {
      en: { play: 'Play', best: 'Best', again: 'Tap to run again' },
      fr: { play: 'Jouer', best: 'Record', again: 'Touchez pour rejouer' },
    };
    const language = (tag) => tag.split('-')[0];
    let t = strings[language(sdk.i18n.locale())] ?? strings.en;
    sdk.i18n.on('change', (locale) => {
      t = strings[language(locale)] ?? strings.en;
      redrawMenus();
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    type Strings = { play: string; best: string; again: string };
    const strings: Record<string, Strings> = {
      en: { play: 'Play', best: 'Best', again: 'Tap to run again' },
      fr: { play: 'Jouer', best: 'Record', again: 'Touchez pour rejouer' },
    };
    const language = (tag: string): string => tag.split('-')[0] ?? 'en';
    let t: Strings = strings[language(sdk.i18n.locale())] ?? strings.en;
    sdk.i18n.on('change', (locale: string) => {
      t = strings[language(locale)] ?? strings.en;
      redrawMenus();
    });
    ```

  </Fragment>
</CodePanel>

## The locale per host

| Host       | Source                                                                       | Changes while running |
| ---------- | ---------------------------------------------------------------------------- | --------------------- |
| filudi.com | The site's locale in `filudi:init`; `filudi:locale` when the player switches | Yes                   |
| CrazyGames | `user.systemInfo.locale`                                                     | No                    |
| Playgama   | `bridge.platform.language`                                                   | No                    |
| Poki       | None: `navigator.language`                                                   | No                    |
| mock       | `mock.locale`, else `navigator.language`                                     | No                    |

`init({ locale })` overrides every source; use it for a language picker inside the game and keep the choice
in your save.

## Fonts and text

Fonts load from the bundle only. A font with the glyphs of every language you ship is one more file in the
zip; a Google Fonts link is blocked by the CSP. Text drawn on a canvas does not reflow: leave room for
French and German, which run a third longer than English.

## Events

`sdk.track()` carries the locale with every event, and the console splits statistics by locale. Keep
event names in English and `snake_case` whatever the player's language.

Source: https://developers.filudi.com/docs/games/localization/

---

# Portals

What the same bundle does on CrazyGames, Poki and Playgama, host by host, and the options each one takes.

One bundle runs on filudi.com and on the three portals. At `init()` the SDK detects the host from the
portal's global or hostname, loads the portal's own script when the page does not have it, and maps every
call. Nothing portal-specific ships in your bundle. Each portal has its own listing process, outside Filudi;
this page covers what your game does once it runs there.

## Side by side

|                    | filudi.com               | CrazyGames                             | Poki                                        | Playgama                   |
| ------------------ | ------------------------ | -------------------------------------- | ------------------------------------------- | -------------------------- |
| Detection          | The handshake in a frame | `CrazyGames.SDK` or `*.crazygames.com` | `PokiSDK` or `*.poki.com`, `*.poki-gdn.com` | `window.bridge`            |
| Ads                | None yet                 | Rewarded and midgame                   | `rewardedBreak`, `commercialBreak`          | Rewarded and interstitial  |
| Saves              | The API                  | Data module, else `localStorage`       | `localStorage`                              | `bridge.storage`           |
| Scores             | Signed, to your boards   | `user.submitScore` with your key       | None                                        | `bridge.leaderboards`      |
| `top()` and `me()` | Work                     | `unavailable`                          | `unavailable`                               | Work with `in_game` boards |
| Player             | Guest or account         | The portal's user, else a random id    | Guest                                       | The portal's player        |
| Locale             | The site's               | `user.systemInfo.locale`               | `navigator.language`                        | `bridge.platform.language` |
| Events             | The API                  | Dropped unless `events: 'always'`      | Same                                        | Same                       |
| Extras             |                          | `sdk.host.crazygames`                  | `sdk.host.poki`                             | `sdk.host.playgama`        |

## CrazyGames

The SDK loads `https://sdk.crazygames.com/crazygames-sdk-v3.js` when the page does not have it, and falls
back to the mock when the script fails, takes longer than `timeoutMs` or reports the `disabled`
environment. `ready()` is `game.loadingStop`, the gameplay brackets are `gameplayStart` and
`gameplayStop`, `happyTime()` is `happytime`. Ads go through `ad.requestAd('rewarded' | 'midgame')`;
`ad.hasAdblock` turns `available()` off. The portal paces interstitials, so the SDK adds no interval there.

Saves go to the data module under one key, `filudi:save`, holding `{ v, d }`; with the module off they stay
in `localStorage`. Scores reach the portal board only with the key from the CrazyGames developer portal,
encrypted with AES-GCM; keep it in a build variable.

<CodePanel title="CrazyGames options">
  <Fragment slot="javascript">
    ```js
    await sdk.init({
      gameId: 'gloop',
      version: '1.4.0',
      crazygames: { leaderboardKey: import.meta.env.VITE_CG_LEADERBOARD_KEY ?? '' },
    });
    sdk.host.crazygames?.onMuteChange((muted) => audio.mute(muted));
    fullscreenButton.hidden = result.host === 'crazygames';   // the portal draws its own
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    const result = await sdk.init({
      gameId: 'gloop',
      version: '1.4.0',
      crazygames: { leaderboardKey: import.meta.env.VITE_CG_LEADERBOARD_KEY ?? '' },
    });
    sdk.host.crazygames?.onMuteChange((muted: boolean) => audio.mute(muted));
    fullscreenButton.hidden = result.host === 'crazygames';   // the portal draws its own
    ```

  </Fragment>
</CodePanel>

The portal's mute setting, invite links and game context are [host extras](/docs/sdk/host/). `device()`
reads `user.systemInfo.device.type`.

## Poki

The SDK loads `https://game-cdn.poki.com/scripts/v2/poki-sdk.js` when the page has no `window.PokiSDK`,
then calls `PokiSDK.init()`. A script that fails, takes longer than `timeoutMs`, or an `init()` that rejects
(Poki does when an ad blocker is on) puts the game on the mock with ads off. `ready()` is
`gameLoadingFinished`. Interstitials are `commercialBreak`, always `completed`: Poki says nothing about a
skip. Rewarded ads are `rewardedBreak`: `completed` on `true`, `skipped` on `false`.

Poki keeps no save, leaderboard or player: saves stay in `localStorage`, boards answer `unavailable`, the
player is a guest. `shareableURL(params)` and `getURLParam(key)` are the host extras.

<CodePanel title="Poki share link">
  <Fragment slot="javascript">
    ```js
    const link = (await sdk.host.poki?.shareableURL({ seed: today })) ?? location.href;
    const seed = sdk.host.poki?.getURLParam('seed') ?? new URLSearchParams(location.search).get('seed');
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    const link: string = (await sdk.host.poki?.shareableURL({ seed: today })) ?? location.href;
    const seed: string | null = sdk.host.poki?.getURLParam('seed') ?? new URLSearchParams(location.search).get('seed');
    ```

  </Fragment>
</CodePanel>

## Playgama

The adapter runs when the page has Playgama Bridge (`window.bridge`) and calls `bridge.initialize()` if the
page has not, within `timeoutMs`. Ads are `advertisement.showRewarded()` and `showInterstitial()`, read
through the state events: `opened` fires `start`, `rewarded` then `closed` is `completed`, `closed` alone is
`skipped`, `failed` is `no-fill`.

Saves go to `bridge.storage` under `filudi:save` as `{ v, d }`. Scores go to `bridge.leaderboards.setScore`
unless the board type is `not_available`, and `top()` reads `getEntries` when the type is `in_game`.
`visibility_state_changed` fires `pause` and `resume`; the locale is `bridge.platform.language`; `device()`
reads `bridge.device.type` (a TV falls back to the SDK's own guess). The audio setting is
`sdk.host.playgama?.onAudioChange(fn)`, with `enabled` the opposite of muted.

<CodePanel title="Playgama audio">
  <Fragment slot="javascript">
    ```js
    sdk.host.playgama?.onAudioChange((enabled) => audio.mute(!enabled));
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    sdk.host.playgama?.onAudioChange((enabled: boolean) => audio.mute(!enabled));
    ```

  </Fragment>
</CodePanel>

## Testing without the portals

The [playground](/docs/games/first-bundle/) installs each portal's global in the frame before your bundle
runs, with the shapes the adapters read, and lets you set the ad outcome, the environment, the data module,
the leaderboard type, the player and the locale. What it cannot do: show a real ad, decrypt a real
CrazyGames key (it checks the encryption against the key you paste), or stand for a portal's review. Run the
game on each host there before every release, as the [release checklist](/docs/games/release-checklist/)
says.

## Distribution

A game runs on filudi.com by default. The console's distribution switch opens it to approved third-party
portals on the Filudi catalog once it has a live version; the console shows which sites list it. That is a
different thing from CrazyGames, Poki and Playgama: those portals host your bundle themselves and you submit
it to them.

Source: https://developers.filudi.com/docs/games/portals/

---

# Release checklist

The checks to run on a build folder before zipping it, each with the reason, and the commands that find the usual mistakes.

Run these on the build folder (`dist/`) before zipping it. Each item says why, so a game with an unusual
build can apply the reason. The bundle is served from `https://<slug>.<play domain>/<slug>/<version>/`
through the CDN and from the preview host under a cookie scoped to that path; both carry the CSP of the
[lifecycle page](/docs/games/lifecycle/).

## Structure

- `index.html` sits at the root of the folder. The upload refuses a zip without it at the root, and a zip
  of the folder itself puts it one level down: zip the content.
- No `..` in a path, no symbolic link, no encrypted entry, no file named `_upload.zip`. The upload refuses
  them.
- Zip at most 200 MB, at most 500 MB unpacked, at most 10,000 files, at most 64 MB per file. A few MB loads
  fast on a phone.
- No source maps unless you want them public.

<CodePanel title="Check the archive">
  <Fragment slot="javascript">
    ```bash
    cd dist && zip -r ../gloop-1.4.0.zip . -x '*.map' && cd ..
    unzip -l gloop-1.4.0.zip | head -5          # index.html first, at the root
    du -sh dist && find dist -type f | wc -l
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```bash
    cd dist && zip -r ../gloop-1.4.0.zip . -x '*.map' && cd ..
    unzip -l gloop-1.4.0.zip | head -5          # index.html first, at the root
    du -sh dist && find dist -type f | wc -l
    ```

  </Fragment>
</CodePanel>

## Paths

- Every URL in HTML, CSS and JS is relative: `assets/x.png`, `./main.js`. Vite needs `base: './'`.
- No URL starts with `/`. On the CDN it leaves `/<slug>/<version>/`; in the preview it also loses the cookie
  and answers 404.
- Code that builds URLs at run time uses `new URL('assets/x.png', document.baseURI)` or `import.meta.url`,
  never `location.origin + '/...'`.
- Workers and WASM load from relative paths too:
  `new Worker(new URL('./w.js', import.meta.url), { type: 'module' })`.

<CodePanel title="Find root-relative URLs">
  <Fragment slot="javascript">
    ```bash
    grep -rnoE '(src|href)="/[^/]' dist --include='*.html'
    grep -rnoE "url\(/[^/]" dist --include='*.css'
    grep -rnoE "[\"'\`]/(assets|src|img|audio|data)/" dist --include='*.js' | head
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```bash
    grep -rnoE '(src|href)="/[^/]' dist --include='*.html'
    grep -rnoE "url\(/[^/]" dist --include='*.css'
    grep -rnoE "[\"'\`]/(assets|src|img|audio|data)/" dist --include='*.js' | head
    ```

  </Fragment>
</CodePanel>

## Scripts and the CSP

- No `<script src="https://...">`: the CSP blocks it. The SDK loads the CrazyGames, Poki and Playgama
  scripts on their own portal; remove the tags the old build had.
- No inline `<script>` with code, no `onclick=""` attribute, no `eval`, no `new Function`, no `setTimeout`
  with a string. The policy has no `unsafe-inline` or `unsafe-eval` for scripts: they throw.
- No `fetch`, `XMLHttpRequest`, `WebSocket` or `EventSource` to a host other than the bundle's own and the
  API. Analytics and error reporting go through `sdk.track()`.
- Fonts, images, audio and data files are inside the bundle. No Google Fonts link, no CDN library.
- The SDK is either bundled (ESM) or loaded by a relative script tag, `vendor/filudi-sdk-<version>.iife.js`,
  before the game's script.
- `sdk-trace.js` and any other playground helper are gone.

<CodePanel title="Find what the CSP will block">
  <Fragment slot="javascript">
    ```bash
    grep -rnE "<script[^>]+src=.https?:" dist --include='*.html'
    grep -rnE '<script>[^<]|<script type="module">[^<]| on[a-z]+="' dist --include='*.html'
    grep -rnE '\beval\(|new Function\(' dist --include='*.js' | grep -v filudi-sdk | head
    grep -rnE 'fonts.googleapis|cdn\.|unpkg|jsdelivr|sdk-trace' dist | head
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```bash
    grep -rnE "<script[^>]+src=.https?:" dist --include='*.html'
    grep -rnE '<script>[^<]|<script type="module">[^<]| on[a-z]+="' dist --include='*.html'
    grep -rnE '\beval\(|new Function\(' dist --include='*.js' | grep -v filudi-sdk | head
    grep -rnE 'fonts.googleapis|cdn\.|unpkg|jsdelivr|sdk-trace' dist | head
    ```

  </Fragment>
</CodePanel>

## Frame and orientation

- The game fills its frame: it reads `innerWidth` and `innerHeight` or a `ResizeObserver`, not
  `screen.width`, and redraws on `resize`.
- The orientation declared on the game (`portrait`, `landscape` or `any`) matches what the layout handles.
- `mobile` and `minutes` are set on the game.
- The game does not draw its own fullscreen button on CrazyGames (`result.host === 'crazygames'`);
  elsewhere a button calls `sdk.fullscreen()`.
- Audio starts after a user gesture.
- A click in the game gives it the keyboard: a `pointerdown` handler that calls `preventDefault()` also
  calls `canvas.focus()`, with `tabindex="0"` on the canvas. Check it: click outside the game, click in the
  game, press an arrow key.

## SDK use

- `sdk.init({ gameId, version })`: `gameId` is the game's slug in the console, `version` the version you
  upload.
- `sdk.ready()` after the first frame, once.
- Gameplay brackets around real play only; mute on `ads.on('start')`; reward on `completed` only.
- Every board passed to `leaderboard.submit()` is declared in the console with its bounds.
- The CrazyGames leaderboard key comes from a build variable and is not in the repository.
- The game ran on each host of the playground with "Production CSP" on and no `CSP violation` line.

## Then

Upload the zip, preview it, request its review: [your first bundle](/docs/games/first-bundle/). Tag the
game's repository with the version you uploaded, so a rollback (activating the previous version again) has
a source to match.

Source: https://developers.filudi.com/docs/games/release-checklist/

---

# Saves

One blob per player per game, a version the game increments, how conflicts resolve, and how to keep an old save loading.

The SDK stores one save per player per game: a JSON value up to 64 kB. It writes `localStorage` first and
pushes to the host after, so a save never waits on the network. The reference is [save](/docs/sdk/save/);
this page is about how to design yours.

## One blob

Keep everything in one object: progress, settings, unlocks. Several keys were a habit of portal data
modules; the SDK has one slot and resolves conflicts on it as a whole. Put a schema field inside the blob
(`schema: 3`) and fill defaults for every field an older blob lacks when you load. That field has nothing to
do with the SDK's version.

<CodePanel title="Load with defaults">
  <Fragment slot="javascript">
    ```js
    const defaults = () => ({ schema: 3, level: 1, stars: [], sound: true });

    async function loadSave() {
      const read = await sdk.save.get();
      version = read.version;
      return { ...defaults(), ...(read.data ?? {}) };
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    interface Save { schema: 3; level: number; stars: number[]; sound: boolean }
    const defaults = (): Save => ({ schema: 3, level: 1, stars: [], sound: true });

    async function loadSave(): Promise<Save> {
      const read = await sdk.save.get<Partial<Save>>();
      version = read.version;
      return { ...defaults(), ...(read.data ?? {}) };
    }
    ```

  </Fragment>
</CodePanel>

## The version

The SDK's `version` is a counter the game increments on every write: `set(data, { version: last + 1 })`
where `last` is the version of the latest `get()` or `saved` result. Keep the writes in order: one at a
time, each with the version the previous one returned. A debounce (write at most every second) keeps the
count low and the API quiet.

## Conflicts

Two devices, one player. The device with the higher version wins. When the server is ahead, `set()` returns
`conflict` with the server copy: take it, merge it if your game can (keep the higher star count per level),
and write again with `server.version + 1`. When a newer copy arrives on its own, `replaced` fires: reload
your state from it. Equal versions with different content: the server wins, because another device has
seen it.

<CodePanel title="Merge on conflict">
  <Fragment slot="javascript">
    ```js
    function merge(mine, theirs) {
      return {
        ...theirs,
        level: Math.max(mine.level, theirs.level),
        stars: mine.stars.map((s, i) => Math.max(s, theirs.stars[i] ?? 0)),
      };
    }

    const result = await sdk.save.set(state, { version: version + 1 });
    if (result.status === 'conflict') {
      state = merge(state, result.server.data);
      version = result.server.version;
      await sdk.save.set(state, { version: version + 1 });
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    function merge(mine: Save, theirs: Save): Save {
      return {
        ...theirs,
        level: Math.max(mine.level, theirs.level),
        stars: mine.stars.map((s, i) => Math.max(s, theirs.stars[i] ?? 0)),
      };
    }

    const result = await sdk.save.set(state, { version: version + 1 });
    if (result.status === 'conflict') {
      state = merge(state, result.server.data as Save);
      version = result.server.version;
      await sdk.save.set(state, { version: version + 1 });
    }
    ```

  </Fragment>
</CodePanel>

## Migrating an old save

A game that moves to the SDK has players with a save under the old key: the portal's data module, or
`localStorage`. Read it when the SDK has nothing, write it through the SDK, and leave the old key where it
is: a rollback to the previous build must still find it.

<CodePanel title="Read the old key once">
  <Fragment slot="javascript">
    ```js
    async function loadSave() {
      const read = await sdk.save.get();
      version = read.version;
      if (read.data !== null) return { ...defaults(), ...read.data };
      const legacy = readLegacySave();          // the old key, exactly as the old code read it
      if (legacy === null) return defaults();
      await sdk.save.set(legacy, { version: version + 1 });
      version += 1;
      return { ...defaults(), ...legacy };
    }

    function readLegacySave() {
      try {
        const data = window.CrazyGames?.SDK?.data;
        const raw = data?.getItem('gloop-save') ?? localStorage.getItem('gloop-save');
        return raw ? JSON.parse(raw) : null;
      } catch {
        return null;
      }
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    async function loadSave(): Promise<Save> {
      const read = await sdk.save.get<Partial<Save>>();
      version = read.version;
      if (read.data !== null) return { ...defaults(), ...read.data };
      const legacy = readLegacySave();          // the old key, exactly as the old code read it
      if (legacy === null) return defaults();
      await sdk.save.set(legacy, { version: version + 1 });
      version += 1;
      return { ...defaults(), ...legacy };
    }

    function readLegacySave(): Partial<Save> | null {
      try {
        const data = (window as { CrazyGames?: { SDK?: { data?: { getItem(k: string): string | null } } } })
          .CrazyGames?.SDK?.data;
        const raw = data?.getItem('gloop-save') ?? localStorage.getItem('gloop-save');
        return raw ? (JSON.parse(raw) as Partial<Save>) : null;
      } catch {
        return null;
      }
    }
    ```

  </Fragment>
</CodePanel>

## What the hub shows

Add a `_summary` object at the top level of the blob and the game's page on filudi.com draws your progress
without knowing your game: `line` ("World 3 of 5", under 60 characters), `progress` (0 to 1), `streak` (days,
for a daily game, counted by you) and `share` (today's result as a text grid, under 400 characters, the one
place emoji are welcome). Update it on every write.

## Per host

| Host       | Where the push goes                                                                              | `features.saves`    |
| ---------- | ------------------------------------------------------------------------------------------------ | ------------------- |
| filudi.com | The API, `PUT /v1/sdk/saves/:gameId` with `If-Match`                                             | `remote`            |
| CrazyGames | The data module, one key `filudi:save` holding `{ v, d }`; `localStorage` when the module is off | `remote` or `local` |
| Playgama   | `bridge.storage`, same key and shape                                                             | `remote`            |
| Poki, mock | `localStorage` only                                                                              | `local`             |

Source: https://developers.filudi.com/docs/games/saves/

---

# Start here

The invitation, your account, the console at developers.filudi.com/console, and how a game goes from pending to live.

Filudi is invitation only. You ask for an invitation, staff sends one, you create your account, and from the
console you create a game, upload versions and ask for a review. Staff approves the game and activates the
version that goes live.

## The invitation

Fill the [request form](/request/): your email, what you build, a few lines about it. Nothing is sent to you
at that point; staff reads the requests and invites. The invitation is an email with a link that works for
7 days. Open it, choose a display name and a password, and your account is active. You can enable a
one-time code (TOTP) on the account page; staff accounts must.

## The console

[developers.filudi.com/console](/console/) is where you work. Sign in with your email and password. The
top bar switches between your games and your sites; an account with one game lands on it. Each game has:

| Screen       | What you do there                                                                  |
| ------------ | ---------------------------------------------------------------------------------- |
| Overview     | Pending or approved, the live version, the sites that list the game, the next step |
| Settings     | Name, descriptions, categories, tags, orientation, `mobile`, `minutes`             |
| Media        | Cover, screenshots, a short video                                                  |
| Versions     | Upload a zip, preview it, request its review                                       |
| Leaderboards | Declare the boards and read the scores                                             |
| Statistics   | Who plays, how long, where, across every site that lists the game                  |
| Members      | Invite another account to the game (owners only)                                   |
| Distribution | filudi.com only, or any approved portal                                            |

An account that owns nothing yet sees the two paths, games and portals, with a button for each.

## Pending, approved, live

A game you create is pending. While pending you can do everything above: configure it, upload drafts,
preview them. Nothing is public and no site lists it. Staff approves the game from its queue; the API
sends them an email for every new pending item, so you do not need to ask.

Each version you upload is a draft. When a draft is ready, press "Request review" on it. Staff plays the
preview and activates the version: it becomes the one filudi.com serves, and the previous live version goes
back to draft. Only staff activates. A version of a pending game cannot go live, so the first review waits
for the approval of the game.

## Members and roles

The account that creates a game is its owner. An owner invites members by email: an existing account gets
the membership, an unknown email gets an invitation that carries it. A member has every right of the owner
except inviting and removing members. Nobody but staff deletes a game.

## What you cannot do

Activate, retire or delete a version; approve your own game; list a game on a site that does not list it
yet; see anything about money. filudi.com has no ad network and pays nothing today; the console shows usage
statistics only.

## Next

[Your first bundle](/docs/games/first-bundle/) takes a game from the playground to a version under review.

Source: https://developers.filudi.com/docs/games/start-here/

---

# Portals

Three ways to run a site on the Filudi catalog, and how a site and its domains are approved.

A portal is a site of yours that lists games from the Filudi catalog and runs them in frames. Players get
saves, leaderboards and accounts from the API; you get the catalog, the frame handshake, server keys and
statistics. The guides take you from a pending site to a published catalog.

- [Start here](/docs/portals/start-here/): the account, a portal in the console, approval, domains.
- [Three ways to build a portal](/docs/portals/three-ways/): a front on hub-core, a front of your own, a backend
  with server keys, and how to pick.
- [A front on hub-core](/docs/portals/hub-core-front/): `fetchCatalog`, `GameFrame`, `PlayerClient`,
  `tokens.css`, the playground.
- [A front of your own](/docs/portals/own-front/): the public catalog, the handshake message by message, the game
  token exchange, `frame-ancestors`.
- [A backend with server keys](/docs/portals/backend-server-keys/): keys and scopes, players by your own user id,
  a token for the browser.
- [Listing games](/docs/portals/listing-games/): distribution, what you may list, why an add is refused.
- [Statistics](/docs/portals/statistics/): what the console shows for a site and what a key reads.
- [Going live](/docs/portals/going-live/): publish, the CDN, the approval queue.

filudi.com is built the first way and is the reference for what hub-core does. The API behind every way is in
the [API reference](/docs/api/).

Source: https://developers.filudi.com/docs/portals/

---

# A backend with server keys

Server keys and their scopes, players by your own user id, a token handed to the browser, leaderboards and statistics from your servers.

A server key lets your backend act for your site on `/v1/server/*`: create a Filudi player for each of your
users, give the browser a token for that player, read leaderboards with nicknames, read the site's numbers.
The key never reaches a browser and nothing else of the API takes it.

## Keys and scopes

Create a key in the console, under the site, Keys: a name and the scopes it needs. The answer shows the key
once, `fsk_<site slug>_<32 base62 characters>`; the API keeps a hash and the console shows the first 12
characters from then on. Store it in your backend's environment. Only an approved site has keys, 20 at most,
revoked ones included.

| Scope | Routes |
| --- | --- |
| `catalog` | `GET /v1/server/catalog` |
| `players` | `POST /v1/server/players`, `GET /v1/server/players/{playerId}` |
| `tokens` | `POST /v1/server/players/{playerId}/tokens`, `POST /v1/server/game-tokens` |
| `leaderboards` | `GET /v1/server/leaderboards/{gameId}/{board}` |
| `stats` | `GET /v1/server/stats/overview`, `GET /v1/server/stats/games/{gameId}` |

A key without the scope of a route answers 403, as does a revoked key or a key of a site that lost its
approval; `message` says which. 600 requests a minute per key, then 429 with `Retry-After`. No IP limit, no CORS.
Revoke a key from the console: the row stays with `revokedAt` and every call with it answers 403 from then on.

<CodePanel title="Create a key">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/keys' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{ "name": "string", "scopes": ["players", "tokens", "leaderboards"] }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // From the console, in the browser. The answer carries `key` once.
    const response = await fetch(`https://api.filudi.com/v1/admin/sites/${siteId}/keys`, {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ name: 'string', scopes: ['players', 'tokens', 'leaderboards'] }),
    });
    const { key, prefix } = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    # The console does this for you. Keep the key in your backend's environment:
    #   FILUDI_SITE_KEY=fsk_...
    import os

    site_key = os.environ['FILUDI_SITE_KEY']
    ```

  </Fragment>
</CodePanel>

## Players by your own user id

`POST /v1/server/players { externalId, nickname?, locale? }` creates a player for one of your users, or finds
the one created before: `externalId` is unique per site, so the call is safe to repeat. A new player answers
201, an existing one 200. A player created here is a guest with no token until you ask for one. `nickname` and
`locale` apply on creation only; the player changes them later with their own token on
`PATCH /v1/sdk/players/me`.

`GET /v1/server/players/{playerId}` reads the profile, the saves metadata and the best scores. A player of
another site answers 404.

<CodePanel title="Find or create a player">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/server/players' \
      -H "authorization: Bearer $FILUDI_SITE_KEY" \
      -H 'content-type: application/json' \
      -d '{ "externalId": "string", "nickname": "Pebble", "locale": "en" }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // Node, in your backend, on each sign-in of one of your users.
    async function filudiPlayer(user) {
      const response = await fetch('https://api.filudi.com/v1/server/players', {
        method: 'POST',
        headers: { authorization: `Bearer ${process.env.FILUDI_SITE_KEY}`, 'content-type': 'application/json' },
        body: JSON.stringify({ externalId: user.id, nickname: user.displayName, locale: user.locale }),
      });
      if (!response.ok) throw new Error(`filudi: ${response.status}`);
      return response.json(); // { id, externalId, nickname, locale, hasAccount, createdAt, lastSeenAt }
    }
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import os
    import requests

    def filudi_player(user):
        response = requests.post(
            'https://api.filudi.com/v1/server/players',
            headers={'authorization': f"Bearer {os.environ['FILUDI_SITE_KEY']}"},
            json={'externalId': user.id, 'nickname': user.display_name, 'locale': user.locale},
        )
        response.raise_for_status()
        return response.json()
    ```

  </Fragment>
</CodePanel>

## Handing a token to the browser

The page needs a player token to run a game as filudi.com does. `POST /v1/server/players/{playerId}/tokens`
answers an `fp1` token, the same kind `POST /v1/sdk/players` answers in the browser. Give it to the page over
your own authenticated channel: the answer of your sign-in, a page you render for a signed-in user, a short
`fetch` on your origin. Never in a URL, never in a cookie readable by scripts of other origins.

In the page, the token goes where a guest token would: `localStorage` under `filudi:player:<site>`, then
`PlayerClient` or your own code uses it. The page exchanges it for a game token before each frame, as any
front does. A backend that renders the whole page can skip that step too: `POST /v1/server/game-tokens
{ playerId, game }` answers the `fg1` token for the frame, and the page posts it in `filudi:init` without
holding the player token at all.

<CodePanel title="A token for the browser">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/server/players/00000000-0000-0000-0000-000000000000/tokens' \
      -H "authorization: Bearer $FILUDI_SITE_KEY"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // Your route, called by your page after sign-in. The token goes in the response body, not in a URL.
    app.post('/api/filudi-token', requireSession, async (request, reply) => {
      const player = await filudiPlayer(request.user);
      const response = await fetch(`https://api.filudi.com/v1/server/players/${player.id}/tokens`, {
        method: 'POST',
        headers: { authorization: `Bearer ${process.env.FILUDI_SITE_KEY}` },
      });
      const { token } = await response.json();
      reply.header('cache-control', 'private, no-store').send({ token });
    });
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    @app.post('/api/filudi-token')
    def filudi_token():
        player = filudi_player(current_user())
        response = requests.post(
            f"https://api.filudi.com/v1/server/players/{player['id']}/tokens",
            headers={'authorization': f"Bearer {os.environ['FILUDI_SITE_KEY']}"},
        )
        response.raise_for_status()
        return {'token': response.json()['token']}, 200, {'cache-control': 'private, no-store'}
    ```

  </Fragment>
</CodePanel>

The whole exchange, from your user's sign-in to the game calling the API:

<figure class="not-content">
  <svg viewBox="0 0 560 420" width="100%" role="img" aria-labelledby="seq-title seq-desc" font-size="12">
    <title id="seq-title">Sequence of a backend with a server key</title>
    <desc id="seq-desc">The browser signs in to your backend. Your backend creates or finds the Filudi player by externalId, asks for a player token, and sends it to the browser. The browser exchanges it for a game token and posts filudi:init to the game frame, which then calls the Filudi API with that game token.</desc>
    <defs>
      <marker id="seq-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
        <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--text-2)" />
      </marker>
    </defs>
    <g fill="var(--surface)" stroke="var(--line)" stroke-width="1.5">
      <rect x="10" y="10" width="110" height="34" rx="10" />
      <rect x="150" y="10" width="110" height="34" rx="10" />
      <rect x="290" y="10" width="110" height="34" rx="10" />
      <rect x="430" y="10" width="110" height="34" rx="10" />
    </g>
    <g fill="var(--text)" font-weight="700" text-anchor="middle">
      <text x="65" y="32">Browser</text>
      <text x="205" y="32">Your backend</text>
      <text x="345" y="32">Filudi API</text>
      <text x="485" y="32">Game frame</text>
    </g>
    <g stroke="var(--line)" stroke-width="1.5" stroke-dasharray="4 4">
      <line x1="65" y1="44" x2="65" y2="410" />
      <line x1="205" y1="44" x2="205" y2="410" />
      <line x1="345" y1="44" x2="345" y2="410" />
      <line x1="485" y1="44" x2="485" y2="410" />
    </g>
    <g stroke="var(--text-2)" stroke-width="1.5" marker-end="url(#seq-arrow)">
      <line x1="65" y1="80" x2="203" y2="80" />
      <line x1="205" y1="125" x2="343" y2="125" />
      <line x1="345" y1="160" x2="207" y2="160" stroke-dasharray="5 3" />
      <line x1="205" y1="205" x2="343" y2="205" />
      <line x1="345" y1="240" x2="207" y2="240" stroke-dasharray="5 3" />
      <line x1="205" y1="285" x2="67" y2="285" />
      <line x1="65" y1="330" x2="343" y2="330" />
      <line x1="345" y1="352" x2="67" y2="352" stroke-dasharray="5 3" />
      <line x1="65" y1="385" x2="483" y2="385" />
      <line x1="485" y1="405" x2="347" y2="405" />
    </g>
    <g fill="var(--text)" text-anchor="middle">
      <text x="134" y="72">signs in to your site</text>
      <text x="275" y="117">POST /v1/server/players</text>
      <text x="275" y="152" fill="var(--text-2)">player id</text>
      <text x="275" y="197">POST /v1/server/players/[id]/tokens</text>
      <text x="275" y="232" fill="var(--text-2)">fp1 player token</text>
      <text x="134" y="277">token in your own response</text>
      <text x="204" y="322">POST /v1/sdk/game-tokens</text>
      <text x="204" y="344" fill="var(--text-2)">fg1 game token</text>
      <text x="275" y="377">filudi:init with the fg1 token</text>
      <text x="415" y="399" fill="var(--text-2)">saves, scores, events</text>
    </g>
  </svg>
</figure>

Dashed arrows are answers. Solid ones are calls. The server key travels only on the arrows that leave your
backend; the player token never leaves the browser; the frame sees the game token alone.

## Leaderboards with nicknames

`GET /v1/server/leaderboards/{gameId}/{board}?period=week&limit=10` answers the same shape as the browser
route, with the nickname of each player. `isMe` is always false: a server has no "me". Use it for a page
rendered on the server, a Discord bot, a weekly email. The browser route stays the one to use inside a page,
where the player's own entry matters.

<CodePanel title="Weekly top">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/server/leaderboards/gloop/height?period=week&limit=10' \
      -H "authorization: Bearer $FILUDI_SITE_KEY"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch(
      'https://api.filudi.com/v1/server/leaderboards/gloop/height?period=week&limit=10',
      { headers: { authorization: `Bearer ${process.env.FILUDI_SITE_KEY}` } },
    );
    const { entries, total } = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    response = requests.get(
        'https://api.filudi.com/v1/server/leaderboards/gloop/height',
        params={'period': 'week', 'limit': 10},
        headers={'authorization': f"Bearer {os.environ['FILUDI_SITE_KEY']}"},
    )
    entries = response.json()['entries']
    ```

  </Fragment>
</CodePanel>

## Statistics

`GET /v1/server/stats/overview?from&to` and `GET /v1/server/stats/games/{gameId}?from&to` answer what the
console shows for the site: the same shapes as the admin routes, cached 60 seconds, 400 days at most.
[Statistics](/docs/portals/statistics/) lists the fields.

## What a backend cannot do

- Store a player token. It has no expiry and opens the player's account; it belongs in the player's browser.
  Ask for a new one on each sign-in instead.
- Act on a player's saves or scores. Saves and scores are written by the game, in the browser, with a game
  token; the API signs scores per play session and a server cannot forge that signature.
- Call `/v1/admin/*`. The console API takes a session cookie, not a key. Automation of the console is not
  offered in this release.
- Reach players of another site, or of filudi.com. A player id from your site means nothing elsewhere.

Source: https://developers.filudi.com/docs/portals/backend-server-keys/

---

# Going live

Publish a catalog change, what the CDN purge does, the approval queue, and the checks before players arrive.

## Publish

A catalog change (an entry, a text, an order, a category) is saved at once and shows on your front after you
publish. "Publish" in the console calls `POST /v1/admin/sites/{siteId}/publish`: the API drops its cached
catalog of the site, then purges the site's CDN zone when the site has one. The answer says what was purged.

- With a Bunny pull zone on the site row (`cdnPullZoneId`, set by staff), the purge reaches your pages at once.
- Without one, nothing is purged and `reason` says `no_zone`: your front picks the change up on its own within
  the catalog's revalidation delay, `max-age=300, stale-while-revalidate=600`. A front behind another CDN purges
  it itself.
- A 503 means the CDN did not accept the purge. Retry in a minute.

<CodePanel title="Publish">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/publish' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch(`https://api.filudi.com/v1/admin/sites/${siteId}/publish`, {
      method: 'POST',
      credentials: 'include',
    });
    const { purged, reason, at } = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    result = session.post(f'https://api.filudi.com/v1/admin/sites/{site_id}/publish').json()
    # {'purged': False, 'reason': 'no_zone', 'at': '2026-10-30T12:00:00Z'}
    ```

  </Fragment>
</CodePanel>

Game versions need no publish on your side: a version a developer activates is live on every site that lists
the game, and the bundle's HTML is cached 5 minutes at most.

## The approval queue

Two things of yours wait for staff, in one queue, oldest first, each with an email to staff when it appears:

1. The site, after creation.
2. Each domain you propose.

Listing a game, its texts, your categories and your keys need no approval.

A refusal comes by email with a reason, and the item stays pending so you can change it and ask again. Staff
also approves games and versions, which concerns game developers; a game you list goes live on your site when
its developer's version is activated.

## Before players arrive

- Your domain is approved: `GET /v1/admin/sites/{siteId}` shows it in `domains`, no longer in
  `pendingDomains`. A page on it gets CORS headers from the API and frames a game.
- Your pages send the CSP of [CORS and origins](/docs/api/cors-and-origins/) and no bundle is served from
  your origin.
- `/account/verify` (and `/<locale>/account/verify` for each locale after the first) consume the magic link
  and send `Cache-Control: private, no-store`, when `accountsAllowed` is on.
- The page that asks for a sign-in link offers the 6-digit code field.
- Consent: pass the visitor's real consent to the frame, and gate your analytics tag the way your law requires.
  The CMP of hub-core ships with a placeholder IAB id; register your own before using it.
- A catalog with at least one visible game whose developer has a live version. Everything else shows an empty
  page.
- The privacy page says that saves, scores and the email of an account are kept by the Filudi API for your
  site, and that a player may export and delete their data from the account page (hub-core's `PlayerClient`
  has both calls).

## After launch

The console's statistics show the first sessions within a minute. The feedback form of hub-core
(`sendFeedback`) writes to your site's feedback list in the console, where you mark messages seen or done.
Comments and ratings of your players are moderated from the same console.

Source: https://developers.filudi.com/docs/portals/going-live/

---

# A front on hub-core

Install @filudi/hub-core, read the catalog with fetchCatalog, run a game with GameFrame, keep the player with PlayerClient, style with tokens.css, test in the playground.

`@filudi/hub-core` is public on npmjs.com under the MIT licence. It is the package filudi.com is built on: the
mechanics of a site front, with no appearance. You draw every screen.

## Install

<CodePanel title="Install">
  <Fragment slot="javascript">

    ```sh
    pnpm add -E @filudi/hub-core preact
    ```

  </Fragment>
  <Fragment slot="typescript">

    ```sh
    pnpm add -E @filudi/hub-core preact
    # Types ship with the package. `preact` is a peer, needed for the `/preact` hooks only.
    ```

  </Fragment>
</CodePanel>

`-E` pins the exact version. The package is ESM with four entry points: `@filudi/hub-core`,
`@filudi/hub-core/preact` (hooks for islands), `@filudi/hub-core/cmp` (a TCF 2.2 consent manager) and
`@filudi/hub-core/tokens.css`. Import `tokens.css` once in your stylesheet: it defines the colours, type scale,
spacing and radii as CSS variables, with a light theme under `[data-theme='light']`.

## Read the catalog

`fetchCatalog(apiUrl, site, { locale })` is a typed `GET /v1/catalog/{site}`. It answers the site row, its
categories and tags, and the games the site lists and shows, in site order, with texts per locale, media and
rating. The helpers read it: `textsFor(game, locale)`, `navCategories(catalog)`, `tagsOf(catalog)`,
`filterGames(...)` for category pages, `search(...)` for accent-insensitive search.

<CodePanel title="Catalog">
  <Fragment slot="javascript">

    ```js
    import { fetchCatalog, textsFor } from '@filudi/hub-core';

    const API = 'https://api.filudi.com';
    const SITE = 'string'; // your site's slug

    const catalog = await fetchCatalog(API, SITE, { locale: 'en' });
    for (const game of catalog.games) {
      const texts = textsFor(game, 'en');
      console.log(game.slug, texts.title, game.bundleUrl);
    }
    ```

  </Fragment>
  <Fragment slot="typescript">

    ```ts
    import { fetchCatalog, textsFor, type Catalog, type CatalogGame } from '@filudi/hub-core';

    const API = 'https://api.filudi.com';
    const SITE = 'string'; // your site's slug

    const catalog: Catalog = await fetchCatalog(API, SITE, { locale: 'en' });
    const playable: CatalogGame[] = catalog.games.filter((game) => game.bundleUrl !== null);
    for (const game of playable) console.log(game.slug, textsFor(game, 'en').title);
    ```

  </Fragment>
</CodePanel>

A game with `bundleUrl: null` has no live version: show it without a play button, or leave it out.

## Keep the player

`PlayerClient.for(apiUrl, site)` is one instance per page. `ensure()` creates a guest on the first visit and
keeps the token in `localStorage` under `filudi:player:<site>`. The same object signs the player in by magic
link, by the code of that email or by password, sets the nickname, lists the saves, rates, comments and sends
feedback. A 401 forgets the token and the next call creates a new guest.

<CodePanel title="Player">
  <Fragment slot="javascript">

    ```js
    import { PlayerClient } from '@filudi/hub-core';

    const player = PlayerClient.for(API, SITE);
    await player.ensure();

    await player.setNickname('Pebble');
    await player.requestMagicLink(email, '/account/');
    // On /account/verify?t=<token>:
    const { merged, redirect } = await player.consumeMagicLink(token);
    ```

  </Fragment>
  <Fragment slot="typescript">

    ```ts
    import { ApiError, PlayerClient } from '@filudi/hub-core';

    const player = PlayerClient.for(API, SITE);
    await player.ensure();

    try {
      await player.signIn(email, password);
    } catch (error) {
      if (error instanceof ApiError && error.status === 401) showWrongPassword();
      else throw error;
    }
    ```

  </Fragment>
</CodePanel>

The sign-in email links to `https://<your first domain>/account/verify?t=<token>`, and to
`/<locale>/account/verify` for a locale other than your first. You build those pages; they call
`consumeMagicLink(t)`. Serve them with `Cache-Control: private, no-store`. The email also shows a 6-digit code,
for a link that opens in another browser: offer a code field on the page that asked for the link, and call
`consumeCode(email, code)`.

## Run a game

`GameFrame` creates the sandboxed iframe and runs the parent side of the handshake: it answers `filudi:ready`
with `filudi:init`, exchanges the player token for a game token through `gameSession`, refreshes that token
every 12 hours, forwards consent and locale, and reports the frame state. It draws nothing: you draw the
loading, unavailable and offline screens from `frame.state`.

<CodePanel title="GameFrame">
  <Fragment slot="javascript">

    ```js
    import { fetchCatalog, framePolicy, GameFrame, PlayerClient, textsFor } from '@filudi/hub-core';

    const NO_CONSENT = { ads: false, analytics: false };
    const catalog = await fetchCatalog(API, SITE, { locale: 'en' });
    const game = catalog.games.find((entry) => entry.slug === 'gloop');
    const player = PlayerClient.for(API, SITE);
    await player.ensure();

    const frame = new GameFrame(document.querySelector('#game'), {
      game: game.slug,
      bundleUrl: game.bundleUrl,
      apiUrl: API,
      site: SITE,
      locale: 'en',
      policy: framePolicy(catalog.site.policy, NO_CONSENT),
      consent: NO_CONSENT,
      gameVersion: game.version ?? '',
      gameSession: (slug) => player.gameSession(slug),
      renewPlayer: async () => {
        player.signOut();
        await player.ensure();
      },
      title: textsFor(game, 'en').title,
      orientation: game.orientation,
    });
    frame.on('state', ({ state }) => {
      // loading, ready, playing, unavailable, offline
    });
    ```

  </Fragment>
  <Fragment slot="typescript">

    ```tsx
    import { useRef } from 'preact/hooks';
    import { framePolicy, PlayerClient, type CatalogGame } from '@filudi/hub-core';
    import { useGameFrame } from '@filudi/hub-core/preact';

    export function Frame({ game, policy }: { game: CatalogGame; policy: Policy }) {
      const ref = useRef<HTMLDivElement>(null);
      const player = PlayerClient.for(API, SITE);
      const consent = { ads: false, analytics: false };
      const { state, loadStartedAt, retry, fullscreen } = useGameFrame(ref, {
        game: game.slug,
        bundleUrl: game.bundleUrl,
        apiUrl: API,
        site: SITE,
        locale: 'en',
        policy: framePolicy(policy, consent),
        consent,
        gameVersion: game.version ?? '',
        gameSession: (slug) => player.gameSession(slug),
        isCurrent: (session) => player.isCurrent(session),
        renewPlayer: async () => {
          player.signOut();
          await player.ensure();
        },
        title: game.slug,
        orientation: game.orientation,
      });
      return <div ref={ref} data-state={state} />;
    }
    ```

  </Fragment>
</CodePanel>

What to know:

- Call `player.ensure()` before mounting, so the token exists when the frame asks for the game token.
- `loading` turns `unavailable` after 20 s without `filudi:ready`. Draw an indeterminate bar from
  `loadStartedAt`; progress is not visible from the parent. Call `frame.retry()` on a "Try again" button.
- `frame.fullscreen()` needs a user gesture. A game's own request is honoured only when the player just clicked
  inside it.
- `save`, `score` and `track` events are claims made by the game. Read the real values from the API with the
  player's token; never grant anything on an event.
- `ads` defaults to `NoAds`: every ad request answers `unavailable`. Implement `AdBridge` to run a network.
- Pass the visitor's real consent once your consent manager has an answer, then `frame.setConsent()` on change
  (`useGameFrame` does it). `@filudi/hub-core/cmp` is a TCF 2.2 CMP if you want one.
- `GameFrame` sends `frame_loaded` to the API when the bundle posts `filudi:loaded`, which is the first step of
  the funnel in your statistics.
- `frame.destroy()` when the page goes away.

## Your page's policy

Your pages send a CSP that lets the frame load and the page call the API, and nothing lets a bundle onto your
origin:

```
frame-src https://play.filudi.com https://*.<play domain>
connect-src 'self' https://api.filudi.com
img-src 'self' data: https://play.filudi.com
media-src https://play.filudi.com
```

`GameFrame` throws on a bundle URL from the page's own origin: with `allow-same-origin`, such a bundle could
read your `localStorage`.

## Test in the playground

The SDK playground of the monorepo (`pnpm --filter @filudi/sdk-playground dev`, `http://localhost:5173`)
plays the host around a bundle and logs every SDK call and every host message. Load Gloop! or your own bundle
on the `filudi` host and read what `filudi:init` carries and what the game posts back; that is what your front
exchanges with the frame. Its "Mock API" answers `/v1/sdk/*` in memory, so a front can be built before a key or
an approved domain exists.

## SEO and analytics

`seo` helpers give you `VideoGame`, `WebSite`, `CollectionPage` and `BreadcrumbList` JSON-LD, OpenGraph tags,
hreflang links, `sitemap.xml`, `robots.txt` and canonical URLs. `Analytics` sends page-level events (share,
search, fullscreen, feedback sent) to a CausalIT domain through your own proxy, gated by consent when you pass
it. The API counts `game_start`, `account_linked` and the other server events itself, so a front never sends
them twice.

Source: https://developers.filudi.com/docs/portals/hub-core-front/

---

# Listing games

A game's distribution, what your site may list, how to add a game to your catalog, and why an add is refused.

Your catalog is yours: which games, in which order, with which titles, descriptions, categories and tags, per
locale. Which games you may pick is decided by the game's developer and by approval.

## Distribution

Every game carries a `distribution`, set by its developer in the console:

- `first_party`, the default: the game is listed by the owner's own sites only (filudi.com and the other sites
  marked first-party by staff).
- `any_portal`: any approved site may list it.

A developer may change it at any time. A game switched back to `first_party` stays in your catalog as an entry,
and the public catalog skips it from then on: your players stop seeing it, and the console shows the entry with
the reason. Nothing else of your catalog moves.

## What you may list

An approved game, with a live version, whose distribution is `any_portal`. The console's "Add a game" list
shows exactly those; the API behind it is `GET /v1/admin/games?available=<your site id>`. A pending site of a
game developer also sees that developer's own pending games, so a game and its portal are built together before
either is approved.

<CodePanel title="Games your site may add">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/admin/games?available=00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch(`https://api.filudi.com/v1/admin/games?available=${siteId}`, {
      credentials: 'include',
    });
    const games = await response.json(); // Game[], each with slug, name, distribution, versions
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    games = session.get(
        'https://api.filudi.com/v1/admin/games',
        params={'available': site_id},
    ).json()
    ```

  </Fragment>
</CodePanel>

## Add a game

`PUT /v1/admin/sites/{siteId}/catalog/{gameId}` creates or updates the entry: `featured`, `visible`,
`categories` and `tags` (slugs of your site's own lists), and `texts` per locale (`title`, `tagline`,
`description`, `howToPlay`, `controls`, `seoTitle`, `seoDescription`). Your site's default locale needs a
title. The same route updates an entry later; `DELETE` removes it; `PUT .../catalog/order` reorders the whole
list.

<CodePanel title="Add Gloop! to your catalog">
  <Fragment slot="curl">

    ```sh
    curl -X PUT 'https://api.filudi.com/v1/admin/sites/00000000-0000-0000-0000-000000000000/catalog/00000000-0000-0000-0000-000000000000' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{
      "visible": true,
      "featured": false,
      "categories": ["puzzle"],
      "tags": [],
      "texts": { "en": { "title": "Gloop!", "tagline": "string", "description": "string" } }
    }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch(`https://api.filudi.com/v1/admin/sites/${siteId}/catalog/${gameId}`, {
      method: 'PUT',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        visible: true,
        featured: false,
        categories: ['puzzle'],
        tags: [],
        texts: { en: { title: 'Gloop!', tagline: 'string', description: 'string' } },
      }),
    });
    if (response.status === 403) {
      const { message } = await response.json(); // why the site may not list the game
    }
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    response = session.put(
        f'https://api.filudi.com/v1/admin/sites/{site_id}/catalog/{game_id}',
        json={
            'visible': True,
            'featured': False,
            'categories': ['puzzle'],
            'tags': [],
            'texts': {'en': {'title': 'Gloop!', 'tagline': 'string', 'description': 'string'}},
        },
    )
    if response.status_code == 403:
        print(response.json()['message'])
    ```

  </Fragment>
</CodePanel>

## Why an add is refused

The route answers 403 with the reason in `message`, and the console shows the same sentence:

| Reason                                                     | What to do                                                                      |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
| The game is pending approval                               | Wait for staff, or, for your own game, ask for approval from the game's scope   |
| The game has no live version                               | The developer must get a version activated: a draft is not playable on any site |
| The game is `first_party` and your site is not first-party | Ask the developer to set the distribution to any portal                         |

A 404 means the game id is unknown, or one your account may not see.

## Texts, categories and tags

Texts are per site and per locale: your title for a game can differ from the same game's title on filudi.com.
Categories and tags are your site's own lists, created under the site, with their own texts and order; a game
entry carries slugs of those lists. `navCategories` of the site picks which categories make the top menu.
Changes show on your front after you publish ([Going live](/docs/portals/going-live/)).

## The game itself

The bundle, its versions, its media, its boards and its name belong to the developer. Your catalog entry
points at the game; the live version is the same on every site that lists it. When the developer activates a
new version, your players get it at the next load, with no action on your side.

Source: https://developers.filudi.com/docs/portals/listing-games/

---

# A front of your own

The public catalog, the frame handshake message by message, the game token exchange, frame-ancestors and your domains. Any stack.

Everything hub-core does is a few HTTP calls and a few `postMessage` calls. This page lists them, in the order a
page runs them, so a front in any language embeds Gloop! with the handshake alone.

## 1. Read the catalog

`GET /v1/catalog/{site}` is public: no token, no header. `?locale=en` narrows the texts to one locale. The
answer carries `Cache-Control: public, max-age=300, stale-while-revalidate=600` and an `ETag`; a 304 has no
body.

<CodePanel title="Catalog">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/catalog/filudi?locale=en'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const catalog = await (await fetch('https://api.filudi.com/v1/catalog/filudi?locale=en')).json();
    const gloop = catalog.games.find((game) => game.slug === 'gloop');
    // gloop.bundleUrl is the iframe address; null means no live version.
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    catalog = requests.get('https://api.filudi.com/v1/catalog/filudi', params={'locale': 'en'}).json()
    gloop = next(game for game in catalog['games'] if game['slug'] == 'gloop')
    bundle_url = gloop['bundleUrl']  # None without a live version
    ```

  </Fragment>
</CodePanel>

Each game has `slug`, `order`, `featured`, `categories`, `tags`, `orientation`, `minutes`, `mobile`, `daily`,
`coverColor`, `bundleUrl`, `version`, `publishedAt`, `boards`, `texts` per locale, `media` and `rating`.
Categories and tags come with their own texts. `site.navCategories` is the top menu; `site.otherSites` the
sister sites of the footer. The [Catalog schema](/docs/api/reference/schemas/#schema-catalog) has every field.

## 2. Create the player, in the browser

A visitor is a guest from the first page. `POST /v1/sdk/players { site, locale }` answers `{ player, token }`.
Keep the token in `localStorage`, never in a cookie, a URL or a log; it has no expiry and opens the whole
account. Create it from the browser: the route allows 20 guests per hour per IP, and a server would spend that
on its own address.

<CodePanel title="Guest">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/players' \
      -H 'content-type: application/json' \
      -d '{ "site": "filudi", "locale": "en" }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const KEY = 'filudi:player:filudi';
    let token = localStorage.getItem(KEY);
    if (!token) {
      const response = await fetch('https://api.filudi.com/v1/sdk/players', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ site: 'filudi', locale: 'en' }),
      });
      token = (await response.json()).token;
      localStorage.setItem(KEY, token);
    }
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    # A server does not create guests: every visitor would share its IP.
    # A backend creates players by externalId with a server key instead:
    # see "A backend with server keys".
    ```

  </Fragment>
</CodePanel>

A 401 on any later call means the API refused the token: forget it and create a new guest. Sign-in by email
link, code or password goes through `/v1/account/*` with the same token; the guest's saves and scores merge
into the account.

## 3. Exchange it for a game token

The frame never sees the player's token. Before the game asks, exchange it:
`POST /v1/sdk/game-tokens { game: '<slug>' }` with the player token answers `{ token, expiresAt }`, an `fg1`
token valid 24 hours for that game only. The API answers 404 unless the game is on your site's catalog. Do the
exchange when you create the iframe: the game waits 1.5 s for the answer once it says `filudi:ready`.

<CodePanel title="Game token">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/game-tokens' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{ "game": "gloop" }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const exchange = fetch('https://api.filudi.com/v1/sdk/game-tokens', {
      method: 'POST',
      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
      body: JSON.stringify({ game: 'gloop' }),
    }).then((response) => response.json());
    // exchange resolves to { token: 'fg1....', expiresAt }
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    # From a backend, with a server key and one of your players:
    response = requests.post(
        'https://api.filudi.com/v1/server/game-tokens',
        headers={'authorization': f'Bearer {site_key}'},
        json={'playerId': player_id, 'game': 'gloop'},
    )
    game_token = response.json()['token']
    ```

  </Fragment>
</CodePanel>

## 4. Create the frame

Use `bundleUrl` from the catalog as it is. Do not build it from the slug and do not copy the bundle to your
origin. The iframe needs `sandbox="allow-scripts allow-same-origin allow-pointer-lock"` and
`allow="fullscreen"`.

```html
<iframe
  id="game"
  src="https://gloop.<play domain>/gloop/1.4.0/index.html"
  title="Gloop!"
  sandbox="allow-scripts allow-same-origin allow-pointer-lock"
  allow="fullscreen"
></iframe>
```

Your page's CSP must allow the frame and the API:

```
frame-src https://play.filudi.com https://*.<play domain>
connect-src 'self' https://api.filudi.com
img-src 'self' data: https://play.filudi.com
media-src https://play.filudi.com
```

## 5. The handshake, message by message

Every message is a `postMessage` with a `type` that starts with `filudi:`. Post to the bundle's exact origin,
read from `new URL(bundleUrl).origin`, never to `*`. Accept a message only when `event.source` is the frame's
`contentWindow` and `event.origin` is that origin.

From the game to your page:

| Message               | Payload                          | When                                                                                                                                                |
| --------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filudi:ready`        | `{ sdk: '1' }`                   | At `sdk.init()`. Answer with `filudi:init` within 1.5 s. The game may repeat it after a reload                                                      |
| `filudi:loaded`       | `{}`                             | The first frame is drawn. Hide your loader. Send `frame_loaded` to `POST /v1/sdk/events` with the player token if you want the funnel's first step  |
| `filudi:gameplay`     | `{ running: boolean }`           | Real play starts or stops                                                                                                                           |
| `filudi:fullscreen`   | `{ request: true }`              | The game asks for fullscreen. Call `requestFullscreen()` on the iframe if the player just clicked inside it, then answer `filudi:fullscreen { ok }` |
| `filudi:ad`           | `{ id, kind, phase: 'request' }` | An ad request. Without an ad network, answer `{ id, phase: 'result', result: { status: 'unavailable', reason: 'host' } }`                           |
| `filudi:save`         | `{ version }`                    | A save was written. A claim: read saves from the API if you show them                                                                               |
| `filudi:score`        | `{ board, score, rank }`         | A score was sent. A claim: the rank that counts is in the API                                                                                       |
| `filudi:track`        | `{ event }`                      | A custom event. A claim; no listener needed                                                                                                         |
| `filudi:unauthorized` | `{}`                             | The API refused the game token. Exchange a new one and reload the frame, once per load                                                              |

From your page to the game:

| Message                         | Payload                                                            | When                                                     |
| ------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------- |
| `filudi:init`                   | see below                                                          | In answer to `filudi:ready`                              |
| `filudi:token`                  | `{ token }`                                                        | A fresh game token, every 12 hours while the frame lives |
| `filudi:consent`                | `{ consent: { ads, analytics } }`                                  | The visitor's consent changed                            |
| `filudi:locale`                 | `{ locale }`                                                       | The page locale changed                                  |
| `filudi:pause`, `filudi:resume` | `{}`                                                               | You cover or uncover the game                            |
| `filudi:fullscreen`             | `{ ok: boolean }`                                                  | In answer to the game's request                          |
| `filudi:ad`                     | `{ id, phase: 'started' }`, then `{ id, phase: 'result', result }` | Around an ad you show                                    |

`filudi:init` carries everything the game needs:

```ts
interface FiludiInit {
  type: 'filudi:init';
  apiUrl: string; // https://api.filudi.com
  token: string; // the fg1 game token, never the player's fp1
  gameId: string; // the slug this frame was opened for
  player: { id: string; nickname: string; guest: boolean };
  locale: string;
  site: string; // your site's slug
  policy: { personalizedAds: boolean; ageBand: 'all' | 'kids' | 'teen' | 'adult'; accounts: boolean };
  consent: { ads: boolean; analytics: boolean };
  gameVersion: string; // the catalog's version
}
```

`player` comes from `GET /v1/sdk/players/me` with the player token. `policy.personalizedAds` is true only when
the site allows it, the visitor consented and the age band is `adult`.

<CodePanel title="Parent side of the handshake">
  <Fragment slot="javascript">

    ```js
    const frame = document.querySelector('#game');
    const origin = new URL(gloop.bundleUrl).origin;
    const me = await (await fetch('https://api.filudi.com/v1/sdk/players/me', {
      headers: { authorization: `Bearer ${token}` },
    })).json();

    window.addEventListener('message', async (event) => {
      if (event.source !== frame.contentWindow || event.origin !== origin) return;
      const message = event.data;
      if (message?.type === 'filudi:ready') {
        const game = await exchange; // { token, expiresAt } from step 3
        frame.contentWindow.postMessage(
          {
            type: 'filudi:init',
            apiUrl: 'https://api.filudi.com',
            token: game.token,
            gameId: 'gloop',
            player: { id: me.id, nickname: me.nickname, guest: me.guest },
            locale: 'en',
            site: 'filudi',
            policy: { personalizedAds: false, ageBand: catalog.site.policy.ageBand, accounts: catalog.site.policy.accountsAllowed },
            consent: { ads: false, analytics: false },
            gameVersion: gloop.version,
          },
          origin,
        );
      }
      if (message?.type === 'filudi:loaded') hideLoader();
      if (message?.type === 'filudi:ad' && message.phase === 'request') {
        frame.contentWindow.postMessage(
          { type: 'filudi:ad', id: message.id, phase: 'result', result: { status: 'unavailable', reason: 'host' } },
          origin,
        );
      }
      if (message?.type === 'filudi:fullscreen' && message.request) {
        frame.contentWindow.postMessage({ type: 'filudi:fullscreen', ok: false }, origin);
      }
    });
    ```

  </Fragment>
  <Fragment slot="typescript">

    ```ts
    type FromGame =
      | { type: 'filudi:ready'; sdk: string }
      | { type: 'filudi:loaded' }
      | { type: 'filudi:gameplay'; running: boolean }
      | { type: 'filudi:fullscreen'; request: true }
      | { type: 'filudi:ad'; id: string; kind: 'rewarded' | 'interstitial'; phase: 'request' }
      | { type: 'filudi:save'; version: number }
      | { type: 'filudi:score'; board: string; score: number; rank: { day: number; week: number; all: number } | null }
      | { type: 'filudi:track'; event: string }
      | { type: 'filudi:unauthorized' };

    function isFromGame(event: MessageEvent, frame: HTMLIFrameElement, origin: string): event is MessageEvent<FromGame> {
      return event.source === frame.contentWindow && event.origin === origin && typeof event.data?.type === 'string';
    }
    ```

  </Fragment>
</CodePanel>

Without `filudi:init` within 1.5 s the SDK goes standalone: local saves, no scores, no `filudi:loaded`. A late
`filudi:init` is ignored. Posting the game token early, from memory, is what keeps the deadline.

## 6. Keep the token fresh

A game token lasts 24 hours. While the frame lives, exchange a new one every 12 hours and post
`filudi:token { token }`; the SDK uses it from its next request, without a reload. On `filudi:unauthorized`,
exchange once and reload the frame; if the exchange itself answers 401, the API refused the player's own token:
forget it, create a new guest, start again.

## 7. Your domains

The frame loads only when your page's origin is in the bundle's `frame-ancestors`, and the API answers your
page only when that origin is allowed. Both lists are the approved domains of approved sites. Until staff
approves yours, build on the development origins ([Start here](/docs/portals/start-here/)).

Source: https://developers.filudi.com/docs/portals/own-front/

---

# Start here

From an invitation to a pending portal with proposed domains, and what approval changes.

## An account

Accounts are created by invitation. Ask for one with the form at [/request/](/request/): your email, what you
build, a few lines. Staff reads the requests and sends an invitation by email; the link is valid 7 days. You set
a name and a password, and the account is active. An authenticator (TOTP) is optional for a developer and
required for staff.

One account holds any number of games and sites. The console shows one scope at a time; the switcher in the
top bar lists every game and site of the account.

## Create the portal

In the console, "New portal". A portal is a site row: a slug, a name, locales, a policy.

- The slug is yours for good and appears in the API paths (`/v1/catalog/<slug>`). Reserved words are refused:
  `admin`, `api`, `play`, `developers`, `filudi`, `www`, `static`.
- The first locale is the default. Texts of your catalog are written per locale.
- The policy says whether players may create accounts (`accountsAllowed`), whether personalised ads are
  allowed, and the age band (`all`, `kids`, `teen`, `adult`). A `kids` site never gets personalised ads.

The site is created pending. Your account is its owner. You hold at most 3 pending sites at a time.

<CodePanel title="The same, with the API">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/admin/sites' \
      -b "filudi_console=$FILUDI_SESSION" \
      -H 'origin: https://developers.filudi.com' \
      -H 'content-type: application/json' \
      -d '{ "slug": "string", "name": "string", "locales": ["en"], "accountsAllowed": true, "ageBand": "all" }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch('https://api.filudi.com/v1/admin/sites', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ slug, name, locales: ['en'], accountsAllowed: true, ageBand: 'all' }),
    });
    const site = await response.json(); // site.approvedAt is null until staff approves it
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    import requests

    session = requests.Session()
    session.headers['origin'] = 'https://developers.filudi.com'
    session.cookies.set('filudi_console', console_session)
    site = session.post(
        'https://api.filudi.com/v1/admin/sites',
        json={'slug': slug, 'name': name, 'locales': ['en'], 'accountsAllowed': True, 'ageBand': 'all'},
    ).json()
    ```

  </Fragment>
</CodePanel>

## What pending means

A pending site works from the console and on the development origins (`http://localhost:4321`,
`http://localhost:5173` on a local API; the playground). You can build the whole front before anyone sees it:

- its catalog, categories, tags, top menu and texts;
- its players, from the development origins;
- its own pending games, if you write games too: a pending site may list the pending games of its own
  developer, so a game and its portal are built together.

A pending site has no allowed origin of its own: its domains do not call the API and do not frame a game. It
has no server keys. It is not in `otherSites` of any site.

## Propose domains

In the site's settings, add the hostnames your front will run on: lowercase, without scheme or port
(`games.example.com`). They go into `pendingDomains`. Staff approves each one; an approved domain moves into
`domains` and becomes an allowed origin within a minute on every API pod.

The first domain of `domains` is canonical: the sign-in emails of your players link to it. A domain on or under
the play domain is refused with the issue code `game_host`.

`localhost` is never a domain. Local work goes through the development origins above.

## Approval

Staff sees pending sites, domains, games and versions in one queue, oldest first, and gets an email for each
new item. A refusal comes with a reason, by email, and the site stays pending so you can change it and ask
again. Approval sets `approvedAt`; from then on:

- the approved domains are allowed origins and `frame-ancestors`;
- the site can create server keys;
- the site can list approved games whose distribution allows it ([Listing games](/docs/portals/listing-games/)).

## Members

An owner invites members from the site's Members screen, by email. An existing account gets the membership at
once; an unknown email gets an invitation that carries it. A member has every right of the owner except
membership changes and deletion. A site keeps at least one owner.

Source: https://developers.filudi.com/docs/portals/start-here/

---

# Statistics

What the console shows for a site, the fields behind each chart, the filters, the CSV export, and the same numbers from a server key.

The console shows your site's usage: players, sessions, retention, the funnel, where and on what players play.
Nothing about ads or money; the platform offers none to portals in this release. Every number comes from the
play sessions, players, saves, scores and events of your site. filudi.com's players are not in it.

## What the console shows

For a range of UTC days (400 at most), with the previous range of the same length for comparison:

| Block   | Fields                                                                                                                                                                                                                          |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Per day | players created, accounts linked, active players, `wau` and `mau` (distinct players over the 7 and 30 days ending that day), returning players, sessions, scores, saves, links sent and consumed, events, median session length |
| Totals  | the same over the range, plus mean and median session length, returning players (a session on two distinct days), D1, D7 and D30 retention                                                                                      |
| Cohorts | players by the ISO week of their first play, with the share that played again on day 1, days 2 to 7, days 8 to 30                                                                                                               |
| Funnel  | distinct players who loaded a frame, started a session, wrote a save, sent a score, linked an email                                                                                                                             |
| Games   | every game of the catalog with sessions, players, scores and mean session length, most sessions first                                                                                                                           |
| Splits  | sessions per host, per device (`phone`, `tablet`, `desktop`, `unknown`), players per locale, events by name                                                                                                                     |
| Catalog | games, visible, live, categories, tags                                                                                                                                                                                          |

A retention share is null below 10 players old enough to be counted, so a small cohort shows no percentage
rather than a misleading one. The device comes from the user agent at the start of a session; nothing else of
the user agent is kept.

The game screen of a site shows the same set for one game on your site, with its boards (scores, players, best,
median) and sessions per bundle version. A game's developer sees their game across every site that lists it,
with a row per site; they see your site's name and its sessions, nothing about your players.

## The funnel's first step

"Loaded" counts players whose frame posted `filudi:loaded`. `GameFrame` of hub-core reports it by sending the
reserved event `frame_loaded` to `POST /v1/sdk/events` with the player's token. A front of your own sends it
the same way; a game cannot, since the API refuses that name with a game token.

<CodePanel title="Report a loaded frame">
  <Fragment slot="curl">

    ```sh
    curl -X POST 'https://api.filudi.com/v1/sdk/events' \
      -H "authorization: Bearer $FILUDI_PLAYER_TOKEN" \
      -H 'content-type: application/json' \
      -d '{ "events": [{ "name": "frame_loaded", "ts": 1761825600000, "gameId": "gloop", "host": "filudi" }] }'
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    // In the page, when the frame posts filudi:loaded. hub-core's GameFrame does this itself.
    await fetch('https://api.filudi.com/v1/sdk/events', {
      method: 'POST',
      headers: { authorization: `Bearer ${playerToken}`, 'content-type': 'application/json' },
      body: JSON.stringify({ events: [{ name: 'frame_loaded', ts: Date.now(), gameId: 'gloop', host: 'filudi' }] }),
    });
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    # A server does not send player events: the player token stays in the browser.
    # Read the numbers instead, with a server key: GET /v1/server/stats/overview.
    ```

  </Fragment>
</CodePanel>

## Filters and export

The site overview takes `from` and `to`. The game screen of a developer also filters by site, host, bundle
version and locale. Every table of the console has a CSV export, written in the browser with the table's
column labels; nothing is sent anywhere.

## From a server key

`GET /v1/server/stats/overview?from=2026-10-01&to=2026-10-30` and
`GET /v1/server/stats/games/{gameId}?from&to` answer the same shapes as the console
([StatsOverview](/docs/api/reference/schemas/#schema-statsoverview),
[GameStats](/docs/api/reference/schemas/#schema-gamestats)), with the `stats` scope. The answer is cached 60
seconds per range in Redis; a 400 says the range is over 400 days or `to` is before `from`.

<CodePanel title="Last 30 days">
  <Fragment slot="curl">

    ```sh
    curl 'https://api.filudi.com/v1/server/stats/overview?from=2026-10-01&to=2026-10-30' \
      -H "authorization: Bearer $FILUDI_SITE_KEY"
    ```

  </Fragment>
  <Fragment slot="javascript">

    ```js
    const response = await fetch(
      'https://api.filudi.com/v1/server/stats/overview?from=2026-10-01&to=2026-10-30',
      { headers: { authorization: `Bearer ${process.env.FILUDI_SITE_KEY}` } },
    );
    const { totals, days, funnel, cohorts } = await response.json();
    ```

  </Fragment>
  <Fragment slot="python">

    ```py
    response = requests.get(
        'https://api.filudi.com/v1/server/stats/overview',
        params={'from': '2026-10-01', 'to': '2026-10-30'},
        headers={'authorization': f"Bearer {os.environ['FILUDI_SITE_KEY']}"},
    )
    totals = response.json()['totals']
    ```

  </Fragment>
</CodePanel>

## Web audience

The console's web audience block (visitors, page views, sources, countries) comes from CausalIT, read with the
site's read key when you set one in the site's settings. Without a key the block says it is not configured and
nothing else changes. The API never sends your front's analytics anywhere.

Source: https://developers.filudi.com/docs/portals/statistics/

---

# Three ways to build a portal

A front on hub-core, a front of your own on the public catalog and the handshake, or a backend with server keys. What each needs and how to pick.

The API does not care how your pages are made. Three shapes cover what portals do; mix them as you need.

|                   | A front on hub-core                                  | A front of your own                             | A backend with server keys                                       |
| ----------------- | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------- |
| Reads the catalog | `fetchCatalog()`                                     | `GET /v1/catalog/{site}`                        | `GET /v1/server/catalog`                                         |
| Runs a game       | `GameFrame`                                          | an `iframe` and the handshake                   | the same, in the page                                            |
| Players           | `PlayerClient`, guests in `localStorage`             | `POST /v1/sdk/players` in the browser           | `POST /v1/server/players` by your own user id                    |
| Accounts          | magic link, code, password, built in                 | the same routes, your pages                     | your own accounts; a token per visit                             |
| Where it runs     | any JavaScript page                                  | any stack                                       | your servers plus a page                                         |
| Credential        | player token in the browser                          | player token in the browser                     | server key on the server, a token handed to the browser          |
| Guide             | [A front on hub-core](/docs/portals/hub-core-front/) | [A front of your own](/docs/portals/own-front/) | [A backend with server keys](/docs/portals/backend-server-keys/) |

## A front on hub-core

`@filudi/hub-core` is the package filudi.com runs on: the catalog client, the frame with the parent side of the
handshake, the player with its sign-in flows, the SEO helpers, an analytics client, a consent manager. It draws
nothing; you write the pages. Pick it when your front is JavaScript and you want the handshake, the token rules
and the retries done for you.

## A front of your own

The catalog is a public JSON document and the handshake is a few `postMessage` calls. Any stack can read the
catalog, create a guest in the browser, exchange its token for a game token and post `filudi:init` to the
frame. Pick it when your pages are not JavaScript, or when you want nothing from npm.

## A backend with server keys

Your service already knows its users. A server key lets it create a Filudi player per user, with your own user
id as `externalId`, and hand the browser a token for that player. The page then runs `GameFrame` or the plain
handshake as a front does. The key also reads leaderboards with nicknames and the site's statistics. Pick it
when players must be your users, or when a server needs the numbers.

## Mixing

A hub-core front with a backend is the common mix: the backend creates the player and the token; the page gives
the token to `PlayerClient` and lets hub-core do the rest. Nothing in the API ties a site to one shape.

## What every way shares

- The site must be approved and your domain approved before a page on it calls the API or frames a game
  ([Start here](/docs/portals/start-here/)).
- A game is untrusted. The player's own token never enters a frame; the frame gets a game token for one game and
  24 hours. Messages from a frame are claims, never facts.
- Bundles live on the play domain. Never copy one to your origin.
- A player belongs to one site. Players of filudi.com are other players.

Source: https://developers.filudi.com/docs/portals/three-ways/

---

# SDK

The reference of @filudi/game-sdk, one page per module, with the rules each host applies.

`@filudi/game-sdk` is the one API a game calls for saves, leaderboards, player, events, locale and ads. It
picks the host at `init()`: filudi.com, CrazyGames, Poki, Playgama or a local mock. Every method is safe to
call on every host. A feature the host does not have returns a typed result with `status: 'unavailable'`;
nothing throws except a programming error (calling a method before `init()`). No runtime dependency, under
12 kB gzipped on every host.

## Install

The package is public on npmjs.com. Pin the exact version.

<CodePanel title="Install">
  <Fragment slot="javascript">
    ```bash
    pnpm add -E @filudi/game-sdk
    # or
    npm install --save-exact @filudi/game-sdk
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```bash
    pnpm add -E @filudi/game-sdk
    # Types ship in the package: nothing else to install.
    ```

  </Fragment>
</CodePanel>

Two builds. ESM, `import { sdk } from '@filudi/game-sdk'`, for games with a bundler: the portal adapters
and the configurable mock are chunks loaded on demand. IIFE, `dist/filudi-sdk.iife.js` in the package, for
games without a build step: copy it into the game as `vendor/filudi-sdk-<version>.iife.js`, load it with a
relative `<script src>` before the game's script, and use `window.FiludiSDK`, which has the same shape as
`sdk` plus `FiludiSDK.version`. The IIFE has no rich mock: on `localhost` it runs the standalone behaviour
(no ads, saves in `localStorage`, no leaderboard).

## Lifecycle

<CodePanel title="The calls every game makes">
  <Fragment slot="javascript">
    ```js
    import { sdk } from '@filudi/game-sdk';

    await sdk.init({ gameId: 'gloop', version: '1.4.0' });
    sdk.ready();             // the first frame is drawn: the hub hides its loader
    sdk.gameplay.start();    // real play begins (not a menu)
    sdk.gameplay.stop();     // pause, menu, game over
    sdk.happyTime();         // a win, a level clear: the host may celebrate
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import { sdk, type InitResult } from '@filudi/game-sdk';

    const result: InitResult = await sdk.init({ gameId: 'gloop', version: '1.4.0' });
    sdk.ready();             // the first frame is drawn: the hub hides its loader
    sdk.gameplay.start();    // real play begins (not a menu)
    sdk.gameplay.stop();     // pause, menu, game over
    sdk.happyTime();         // a win, a level clear: the host may celebrate
    ```

  </Fragment>
</CodePanel>

## Modules

| Page                                                    | What it covers                                                                             |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [init](/docs/sdk/init/)                                 | `sdk.init()`, the options, the result, host detection, what works before it resolves       |
| [ready and gameplay](/docs/sdk/ready-and-gameplay/)     | `sdk.ready()`, `sdk.gameplay.start()`, `sdk.gameplay.stop()`, `sdk.happyTime()`            |
| [ads](/docs/sdk/ads/)                                   | `sdk.ads.rewarded()`, `sdk.ads.interstitial()`, `sdk.ads.available()`, `sdk.ads.on()`      |
| [save](/docs/sdk/save/)                                 | `sdk.save.get()`, `sdk.save.set()`, `sdk.save.sync()`, `sdk.save.clear()`, `sdk.save.on()` |
| [leaderboard](/docs/sdk/leaderboard/)                   | `sdk.leaderboard.submit()`, `sdk.leaderboard.top()`, `sdk.leaderboard.me()`                |
| [player](/docs/sdk/player/)                             | `sdk.player.get()`, `sdk.player.on()`                                                      |
| [track](/docs/sdk/track/)                               | `sdk.track()` and where events go                                                          |
| [i18n](/docs/sdk/i18n/)                                 | `sdk.i18n.locale()`, `sdk.i18n.on()`                                                       |
| [host events, fullscreen and device](/docs/sdk/events/) | `sdk.on()`, `sdk.fullscreen()`, `sdk.device()`                                             |
| [host extras](/docs/sdk/host/)                          | `sdk.host.crazygames`, `sdk.host.poki`, `sdk.host.playgama`                                |
| [types, errors and size](/docs/sdk/types/)              | Every exported type, logging, browsers, the size budget                                    |

## Local work

On `localhost` the SDK runs on the standalone mock: no ads, saves in `localStorage`, no leaderboard. With
`init({ mock: { ... } })` or `?filudi_host=mock` on the page URL, the ESM build loads the rich mock as a
separate chunk and `init({ mock: { ads: 'no-fill', latencyMs: 300 } })` changes what it answers.
`?filudi_debug=1` logs every call. The [playground](/docs/games/first-bundle/) plays each host around your
bundle and logs every call and message.

Source: https://developers.filudi.com/docs/sdk/

---

# ads

sdk.ads.rewarded() and interstitial() show an ad where the host has one; available() says whether to draw the button; on() tells you when to mute.

filudi.com has no ad network today: both ad kinds answer `unavailable` with reason `host` there. On
CrazyGames, Poki and Playgama the SDK maps them to the portal's own ads. Write the game so that every
result is handled, and nothing depends on an ad showing.

## `ads.rewarded(): Promise<AdResult>`

Grant the reward on `status === 'completed'` and on nothing else. `skipped`, `unavailable` and `error`
give nothing: a game that rewards an unavailable ad gives free rewards on every host that has none.

<CodePanel title="A rewarded ad">
  <Fragment slot="javascript">
    ```js
    lifeButton.addEventListener('click', async () => {
      lifeButton.hidden = true;
      const result = await sdk.ads.rewarded();
      if (result.status === 'completed') grantSecondLife();
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { AdResult } from '@filudi/game-sdk';

    lifeButton.addEventListener('click', async () => {
      lifeButton.hidden = true;
      const result: AdResult = await sdk.ads.rewarded();
      if (result.status === 'completed') grantSecondLife();
    });
    ```

  </Fragment>
</CodePanel>

## `ads.interstitial(): Promise<AdResult>`

At a natural break, after `gameplay.stop()`: a game over, a level end. The SDK refuses it with `too-soon`
inside the host's minimum interval, 120 s on filudi.com and on the mock, counted from the end of the last
ad shown of either kind. Portals pace their own interstitials. The result is informative; most games
ignore it.

<CodePanel title="An interstitial at game over">
  <Fragment slot="javascript">
    ```js
    async function gameOver() {
      sdk.gameplay.stop();
      overs += 1;
      if (overs % 3 === 0) await sdk.ads.interstitial();
      showGameOver();
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    async function gameOver(): Promise<void> {
      sdk.gameplay.stop();
      overs += 1;
      if (overs % 3 === 0) await sdk.ads.interstitial();
      showGameOver();
    }
    ```

  </Fragment>
</CodePanel>

## `AdResult`

<CodePanel title="AdResult">
  <Fragment slot="javascript">
    ```js
    const result = await sdk.ads.rewarded();
    switch (result.status) {
      case 'completed':   // rewarded: grant the reward
      case 'skipped':     // the player closed it early
      case 'unavailable': // result.reason: 'no-fill' | 'adblock' | 'host' | 'policy' | 'busy' | 'too-soon'
      case 'error':       // result.message
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    type AdResult =
      | { status: 'completed' }            // rewarded: grant the reward
      | { status: 'skipped' }              // the player closed it early
      | { status: 'unavailable'; reason: 'no-fill' | 'adblock' | 'host' | 'policy' | 'busy' | 'too-soon' }
      | { status: 'error'; message: string };
    ```

  </Fragment>
</CodePanel>

## Rules the SDK applies

- One ad at a time. A second call while one runs returns `unavailable` with reason `busy`.
- Before an ad the SDK calls `gameplay.stop()` and fires the `start` event; after it, the `end` event, then
  `gameplay.start()` if play was running. The game does not bracket ads itself.
- Without ad consent the filudi host answers `unavailable` with reason `policy`.
- No answer from the host within 90 s is `{ status: 'error', message: 'host timeout' }`.

## `ads.on(type, listener): Off`

`type` is `'start'` or `'end'`. Mute audio on `start`, not when you request the ad: a refused ad never
starts, and the game would stay silent. The listener takes no argument. The call returns a function that
removes the listener.

<CodePanel title="Mute during an ad">
  <Fragment slot="javascript">
    ```js
    sdk.ads.on('start', () => audio.mute());
    sdk.ads.on('end', () => audio.unmute());
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { Off } from '@filudi/game-sdk';

    const offStart: Off = sdk.ads.on('start', () => audio.mute());
    const offEnd: Off = sdk.ads.on('end', () => audio.unmute());
    // offStart(); offEnd();   when the scene that owns the audio goes away
    ```

  </Fragment>
</CodePanel>

## `ads.available(): { rewarded: boolean; interstitial: boolean }`

Whether a "watch an ad" button is worth drawing. It can change after `init()` (adblock detection): read it
each time you draw the button, not once. Throws before `init()` resolves.

<CodePanel title="Draw the button only when an ad can show">
  <Fragment slot="javascript">
    ```js
    function showGameOver() {
      lifeButton.hidden = usedLife || !sdk.ads.available().rewarded;
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { AdsAvailability } from '@filudi/game-sdk';

    function showGameOver(): void {
      const ads: AdsAvailability = sdk.ads.available();
      lifeButton.hidden = usedLife || !ads.rewarded;
    }
    ```

  </Fragment>
</CodePanel>

## Unavailable cases

| Reason     | When                                                                                           |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `host`     | The host has no ads: filudi.com today, the standalone mock, a portal in a disabled environment |
| `no-fill`  | The portal had no ad to show                                                                   |
| `adblock`  | The portal detected an ad blocker; `available()` turns both kinds off                          |
| `policy`   | No ad consent, or the site's age policy forbids ads                                            |
| `busy`     | Another ad is running                                                                          |
| `too-soon` | An interstitial inside the host's minimum interval                                             |

Where to put ads in a game, and what filudi.com offers, is in [ads on portals](/docs/games/ads/).

Source: https://developers.filudi.com/docs/sdk/ads/

---

# host events, fullscreen and device

sdk.on() delivers pause, resume, consent and locale from the host; sdk.fullscreen() asks for fullscreen; sdk.device() says phone, tablet or desktop.

## `on(type, listener): Off`

Four host events. `on()` works at any time, before `init()` included, and returns a function that removes
the listener.

| Event     | Value                                  | When                                                                                                                          |
| --------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `pause`   | none                                   | The host hid or covered the game: the hub's `filudi:pause`, a Playgama visibility change, the page going hidden on every host |
| `resume`  | none                                   | The game is visible again. `pause` fires once when the first source pauses, `resume` once when the last one resumes           |
| `consent` | `{ ads: boolean, analytics: boolean }` | The player changed consent on filudi.com                                                                                      |
| `locale`  | the new tag                            | Same as `sdk.i18n.on('change')`                                                                                               |

<CodePanel title="Pause and resume">
  <Fragment slot="javascript">
    ```js
    sdk.on('pause', () => game.pause());
    sdk.on('resume', () => game.resume());
    sdk.on('consent', (consent) => analyticsAllowed = consent.analytics);
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { Consent } from '@filudi/game-sdk';

    sdk.on('pause', () => game.pause());
    sdk.on('resume', () => game.resume());
    sdk.on('consent', (consent: Consent) => { analyticsAllowed = consent.analytics; });
    ```

  </Fragment>
</CodePanel>

A paused game stops its clock and its audio. It does not call `gameplay.stop()` for the pause the host
caused: the SDK does not either, and a session that spans a hidden tab is still one session.

## `fullscreen(): Promise<boolean>`

Resolves `true` when the frame is now fullscreen. On filudi.com the SDK asks the hub, which applies the
Fullscreen API to the frame and answers; the SDK resolves with that answer, or `false` after 2 s. Elsewhere
the SDK calls `document.documentElement.requestFullscreen()` itself. Call it from a click: browsers refuse
fullscreen without a gesture, and the hub answers `false` unless the player just clicked inside the game.

<CodePanel title="A fullscreen button">
  <Fragment slot="javascript">
    ```js
    fullscreenButton.hidden = result.host === 'crazygames';   // the portal draws its own
    fullscreenButton.addEventListener('click', async () => {
      const ok = await sdk.fullscreen();
      if (!ok) fullscreenButton.hidden = true;
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    fullscreenButton.hidden = result.host === 'crazygames';   // the portal draws its own
    fullscreenButton.addEventListener('click', async () => {
      const ok: boolean = await sdk.fullscreen();
      if (!ok) fullscreenButton.hidden = true;
    });
    ```

  </Fragment>
</CodePanel>

## `device(): Device`

`'desktop' | 'tablet' | 'mobile'`. From the host when it knows (CrazyGames `systemInfo.device.type`,
Playgama `bridge.device.type`), else from `navigator.userAgentData` or a pointer and width heuristic. Read
it after `init()`; it throws before. Use it for a default layout, not for input: a desktop can have a touch
screen.

<CodePanel title="Default layout">
  <Fragment slot="javascript">
    ```js
    const touchFirst = sdk.device() !== 'desktop';
    showOnScreenButtons(touchFirst);
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { Device } from '@filudi/game-sdk';

    const device: Device = sdk.device();
    showOnScreenButtons(device !== 'desktop');
    ```

  </Fragment>
</CodePanel>

## Unavailable cases

`fullscreen()` resolves `false` when the host or the browser refuses. The events fire on every host or not
at all: a host without consent or locale changes never emits them.

Source: https://developers.filudi.com/docs/sdk/events/

---

# host extras

sdk.host.crazygames, sdk.host.poki and sdk.host.playgama expose what one portal has and the others do not; each is undefined elsewhere.

Everything a game needs on every host is in the main API. `sdk.host.<name>` is defined only while the game
runs on that host and is `undefined` everywhere else, so optional calls are safe. The object is the same
for the life of the SDK: `const { host } = sdk` stays valid.

## `host.crazygames`

| Member                             | What it does                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| `onMuteChange(fn): Off`            | The portal's mute setting changed; `fn(muted: boolean)`. Returns an unsubscribe |
| `muted(): boolean`                 | The current setting                                                             |
| `inviteLink(params): string`       | A link to the game with `params` as query, built by the portal                  |
| `inviteParam(key): string \| null` | A parameter of the link the player arrived with                                 |
| `setGameContext(data): void`       | Context for the portal's own features                                           |

<CodePanel title="CrazyGames extras">
  <Fragment slot="javascript">
    ```js
    audio.mute(sdk.host.crazygames?.muted() ?? false);
    sdk.host.crazygames?.onMuteChange((muted) => audio.mute(muted));
    const link = sdk.host.crazygames?.inviteLink({ seed: '42' });
    const seed = sdk.host.crazygames?.inviteParam('seed') ?? new URLSearchParams(location.search).get('seed');
    sdk.host.crazygames?.setGameContext({ level: 3 });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { CrazygamesExtras } from '@filudi/game-sdk';

    const cg: CrazygamesExtras | undefined = sdk.host.crazygames;
    audio.mute(cg?.muted() ?? false);
    cg?.onMuteChange((muted: boolean) => audio.mute(muted));
    const link: string | undefined = cg?.inviteLink({ seed: '42' });
    const seed = cg?.inviteParam('seed') ?? new URLSearchParams(location.search).get('seed');
    cg?.setGameContext({ level: 3 });
    ```

  </Fragment>
</CodePanel>

## `host.poki`

| Member                                  | What it does                                    |
| --------------------------------------- | ----------------------------------------------- |
| `shareableURL(params): Promise<string>` | A poki.com link to the game with `params`       |
| `getURLParam(key): string \| null`      | A parameter of the link the player arrived with |

<CodePanel title="Poki extras">
  <Fragment slot="javascript">
    ```js
    const url = await sdk.host.poki?.shareableURL({ seed: '42' });
    const seed = sdk.host.poki?.getURLParam('seed');
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    const url: string | undefined = await sdk.host.poki?.shareableURL({ seed: '42' });
    const seed: string | null | undefined = sdk.host.poki?.getURLParam('seed');
    ```

  </Fragment>
</CodePanel>

## `host.playgama`

| Member                   | What it does                                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `onAudioChange(fn): Off` | The platform's audio setting changed; `fn(enabled: boolean)`, the opposite of muted. Returns an unsubscribe |

<CodePanel title="Playgama extras">
  <Fragment slot="javascript">
    ```js
    sdk.host.playgama?.onAudioChange((enabled) => audio.mute(!enabled));
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    sdk.host.playgama?.onAudioChange((enabled: boolean) => audio.mute(!enabled));
    ```

  </Fragment>
</CodePanel>

## A share link on every host

<CodePanel title="One function for every host">
  <Fragment slot="javascript">
    ```js
    async function shareLink(params) {
      if (sdk.host.crazygames) return sdk.host.crazygames.inviteLink(params);
      if (sdk.host.poki) return sdk.host.poki.shareableURL(params);
      const url = new URL(location.href);
      url.search = new URLSearchParams(params).toString();
      return url.toString();
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    async function shareLink(params: Record<string, string>): Promise<string> {
      if (sdk.host.crazygames) return sdk.host.crazygames.inviteLink(params);
      if (sdk.host.poki) return sdk.host.poki.shareableURL(params);
      const url = new URL(location.href);
      url.search = new URLSearchParams(params).toString();
      return url.toString();
    }
    ```

  </Fragment>
</CodePanel>

## Unavailable cases

The whole object is the unavailable case: on filudi.com all three names are `undefined`. Mute on
filudi.com is the page's own control; a game that wants a mute button draws one.

Source: https://developers.filudi.com/docs/sdk/host/

---

# i18n

sdk.i18n.locale() gives the locale the host asked for, a lowercase BCP 47 tag; on('change') follows a switch while the game runs.

## `i18n.locale(): string`

A BCP 47 tag in lowercase: `en`, `fr`, `pt-br`. From the host when it has one (filudi.com passes the
site's locale; CrazyGames exposes `user.systemInfo.locale`; Playgama `bridge.platform.language`; Poki has
none), else `navigator.language`, else `en`. `init({ locale })` overrides all of it. Throws before
`init()` resolves.

<CodePanel title="Pick the strings">
  <Fragment slot="javascript">
    ```js
    const strings = { en, fr };
    let t = strings[sdk.i18n.locale().split('-')[0]] ?? en;
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    const strings: Record<string, Strings> = { en, fr };
    let t: Strings = strings[sdk.i18n.locale().split('-')[0] ?? 'en'] ?? en;
    ```

  </Fragment>
</CodePanel>

## `i18n.on('change', listener): Off`

Fires when the host switches locale while the game runs; filudi.com does when the player changes the site
language. The listener gets the new tag. `sdk.on('locale', listener)` is the same event under the host
events.

<CodePanel title="Redraw on a switch">
  <Fragment slot="javascript">
    ```js
    sdk.i18n.on('change', (locale) => {
      t = strings[locale.split('-')[0]] ?? en;
      redrawMenus();
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    sdk.i18n.on('change', (locale: string) => {
      t = strings[locale.split('-')[0] ?? 'en'] ?? en;
      redrawMenus();
    });
    ```

  </Fragment>
</CodePanel>

## Unavailable cases

None: there is always a locale. A host without one gives the browser's. Which languages filudi.com runs
in, and what to translate first, is in [localization](/docs/games/localization/).

Source: https://developers.filudi.com/docs/sdk/i18n/

---

# init

sdk.init() picks the host, opens the handshake on filudi.com and resolves with the player, the locale, the features and the policy.

`init(options): Promise<InitResult>`. Call it once, before anything else. A second call returns the same
promise. It never rejects: a portal script that fails to load falls back to `mock`, and `result.host` says
so.

<CodePanel title="Initialise">
  <Fragment slot="javascript">
    ```js
    import { sdk } from '@filudi/game-sdk';

    const result = await sdk.init({ gameId: 'gloop', version: '1.4.0' });
    console.log(result.host);              // 'filudi' | 'crazygames' | 'poki' | 'playgama' | 'mock'
    console.log(result.player.nickname);   // 'Guest-Fox'
    if (result.features.leaderboard) showBoardButton();
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import { sdk, type InitResult } from '@filudi/game-sdk';

    const result: InitResult = await sdk.init({ gameId: 'gloop', version: '1.4.0' });
    const host: InitResult['host'] = result.host;   // 'filudi' | 'crazygames' | 'poki' | 'playgama' | 'mock'
    if (result.features.leaderboard) showBoardButton();
    ```

  </Fragment>
</CodePanel>

## Options

<CodePanel title="InitOptions">
  <Fragment slot="javascript">
    ```js
    await sdk.init({
      gameId: 'gloop',            // slug, same as in the console
      version: '1.4.0',           // bundle version, sent with events
      debug: false,               // console logging, same as ?filudi_debug=1
      crazygames: { leaderboardKey: import.meta.env.VITE_CG_LEADERBOARD_KEY ?? '' },
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    interface InitOptions {
      gameId: string;                       // slug, same as in the console
      host?: HostName;                      // skip detection
      version?: string;                     // bundle version, sent with events
      locale?: string;                      // overrides the host's locale
      mock?: Partial<MockConfig>;           // only read by the mock adapter
      timeoutMs?: number;                   // portal SDK script load, default 4000
      handshakeTimeoutMs?: number;          // wait for filudi:init, default 1500
      debug?: boolean;                      // console logging, same as ?filudi_debug=1
      events?: 'default' | 'always';        // 'always' sends track() batches from portals too
      eventsUrl?: string;                   // where portal batches go (POST .../v1/sdk/events), with 'always'
      crazygames?: { leaderboardKey?: string };
      poki?: Record<string, never>;
    }
    ```

  </Fragment>
</CodePanel>

`gameId` is the slug of the game in the console. On filudi.com the frame is opened for one game; when the
handshake names another slug than the one you passed, the SDK logs an error and uses the slug of the frame,
because the API would refuse the other one. `version` is the version string you upload; events carry it, so
pass the release version from your build.

The SDK ignores options for a host the game does not run on.

## Result

<CodePanel title="InitResult">
  <Fragment slot="javascript">
    ```js
    const { host, player, locale, features, policy } = await sdk.init({ gameId: 'gloop' });
    // features.saves: 'remote' on filudi.com and portals with storage, 'local' elsewhere
    // features.leaderboard, features.rewarded, features.interstitial, features.account: booleans
    // policy.personalizedAds: false on kids sites or without consent
    // policy.ageBand: 'all' | 'kids' | 'teen' | 'adult'
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    interface InitResult {
      host: HostName;
      player: Player;                       // { id, nickname, guest, host }
      locale: string;
      features: {
        saves: 'remote' | 'local';
        leaderboard: boolean;
        rewarded: boolean;
        interstitial: boolean;
        account: boolean;
      };
      policy: {
        personalizedAds: boolean;           // false on kids sites or without consent
        ageBand: 'all' | 'kids' | 'teen' | 'adult';
      };
    }
    ```

  </Fragment>
</CodePanel>

## Host detection

In this order: `options.host`; `?filudi_host=<name>` on the page URL; a portal global or hostname
(`CrazyGames.SDK` or `*.crazygames.com`; `PokiSDK` or `*.poki.com` or `*.poki-gdn.com`; Playgama's bridge);
the filudi handshake when the SDK runs inside an iframe (skipped on portal domains and at top level);
`localhost`, `127.0.0.1` or any unknown host gives `mock`.

On `mock`, two behaviours share the name. With `options.mock` or `?filudi_host=mock`, the ESM build loads
the configurable mock. Without them, and always in the IIFE, the SDK runs standalone: ads unavailable,
saves in `localStorage`, no leaderboard.

## The mock

<CodePanel title="MockConfig">
  <Fragment slot="javascript">
    ```js
    await sdk.init({
      gameId: 'gloop',
      mock: { host: 'filudi', ads: 'no-fill', latencyMs: 300, player: { nickname: 'Guest-Fox' } },
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    interface MockConfig {
      host: HostName;                       // whose rules the mock follows (ad interval, features)
      latencyMs: number;                    // added to every async call
      ads: 'fill' | 'no-fill' | 'adblock' | 'error';
      player: Partial<Player>;
      saveConflict: SaveRead<unknown> | null; // returned as the server copy on the next write
      leaderboard: LeaderboardEntry[];      // seed entries
      locale: string;
      eventsUrl: string | null;             // where track() batches go; null drops them
    }
    ```

  </Fragment>
</CodePanel>

## Before init resolves

Async and void methods called while `init()` is pending wait for it. `sdk.player.get()`,
`sdk.ads.available()`, `sdk.i18n.locale()` and `sdk.device()` throw until it resolves. Every `on()` works at
any time and returns an unsubscribe function. Calling anything before `init()` was called at all throws.

## Unavailable cases

`init()` has none: it resolves on every host. When a portal script fails, takes longer than `timeoutMs` or
reports a disabled environment, the result says `host: 'mock'` and every other module answers as on the
mock.

Source: https://developers.filudi.com/docs/sdk/init/

---

# leaderboard

sdk.leaderboard.submit() sends a score to a board declared in the console; top() and me() read it by period.

You declare boards per game in the console: `name` (`^[a-z][a-z0-9_]{0,31}$`), `sort` (`desc` or `asc`),
`min` and `max`, `keep` (`best` or `latest`) and a rate per minute (10 by default). The API rejects a score
outside the bounds. Periods are `day`, `week` and `all`.

## `leaderboard.submit(board, score, meta?): Promise<SubmitResult>`

Once per finished run, after `gameplay.stop()`, in a run that called `gameplay.start()`. `score` is a safe
integer. `meta` is at most 512 bytes of JSON with string or number values, shown as the entry's detail
(tries, time). A board or a meta key named `time` is in seconds; the hub formats it as `m:ss`.

<CodePanel title="Submit a score">
  <Fragment slot="javascript">
    ```js
    async function endRun(metres, tries) {
      sdk.gameplay.stop();
      const result = await sdk.leaderboard.submit('height', metres, { tries });
      if (result.status === 'accepted') showRank(result.rank.week, result.best);
      else if (result.status === 'rejected') console.warn('score rejected:', result.reason);
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { SubmitResult } from '@filudi/game-sdk';

    async function endRun(metres: number, tries: number): Promise<void> {
      sdk.gameplay.stop();
      const result: SubmitResult = await sdk.leaderboard.submit('height', metres, { tries });
      if (result.status === 'accepted') showRank(result.rank.week, result.best);
      else if (result.status === 'rejected') console.warn('score rejected:', result.reason);
    }
    ```

  </Fragment>
</CodePanel>

## `leaderboard.top(board, period): Promise<TopResult>`

Up to 10 entries, ranked. The hub draws the top 5 and the player's row itself; the SDK gives the raw list.
`total` is the number of entries on the board for that period.

## `leaderboard.me(board, period): Promise<MeResult>`

The player's own entry for that period, or `null` when they have none.

<CodePanel title="Draw a board">
  <Fragment slot="javascript">
    ```js
    const top = await sdk.leaderboard.top('height', 'week');
    const me = await sdk.leaderboard.me('height', 'week');
    if (top.status === 'unavailable') return hideBoard();
    drawRows(top.entries.slice(0, 5));           // { rank, nickname, score, meta, isMe }
    if (me.status === 'ok' && me.entry) drawMyRow(me.entry);
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { LeaderboardEntry, MeResult, TopResult } from '@filudi/game-sdk';

    const top: TopResult = await sdk.leaderboard.top('height', 'week');
    const me: MeResult = await sdk.leaderboard.me('height', 'week');
    if (top.status === 'unavailable') return hideBoard();
    const rows: LeaderboardEntry[] = top.entries.slice(0, 5);
    drawRows(rows);
    if (me.status === 'ok' && me.entry) drawMyRow(me.entry);
    ```

  </Fragment>
</CodePanel>

## Types

<CodePanel title="Leaderboard types">
  <Fragment slot="javascript">
    ```js
    // Period: 'day' | 'week' | 'all'
    // LeaderboardEntry: { rank, nickname, score, meta, isMe }
    // SubmitResult: { status: 'accepted', rank: { day, week, all }, best }
    //             | { status: 'rejected', reason }     'bounds' | 'rate' | 'signature' | 'board' | 'session' | 'nonce' | 'clock' | 'meta'
    //             | { status: 'unavailable' }
    //             | { status: 'error', message }       meta not serializable, network failure
    // TopResult: { status: 'ok', entries, period, total } | { status: 'unavailable' }
    // MeResult:  { status: 'ok', entry, period } | { status: 'unavailable' }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    type Period = 'day' | 'week' | 'all';

    interface LeaderboardEntry {
      rank: number;
      nickname: string;
      score: number;
      meta: Record<string, string | number> | null;
      isMe: boolean;
    }

    type SubmitResult =
      | { status: 'accepted'; rank: { day: number; week: number; all: number }; best: boolean }
      | { status: 'rejected'; reason: 'bounds' | 'rate' | 'signature' | 'board' | 'session' | 'nonce' | 'clock' | 'meta' }
      | { status: 'unavailable' }
      | { status: 'error'; message: string };     // meta not serializable, network failure

    type TopResult =
      | { status: 'ok'; entries: LeaderboardEntry[]; period: Period; total: number }
      | { status: 'unavailable' };

    type MeResult =
      | { status: 'ok'; entry: LeaderboardEntry | null; period: Period }
      | { status: 'unavailable' };
    ```

  </Fragment>
</CodePanel>

## Signed scores on filudi.com

`gameplay.start()` opens a play session and receives a session key. The SDK signs
`pid|gameId|board|score|nonce|ts` with HMAC-SHA256 through `crypto.subtle` and sends the signature with the
score. Replaying a nonce or submitting outside a session is `rejected`. The game does nothing for this;
it only brackets play. Without `crypto.subtle` (an old browser on plain HTTP) `submit` answers `rejected`
with reason `signature` and everything else works.

## Rejected reasons

| Reason                        | What it means                                                                                                  |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `bounds`                      | The score is outside the board's `min` and `max`, or not a safe integer. Also the mapping of an unknown reason |
| `rate`                        | More scores than the board's rate per minute (a 429)                                                           |
| `session`                     | No play session: `gameplay.start()` was not called in this run                                                 |
| `signature`, `nonce`, `clock` | The signature failed, the nonce was replayed, or the clock is off by too much                                  |
| `board`                       | No board of that name on this game                                                                             |
| `meta`                        | `meta` is over 512 bytes or has a value that is not a string or a number                                       |

## Per host

| Host       | `submit`                                                                                                                           | `top` and `me`                          |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| filudi.com | Signed, to the board of the game                                                                                                   | Work, by period                         |
| CrazyGames | Encrypted for `user.submitScore` when `init({ crazygames: { leaderboardKey } })` is given, else `unavailable`; `rank` values are 0 | `unavailable`: the portal draws its own |
| Poki       | `unavailable`                                                                                                                      | `unavailable`                           |
| Playgama   | Through `bridge.leaderboards` unless its type is `not_available`; `rank` values are 0                                              | Work when the type is `in_game`         |
| mock       | Accepted against the seed entries of `mock.leaderboard`; standalone answers `unavailable`                                          | Same                                    |

`features.leaderboard` from `init()` says ahead of time whether a board is worth drawing. Which boards to
declare and how to pick their bounds is in [leaderboards](/docs/games/leaderboards/).

Source: https://developers.filudi.com/docs/sdk/leaderboard/

---

# player

sdk.player.get() gives the player's id, nickname and guest state on the current host; on('change') follows a nickname or an account link.

## `player.get(): Player`

Synchronous. Throws before `init()` resolves; after it, always answers.

<CodePanel title="Read the player">
  <Fragment slot="javascript">
    ```js
    const player = sdk.player.get();
    // { id: string, nickname: string, guest: boolean, host: HostName }
    drawName(player.guest ? 'Guest' : player.nickname);
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { Player } from '@filudi/game-sdk';

    const player: Player = sdk.player.get();
    drawName(player.guest ? 'Guest' : player.nickname);
    ```

  </Fragment>
</CodePanel>

`id` is stable per host. On filudi.com it is the player id of the API: the same for a guest and for the
account that guest later creates. On portals it is the portal's user id when the portal exposes one, else
a random id kept in `localStorage`. `nickname` is the hub's or the portal's display name; a guest on
filudi.com gets a generated one like `Guest-Fox`. Do not key saves on `id`: the SDK does that for you.

## `player.on('change', listener): Off`

Fires when the nickname changes or the player links an account while the game runs. The listener gets the
new `Player`. Returns a function that removes the listener.

<CodePanel title="Follow the player">
  <Fragment slot="javascript">
    ```js
    const off = sdk.player.on('change', (player) => drawName(player.nickname));
    // off() when the scene goes away
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { Off, Player } from '@filudi/game-sdk';

    const off: Off = sdk.player.on('change', (player: Player) => drawName(player.nickname));
    ```

  </Fragment>
</CodePanel>

## Unavailable cases

None: every host has a player. On Poki and on the standalone mock the player is always a guest. `features.account`
from `init()` says whether the host lets a guest become an account; the hub owns that flow, the game only
reads the result through `change`.

Source: https://developers.filudi.com/docs/sdk/player/

---

# ready and gameplay

sdk.ready() hides the host's loader; sdk.gameplay.start() and stop() bracket real play; sdk.happyTime() marks a win.

Four void calls. They return nothing and never throw after `init()`; called while `init()` is pending they
wait for it.

## `ready(): void`

Call it when the game can be seen and played, once the first frame is drawn. It forwards to the host's
loading-stop: filudi.com hides its loader, CrazyGames gets `loadingStop`, Poki `gameLoadingFinished`.
Idempotent: a second call does nothing.

<CodePanel title="Ready after the first frame">
  <Fragment slot="javascript">
    ```js
    let first = true;

    function frame(now) {
      draw(now);
      if (first) {
        first = false;
        sdk.ready();
      }
      requestAnimationFrame(frame);
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    let first = true;

    function frame(now: DOMHighResTimeStamp): void {
      draw(now);
      if (first) {
        first = false;
        sdk.ready();
      }
      requestAnimationFrame(frame);
    }
    ```

  </Fragment>
</CodePanel>

## `gameplay.start(): void` and `gameplay.stop(): void`

Bracket real play. Not menus, not loading, not an ad. The SDK dedupes: two `start()` in a row send one, so
drop the game's own `playing` flag. The SDK itself calls `stop()` before an ad and `start()` after it when
play was running: never call them around an ad yourself.

On filudi.com `start()` opens a play session and receives the key that signs scores. A score submitted
outside a session is rejected, see [leaderboard](/docs/sdk/leaderboard/).

<CodePanel title="Bracket play">
  <Fragment slot="javascript">
    ```js
    function startRun() {
      state.mode = 'run';
      sdk.gameplay.start();
    }

    function endRun() {
      state.mode = 'over';
      sdk.gameplay.stop();
    }

    pauseButton.addEventListener('click', () => {
      state.mode = 'paused';
      sdk.gameplay.stop();
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    type Mode = 'menu' | 'run' | 'paused' | 'over';

    function setMode(mode: Mode): void {
      state.mode = mode;
      if (mode === 'run') sdk.gameplay.start();
      else sdk.gameplay.stop();
    }
    ```

  </Fragment>
</CodePanel>

## `happyTime(): void`

A win or a level clear. Hosts that have the concept (CrazyGames `happytime`) get it; the others ignore it.

<CodePanel title="Celebrate a level clear">
  <Fragment slot="javascript">
    ```js
    function levelCleared() {
      sdk.gameplay.stop();
      sdk.happyTime();
      showSummary();
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    function levelCleared(): void {
      sdk.gameplay.stop();
      sdk.happyTime();
      showSummary();
    }
    ```

  </Fragment>
</CodePanel>

## Unavailable cases

None. On a host without the concept the call is a no-op. On filudi.com `ready()` posts `filudi:loaded` and
`gameplay` posts `filudi:gameplay { running }`; the hub counts the first as the first step of your funnel
and the second as a session, see [events and statistics](/docs/games/events-and-statistics/).

Source: https://developers.filudi.com/docs/sdk/ready-and-gameplay/

---

# save

One save per player per game, a JSON value up to 64 kB, local first and synced to the host, with a version the game increments.

One save per player per game: a JSON value of at most 64 kB once serialized. The SDK is local-first. It
writes `localStorage` at once (key `filudi:save:<gameId>`) and pushes to the host after: the API on
filudi.com, the data module on CrazyGames, the storage on Playgama. Poki and the mock keep it local.

## `save.get<T>(): Promise<SaveRead<T>>`

Waits up to 1 s for the remote copy, then returns the local one. If the remote turns out newer later, the
SDK replaces the local copy and fires `replaced`.

<CodePanel title="Read the save">
  <Fragment slot="javascript">
    ```js
    const read = await sdk.save.get();
    // read: { data: MySave | null, version: number, source: 'remote' | 'local' | 'none', updatedAt: string | null }
    let version = read.version;
    const state = read.data ?? defaults();
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { SaveRead } from '@filudi/game-sdk';

    interface MySave { level: number; stars: number[] }

    const read: SaveRead<MySave> = await sdk.save.get<MySave>();
    let version = read.version;              // 0 when there is no save yet
    const state: MySave = read.data ?? defaults();
    ```

  </Fragment>
</CodePanel>

## `save.set(data, { version }): Promise<SaveWrite>`

`version` is a positive integer the game increments: the version of the last `get()` or `saved` result
plus one. Without it the call returns `{ status: 'error' }` with a message that says so. It has nothing to
do with a schema version inside your data: keep that inside the blob.

`set()` returns `saved` at once with `synced: false`, then pushes. It returns `conflict` without writing
when the version the SDK already knows from the server is greater than or equal to the one you pass.

<CodePanel title="Write the save">
  <Fragment slot="javascript">
    ```js
    let writing = Promise.resolve();

    // One write at a time, so each one sends the version the previous one returned.
    function writeSave(state) {
      writing = writing.then(async () => {
        const result = await sdk.save.set(state, { version: version + 1 });
        if (result.status === 'saved') version = result.version;
        else if (result.status === 'conflict') {
          version = result.server.version;
          replaceState(result.server.data);
        } else if (result.status === 'too-large') {
          console.error(`save is ${result.bytes} bytes, max ${result.max}`);
        }
      });
      return writing;
    }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { SaveWrite } from '@filudi/game-sdk';

    let writing: Promise<void> = Promise.resolve();

    // One write at a time, so each one sends the version the previous one returned.
    function writeSave(state: MySave): Promise<void> {
      writing = writing.then(async () => {
        const result: SaveWrite = await sdk.save.set(state, { version: version + 1 });
        if (result.status === 'saved') version = result.version;
        else if (result.status === 'conflict') {
          version = result.server.version;
          replaceState(result.server.data as MySave);
        } else if (result.status === 'too-large') {
          console.error(`save is ${result.bytes} bytes, max ${result.max}`);
        }
      });
      return writing;
    }
    ```

  </Fragment>
</CodePanel>

## Types

<CodePanel title="SaveRead and SaveWrite">
  <Fragment slot="javascript">
    ```js
    // SaveRead:  { data, version, source: 'remote' | 'local' | 'none', updatedAt }
    // SaveWrite: { status: 'saved', version, synced }
    //          | { status: 'conflict', server }      server has a higher version
    //          | { status: 'too-large', bytes, max }  max is 65536
    //          | { status: 'error', message }
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    interface SaveRead<T> {
      data: T | null;
      version: number;                      // 0 when none
      source: 'remote' | 'local' | 'none';
      updatedAt: string | null;             // ISO
    }

    type SaveWrite =
      | { status: 'saved'; version: number; synced: boolean }
      | { status: 'conflict'; server: SaveRead<unknown> }   // server has a higher version
      | { status: 'too-large'; bytes: number; max: 65536 }
      | { status: 'error'; message: string };
    ```

  </Fragment>
</CodePanel>

## How a conflict resolves

On filudi.com the push is `PUT /v1/sdk/saves/:gameId` with `If-Match`. A 409 resolves by version: the
higher version wins. If the server is higher, the SDK replaces the local copy and fires `replaced` so the
game can reload. Equal versions with different content: the server wins, another device has seen it. On
portals with a storage module the push goes there; else the save stays local and `synced` stays false.

## `save.on('replaced', listener): Off`

Fires when a newer copy arrives from the host: after a `get()` that returned the local copy first, after a
conflict, or when another device wrote. The listener gets the `SaveRead`. Reload your state from it.

<CodePanel title="Reload on a newer copy">
  <Fragment slot="javascript">
    ```js
    sdk.save.on('replaced', (read) => {
      version = read.version;
      replaceState(read.data ?? defaults());
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    sdk.save.on('replaced', (read: SaveRead<unknown>) => {
      version = read.version;
      replaceState((read.data as MySave | null) ?? defaults());
    });
    ```

  </Fragment>
</CodePanel>

## `save.sync<T>(): Promise<SaveRead<T>>`

For a game that needs the authoritative copy before drawing: waits for the host and returns the merged
read. On a host without remote saves it returns the local copy.

## `save.clear(): Promise<void>`

Deletes the local and the remote copy. The next `get()` returns `version: 0` and `source: 'none'`.

<CodePanel title="Sync, then reset">
  <Fragment slot="javascript">
    ```js
    const authoritative = await sdk.save.sync();

    resetButton.addEventListener('click', async () => {
      await sdk.save.clear();
      version = 0;
      replaceState(defaults());
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    const authoritative: SaveRead<MySave> = await sdk.save.sync<MySave>();

    resetButton.addEventListener('click', async () => {
      await sdk.save.clear();
      version = 0;
      replaceState(defaults());
    });
    ```

  </Fragment>
</CodePanel>

## The `_summary` field

A game may put a `_summary` object at the top level of its save data so the hub can draw it without knowing
the game: `line` (a string under 60 characters, like "World 3 of 5"), `progress` (0 to 1), `streak` (days,
for daily games, counted by the game) and `share` (the text grid of today's result, under 400 characters,
emoji allowed there). The SDK does not read it.

## Unavailable cases

Saves never answer `unavailable`: a host without storage keeps the save in `localStorage` and `source` says
`local`. `features.saves` from `init()` says `remote` or `local` ahead of time. The migration of a save
written by an older build, and what to keep in the blob, is in [saves](/docs/games/saves/).

Source: https://developers.filudi.com/docs/sdk/save/

---

# track

sdk.track() records a game event with up to 20 properties; the SDK batches them and they appear in your statistics.

## `track(event, props?): void`

`event` is `snake_case`, at most 40 characters (`^[a-z][a-z0-9_]{0,39}$`). `props` holds at most 20
properties with string, number or boolean values, each at most 200 characters once written. The call
returns nothing and never throws after `init()`.

<CodePanel title="Record an event">
  <Fragment slot="javascript">
    ```js
    sdk.track('level_complete', { level: 12, moves: 48, perfect: true });
    sdk.track('shop_open');
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { TrackProps } from '@filudi/game-sdk';

    const props: TrackProps = { level: 12, moves: 48, perfect: true };
    sdk.track('level_complete', props);
    sdk.track('shop_open');
    ```

  </Fragment>
</CodePanel>

## Where events go

The SDK batches: 50 events or 5 s, whichever comes first, then `POST /v1/sdk/events` on filudi.com with
the game token. On `pagehide` and when the page becomes hidden it flushes with a `keepalive` request so the
last batch leaves with the page. Each item carries what the SDK knows: `gameId`, `gameVersion` (the
`version` you passed to `init()`), `host`, `locale`, a `sessionId` per page load and a timestamp.

On portals, events go nowhere by default. `init({ events: 'always', eventsUrl })` sends them to the URL you
give, the Filudi API's `/v1/sdk/events`; no token exists there, so the API counts them as anonymous for the
game's site.

<CodePanel title="Events from portals too">
  <Fragment slot="javascript">
    ```js
    await sdk.init({
      gameId: 'gloop',
      version: '1.4.0',
      events: 'always',
      eventsUrl: 'https://api.filudi.com/v1/sdk/events',
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    await sdk.init({
      gameId: 'gloop',
      version: '1.4.0',
      events: 'always',
      eventsUrl: 'https://api.filudi.com/v1/sdk/events',
    });
    ```

  </Fragment>
</CodePanel>

## What to track

Events are for what the console cannot see on its own. Sessions, saves and scores are already counted
from the SDK calls that make them. Track the decisions inside your game: a level cleared, a difficulty
chosen, a shop opened, a tutorial skipped. Keep the set small and stable across versions; a renamed event
starts a new line in the statistics.

`frame_loaded` is reserved: the hub sends it when your bundle calls `ready()`, and the API refuses it from
a game. Every other name is yours.

## Unavailable cases

`track()` never reports one. An event that breaks the limits is dropped with a debug log line
(`init({ debug: true })` or `?filudi_debug=1`). On the mock, events are kept in memory unless
`mock.eventsUrl` points somewhere. What the console shows for your events is in
[events and statistics](/docs/games/events-and-statistics/).

Source: https://developers.filudi.com/docs/sdk/track/

---

# types, errors and size

Every type @filudi/game-sdk exports, what the SDK logs, the browsers it runs in and the 12 kB budget.

## Exported types

Every type is exported from the package root. The IIFE has the same shapes at runtime without the names.

| Type                                                                                                                                                                              | Page                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `FiludiSdk`                                                                                                                                                                       | The shape of `sdk` and of `window.FiludiSDK`                                               |
| `InitOptions`, `InitResult`, `MockConfig`, `HostName`, `Features`, `Policy`, `AgeBand`                                                                                            | [init](/docs/sdk/init/)                                                                    |
| `AdResult`, `AdsAvailability`                                                                                                                                                     | [ads](/docs/sdk/ads/)                                                                      |
| `SaveRead<T>`, `SaveWrite`                                                                                                                                                        | [save](/docs/sdk/save/)                                                                    |
| `Period`, `LeaderboardEntry`, `SubmitResult`, `TopResult`, `MeResult`                                                                                                             | [leaderboard](/docs/sdk/leaderboard/)                                                      |
| `Player`                                                                                                                                                                          | [player](/docs/sdk/player/)                                                                |
| `TrackProps`                                                                                                                                                                      | [track](/docs/sdk/track/)                                                                  |
| `HostEvents`, `Consent`, `Device`, `Off`                                                                                                                                          | [host events, fullscreen and device](/docs/sdk/events/)                                    |
| `HostExtras`, `CrazygamesExtras`, `PokiExtras`, `PlaygamaExtras`                                                                                                                  | [host extras](/docs/sdk/host/)                                                             |
| `FiludiInit`, `Adapter`, `AdapterContext`, `AdapterEvent`, `AdapterInit`, `AdKind`, `ParentMessage`, `RemoteSaveWrite`, `ScoreSubmission`, `Session`, `SignedScore`, `TrackEvent` | The handshake and the adapter contract, for a hub or a host implementation, not for a game |

<CodePanel title="Typed wrappers">
  <Fragment slot="javascript">
    ```js
    import { sdk, version } from '@filudi/game-sdk';

    console.log(`Filudi SDK ${version}`);
    // Without a bundler: window.FiludiSDK.version
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import { sdk, version, type FiludiSdk, type SaveRead } from '@filudi/game-sdk';

    interface MySave { level: number }

    class Platform {
      constructor(private readonly api: FiludiSdk = sdk) {}
      load(): Promise<SaveRead<MySave>> {
        return this.api.save.get<MySave>();
      }
    }
    console.log(`Filudi SDK ${version}`);
    ```

  </Fragment>
</CodePanel>

## Errors and logging

Nothing throws after `init()`. Failures are statuses on the result: `unavailable`, `rejected`, `conflict`,
`too-large`, `error`. The programming errors that throw: a method called before `init()` was called at all,
and `player.get()`, `ads.available()`, `i18n.locale()` or `device()` called before `init()` resolved.

`init({ debug: true })` or `?filudi_debug=1` on the page URL logs every call and every host message to the
console with the prefix `[filudi-sdk]`. Leave it off in a release.

<CodePanel title="Debug logging">
  <Fragment slot="javascript">
    ```js
    await sdk.init({ gameId: 'gloop', debug: location.hostname === 'localhost' });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    await sdk.init({ gameId: 'gloop', debug: import.meta.env.DEV });
    ```

  </Fragment>
</CodePanel>

## Browsers and size

Last two versions of Chrome, Firefox, Safari and Edge; iOS 16 and later. Signed scores need
`crypto.subtle`; without it `submit` returns `rejected` with reason `signature` and everything else works.
No `eval`, no `document.write`, no inline script: the SDK runs under the `script-src 'self'` policy of the
bundle route.

Two builds, 12 kB gzipped each on every host path:

- ESM, `dist/index.js`: the core, the filudi adapter and the standalone adapter in the entry; the portal
  adapters and the rich mock as chunks loaded with `import()` when that host is detected.
- IIFE, `dist/filudi-sdk.iife.js`: one file with the core, filudi, standalone and the three portal
  adapters, as `window.FiludiSDK` plus `FiludiSDK.version`. No rich mock: host `mock` behaves as
  standalone.

Each release lists its changes in the package's changelog on npmjs.com. Pin the exact version and read
the changelog before moving.

Source: https://developers.filudi.com/docs/sdk/types/