Server IDs

The id is a server's permanent identity. Its directory name, its keys in the catalog and its media URLs all depend on it. It must not change when the display name does.

RulesCopy Anchor Link

• 2 to 32 characters.
• Lowercase ASCII letters, digits, and single hyphens between them. The pattern is ^[a-z0-9]+(?:-[a-z0-9]+)*$.
• Equal to the name of the server's directory under servers/.

Valid: hypixel, minemen-club, example-server.

Invalid: My Server (spaces and uppercase), -start and end- (leading or trailing hyphen), a--b (double hyphen), ../x (path characters), Upper (uppercase).

The id becomes a path segment and a URL segment, so the validator checks it before using it for anything else.

Renaming a serverCopy Anchor Link

If a server changes its display name, edit name in metadata.json and keep the id. Its URLs keep working.

If the network changes its identity completely, retire the old id and add the new server under a new id. Do not reuse the old directory for a different network.

RetirementCopy Anchor Link

A retired id can never be used again, even after its directory is deleted. The file retired-ids.json records each one, with the date and the reason:

{
  "schemaVersion": 1,
  "retired": [
    {
      "id": "old-network",
      "retiredOn": "2026-10-23",
      "reason": "Network closed; the id is kept so that URLs never point to another server."
    }
  ]
}

Retirement means deleting the server's directory and adding its id to this file, in a pull request. Clients that cached the old id see it disappear from the catalog, which is the intended behavior.