Whistle.day API

Everything one projector screen shows

One assembled payload: the tournament, its stages with their pools, tables and rounds, what is playing now, what is next, recent results, courts and sponsors. Teams are sent once in entries and referenced by id everywhere else. A side of a match that nobody has qualified for yet has an empty entry and a label to draw instead, such as Winner SF1.

The response carries an ETag. Send it back in If-None-Match and an unchanged tournament answers 304. A screen whose tournament is still a draft answers 404, the same as a token that does not exist. This endpoint has no rate limit.

Parameters

Responses

{
  "generated_at": "2026-10-03T09:41:12Z",
  "tournament": {
    "id": "t8w2k1m0q9x4c7z",
    "name": "Autumn Cup",
    "sport": "volleyball",
    "location": "Sports hall B",
    "logo": "",
    "status": "live"
  },
  "display": {
    "id": "d3n5p7r9t1v2x4z",
    "name": "Main wall",
    "mode": "auto",
    "rotate_seconds": 15,
    "scope": {
      "stage": "",
      "pool": "",
      "court": ""
    },
    "theme": {
      "mode": "dark"
    },
    "panels": []
  },
  "entries": {
    "e1a2b3c4d5f6g7h": {
      "id": "e1a2b3c4d5f6g7h",
      "name": "Kestrels",
      "short_name": "KES",
      "club": "",
      "logo": "",
      "seed": 1
    },
    "e2b3c4d5f6g7h8j": {
      "id": "e2b3c4d5f6g7h8j",
      "name": "Otters",
      "short_name": "OTT",
      "club": "",
      "logo": "",
      "seed": 2
    }
  },
  "courts": [
    {
      "id": "c9y8x7w6v5u4t3s",
      "name": "Court 1",
      "position": 0
    }
  ],
  "stages": [
    {
      "id": "s4h6j8k0m2n4p6q",
      "position": 0,
      "name": "Groups",
      "name_kind": "groups",
      "format": "round_robin",
      "status": "live",
      "pools": [
        {
          "id": "p1q2r3s4t5u6v7w",
          "name": "A",
          "kind": "group",
          "advance_count": 2,
          "standings": [
            {
              "position": 1,
              "entry": "e1a2b3c4d5f6g7h",
              "played": 1,
              "won": 1,
              "drawn": 0,
              "lost": 0,
              "score_for": 2,
              "score_against": 0,
              "points": 2,
              "qualified": false,
              "tiebreak": [
                "points"
              ]
            }
          ],
          "rounds": [
            {
              "round": 0,
              "fixtures": [
                {
                  "id": "f7g8h9j0k1m2n3p",
                  "code": "A1",
                  "stage": "s4h6j8k0m2n4p6q",
                  "pool": "p1q2r3s4t5u6v7w",
                  "round": 0,
                  "position": 0,
                  "status": "finished",
                  "home": {
                    "entry": "e1a2b3c4d5f6g7h",
                    "label": "Kestrels",
                    "score": 2
                  },
                  "away": {
                    "entry": "e2b3c4d5f6g7h8j",
                    "label": "Otters",
                    "score": 0
                  },
                  "winner": "e1a2b3c4d5f6g7h",
                  "court": "c9y8x7w6v5u4t3s",
                  "scheduled_at": "2026-10-03 09:00:00.000Z",
                  "games": [
                    {
                      "number": 1,
                      "home": 25,
                      "away": 19
                    },
                    {
                      "number": 2,
                      "home": 25,
                      "away": 22
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "now_playing": [],
  "next_up": [],
  "recent": [],
  "sponsors": []
}

A club and the tournaments it has run

The club's name, colour and logo, and every tournament its owner has listed on it, newest first. A draft is left out. date is when the tournament is played if that was ever set, and when it was created otherwise. screen is the token of one of the tournament's active screens, for /m/{screen} or GET /api/display/{token}, and is empty when it has none.

There is no endpoint that lists clubs: this one answers for a slug you already have.

Parameters

Responses

{
  "club": {
    "id": "c4h7k2m9p1r3t5v",
    "name": "TJ Sokol Brno",
    "slug": "tj-sokol-brno",
    "accent": "#0b7a43",
    "logo": "/api/files/pbc_1219621782/c4h7k2m9p1r3t5v/crest_a1b2c3d4e5.png"
  },
  "tournaments": [
    {
      "id": "t8w2k1m0q9x4c7z",
      "name": "Autumn Cup",
      "sport": "volleyball",
      "location": "Sports hall B",
      "status": "live",
      "date": "2026-10-03T08:00:00Z",
      "screen": "hala-1"
    }
  ]
}

Draw a stage that does not exist

A format, a field and a config in, a plan out. It runs the same generators a real stage does and touches no stored data, so it needs no account. Send either teams (a count, numbered Team 1, Team 2, …) or names; names wins when both are present.

format is one of round_robin, single_elim, double_elim or swiss. config takes the same keys a stage's config does: poolCount, advancePerPool, legs, thirdPlace, consolation and rounds. seedFrom is refused, because there is no earlier stage to read. The field is capped at 128 teams and the endpoint at 60 requests a minute per IP address. Responses may be cached for an hour.

Request body

{
  "format": "single_elim",
  "names": [
    "Kestrels",
    "Otters"
  ],
  "config": {
    "thirdPlace": false
  }
}

Responses

{
  "format": "single_elim",
  "plan": {
    "pools": [
      {
        "key": "pool:main",
        "name": "Main",
        "name_kind": "main",
        "position": 0,
        "kind": "winners",
        "advance_count": 1
      }
    ],
    "slots": [
      {
        "key": "slot:0:0",
        "pool_key": "pool:main",
        "round": 0,
        "position": 0,
        "label": "Kestrels",
        "entry": "preview1",
        "source_type": "direct",
        "source_fixture_key": "",
        "source_pool": "",
        "source_stage": "",
        "source_position": 1
      },
      {
        "key": "slot:0:1",
        "pool_key": "pool:main",
        "round": 0,
        "position": 1,
        "label": "Otters",
        "entry": "preview2",
        "source_type": "direct",
        "source_fixture_key": "",
        "source_pool": "",
        "source_stage": "",
        "source_position": 2
      },
      {
        "key": "slot:1:0",
        "pool_key": "pool:main",
        "round": 1,
        "position": 0,
        "label": "Winner F",
        "label_kind": "winner_of",
        "label_args": {
          "code": "F"
        },
        "entry": "",
        "source_type": "fixture_winner",
        "source_fixture_key": "fixture:0:0",
        "source_pool": "",
        "source_stage": "",
        "source_position": 0
      }
    ],
    "fixtures": [
      {
        "key": "fixture:0:0",
        "pool_key": "pool:main",
        "round": 0,
        "position": 0,
        "code": "F",
        "home_slot_key": "slot:0:0",
        "away_slot_key": "slot:0:1",
        "status": "pending"
      }
    ]
  }
}

Sign in

PocketBase's own sign-in. identity is the email address of the account. The token in the answer is what every authenticated request sends in its Authorization header.

Request body

{
  "identity": "jana@example.com",
  "password": "correct horse battery"
}

Responses

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "record": {
    "id": "u5k7m9p1r3t5v7x",
    "collectionName": "users",
    "email": "jana@example.com",
    "verified": true
  }
}

Trade a token for a fresh one

PocketBase's own refresh. Send the token you hold; the answer has the same shape as signing in.

Responses

List records

A page of one collection. Records of a published tournament are returned to anybody; records of a draft only to its owner and crew, and without a token they are simply absent from the list rather than refused.

displays is the exception: anonymously it returns a screen only when the request carries that screen's ?token=.

Parameters

Responses

{
  "page": 1,
  "perPage": 30,
  "totalItems": 1,
  "totalPages": 1,
  "items": [
    {
      "id": "c9y8x7w6v5u4t3s",
      "collectionName": "courts",
      "tournament": "t8w2k1m0q9x4c7z",
      "name": "Court 1",
      "position": 0
    }
  ]
}

Create a record

Anybody signed in can create a tournament, and becomes its owner. Courts, entries, stages, displays and sponsors are created by the tournament's owner or crew, invites and crew rows by the owner alone. standings and fixture_events are written by the server and accept nothing.

A stage created here has no matches until POST /api/stages/{stage}/generate draws it. An entry created after the draw is not in any stage until POST /api/entries/{entry}/admit fits it in.

Parameters

Request body

{
  "tournament": "t8w2k1m0q9x4c7z",
  "name": "Kestrels",
  "short_name": "KES",
  "seed": 1,
  "status": "registered"
}

Responses

Read one record

The same access as listing. A record you may not see answers 404, not 403.

Parameters

Responses

Update a record

Send only the fields that change. Entering a result is a patch to a fixture: settling it is what fills the slots that were waiting on it, rebuilds the tables, draws the next Swiss round and seeds a playoff from a finished group, all before the response is sent.

A level score is refused with 400 when the tournament's scoring does not allow draws, and always in a knockout stage. A best-of series accepts only the scores a series can end on.

Parameters

Request body

{
  "home_score": 2,
  "away_score": 1,
  "status": "finished"
}

Responses

Delete a record

Deleting a tournament deletes everything under it. Deleting a crew row removes that person's access immediately.

Parameters

Responses

Be told when a tournament changes

PocketBase's server-sent event stream. The first event is PB_CONNECT and carries a clientId; post that id back with the topics you want. Whistle.day broadcasts on tournament/{id} whenever anything a screen renders is written. The message says that something changed and never what, so the thing to do on receiving one is to read GET /api/display/{token} or the records again.

Keep a slow poll underneath: a connection that looks open and has stopped delivering is the failure worth planning for.

Responses

Choose what the stream delivers

Sets the subscriptions of an open stream, replacing whatever it had.

Request body

{
  "clientId": "kX2bQ9…",
  "subscriptions": [
    "tournament/t8w2k1m0q9x4c7z"
  ]
}

Responses

Draw a stage

Writes the stage's pools, slots and fixtures from its format, its config and the tournament's entries, then fills in whatever can already be resolved. With ?dry_run=1 nothing is written and the answer is the plan itself, in the shape POST /api/preview returns, so a preview and the real draw come out of the same generator.

A playoff seeded from an earlier stage sets config.seedFrom to { "stage": "<id>", "advancePerPool": 2 } and is filled from that stage's tables as its groups finish.

Parameters

Responses

{
  "stage": "s4h6j8k0m2n4p6q",
  "pools": 2,
  "slots": 8,
  "fixtures": 12
}

Re-resolve a stage

Recomputes who goes where from the results already entered. Results resolve themselves as they are written, so this is the repair path: after a score is corrected, or when a slot was written after the fixture it reads from. Safe to call twice.

Parameters

Responses

{
  "stage": "s4h6j8k0m2n4p6q",
  "resolved": 3
}

Draw the next Swiss round

A Swiss stage draws each round itself when the last result of the round before it is entered, so this too is a repair path. It depends only on rounds that are complete, which makes it safe to call twice.

Parameters

Responses

{
  "stage": "s4h6j8k0m2n4p6q",
  "round": 2,
  "rematch": false
}

Take a team out

Closes every match the team had left and retallies every stage, in one transaction. policy has no default, because the two answers rank everybody else differently: forfeit lets what they played stand and gives the rest to their opponents as walkovers; void strikes every match they were in, on both sides. status is withdrawn (the default) or disqualified.

Parameters

Request body

{
  "policy": "forfeit",
  "status": "withdrawn"
}

Responses

{
  "entry": "e1a2b3c4d5f6g7h",
  "status": "withdrawn",
  "policy": "forfeit"
}

Put a team back

Undoes exactly what taking them out did, and nothing else: the matches that withdrawal closed are reopened and the tables are rebuilt.

Parameters

Responses

{
  "entry": "e1a2b3c4d5f6g7h",
  "status": "active"
}

Fit in a team that arrived after the draw

Create the entry through the records API first, then call this. What it does depends on the format: in a round robin the team joins the smallest group and gets a match against everybody in it; in a Swiss it takes a seat in the table and is paired from the next round; a knockout drawn from the entries is drawn again, and only while nobody has played in it.

Every stage is checked before anything is written, so a refusal leaves the tournament untouched. A team already in a stage is left where it is.

Parameters

Responses

{
  "entry": "e3c4d5f6g7h8j9k",
  "stages": [
    "s4h6j8k0m2n4p6q"
  ]
}

What a join code is for

The name of the tournament and the role on offer, and nothing else about the event. Public, so that a join screen can say what is being accepted before anybody accepts it. A withdrawn code answers the same 404 as one that never existed.

Parameters

Responses

{
  "name": "Autumn Cup",
  "role": "referee"
}

Accept a join code

Adds the signed-in account to the tournament's crew in the role the code carries. name is what the rest of the crew sees beside the results this person enters; left empty it falls back to the role. Scanning a different role's code changes the role instead of adding a second row, and the owner scanning their own code changes nothing.

Request body

{
  "token": "Zk4mP9qR2sT7vX1b",
  "name": "Jana"
}

Responses

{
  "tournament": "t8w2k1m0q9x4c7z",
  "name": "Autumn Cup",
  "role": "referee"
}

Put an email and a password on a temporary account

Turns the account the wizard made into one somebody can sign in with. It works only on an account that has never had an address. Every token issued before the claim stops working, so sign in again with the new address and password. A confirmation email is sent, and the account works before it is confirmed.

A refusal does not say whether the address is already in use.

Request body

{
  "email": "jana@example.com",
  "password": "correct horse battery"
}

Responses

{
  "email": "jana@example.com"
}

Make a link that hands a tournament to a person

For an account that cannot claim itself, which in practice is one an agent is holding. The owner mints a link, sends it to whoever is running the day, and that person sets their own email and password on it. The link is single-use and expires after 24 hours; minting another burns the one before it.

Request body

{
  "tournament": "t8w2k1m0q9x4c7z"
}

Responses

{
  "token": "4f9c…",
  "url": "https://whistle.day/claim/4f9c…",
  "expires": "2026-10-04 09:41:12.000Z"
}

What a handoff link is for

The name of the tournament on offer. Public, because the person opening the link has no account yet.

Parameters

Responses

{
  "tournament": "Autumn Cup"
}

Take a tournament over with an email and a password

Public: the link is the credential. The account behind it gets the address and password sent here, the link is spent, and every token the previous holder had stops working. Sign in afterwards with what was just set.

Parameters

Request body

{
  "email": "jana@example.com",
  "password": "correct horse battery"
}

Responses

{
  "email": "jana@example.com",
  "tournament": "t8w2k1m0q9x4c7z"
}

Start taking a tournament over with Google or Facebook

The first of two requests either side of the provider's redirect. It returns a token for the account behind the link, so that completing PocketBase's own OAuth2 sign-in with it links the provider to that account instead of creating a new one. Nothing about the account changes here and the link is not spent.

Parameters

Responses

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
}

Finish taking a tournament over with Google or Facebook

The second request, sent with the token from oauth-session once the provider has been linked. The link is spent, the account's old password and tokens stop working, and the answer carries the one token that still does. email is optional: send the address the provider returned to put it on the account.

Parameters

Request body

{
  "email": "jana@example.com"
}

Responses

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "email": "jana@example.com",
  "tournament": "t8w2k1m0q9x4c7z"
}

Delete the account and everything it owns

Permanent. Every tournament the account owns is deleted with its courts, teams, stages, matches, tables, screens and crew; the account is removed from the crews it was on, and from any match it was down to referee.

Responses

{
  "deleted": true
}

Delete the account, for clients that cannot send DELETE

The same operation as DELETE /api/organiser/account.

Responses

{
  "deleted": true
}

Open the stream an MCP client listens on

Server-to-client messages for the session in Mcp-Session-Id.

Responses

Send an MCP request

The MCP server, over Streamable HTTP: JSON-RPC in the body, the session in the Mcp-Session-Id header the server hands out on initialize. No credential is needed to start: create_tournament makes a temporary account and the session remembers it. A client that has been through the OAuth flow below sends its access token as Authorization: Bearer and works on that account instead. Limited to 120 requests a minute per IP address.

Responses

End an MCP session

Ends the session in Mcp-Session-Id. A temporary account lasts as long as the session that made it, so call the create_handoff tool first to keep the tournament.

Responses

Where the MCP server's tokens come from

Protected resource metadata (RFC 9728): names /api/mcp as the resource and this host as its authorization server.

Responses

The OAuth endpoints and what they support

Authorization server metadata (RFC 8414), and the authoritative list of the endpoints below. Authorization code with PKCE (S256) and refresh tokens, public clients only, one scope: tournaments.

Responses

Register an OAuth client

Dynamic client registration (RFC 7591). Send redirect_uris and a client_name; the answer carries the client_id to use from then on. There is no client secret.

Responses

Ask a person to connect their account

The authorization endpoint. Send the browser here with a standard authorization code request carrying a PKCE code_challenge; the person signs in, approves, and is sent back to the client's redirect_uri with a code.

Responses

Exchange a code or a refresh token

The token endpoint, taking grant_type=authorization_code with the PKCE code_verifier, or grant_type=refresh_token. Refresh tokens rotate: each one is good once, and using a spent one revokes the whole family.

Responses