Server‐API

Server API

Server API entries are polled from <dataSyncUrl>/<dataSyncEndpoint> (default endpoint: server_data) on a configurable interval. The gamemaster server responds with a JSON array. Requires webDataSync to be enabled.

Mods built on Apibalego can register additional entries beyond the built-in ones. Check those mods' own documentation for their entries.

See also: Client API Entries, Server Live Updates, Client Live Updates

---

Data format

Each entry in the response array has:

Field	Type	Description
type	string (resource ID)	Identifies which handler processes this entry.
id	string	Stable identifier for this entry. Used for deduplication (e.g. a toast is shown once per player per id).
active	boolean	If false, the entry is ignored. Defaults to true.
details	object	Handler-specific payload. May be omitted for entries with no extra data.

Active entries are stored in memory and replayed to players who join mid-session.

Example response:

[
  {
    "type": "apibalego:toast",
    "id": "session-start",
    "active": true,
    "details": {
      "title": "The session has started!",
      "message": "Good luck."
    }
  }
]

---

apibalego:toast

Shows a toast notification to all online players. Each player sees it once per unique id. Players who join later also receive active toast entries.

You can also directly send toasts via Server Live Updates, this is meant when you want them in sync with something else

Field	Type	Description
title	Component	Toast title. Supports JSON text component format or plain string.
message	Component	Toast body text. Optional.
item	string	Item ID (e.g. "minecraft:diamond"). Sets the icon in the toast. Optional.

Example:

{
  "title": "New area unlocked",
  "message": "Head north to find the ruins.",
  "item": "minecraft:compass"
}

---

apibalego:command

Runs a server command once. Each entry's id is persisted in world save data; the command does not re-run on world reload if the id has already been seen.

Requires remoteCommandExecution to be enabled in the config.

Field	Type	Description
command	string	The command to run, without a leading /.
x, y, z	int	Optional position for the command source.

Example:

{
  "command": "weather thunder 6000"
}

---

apibalego:structure

Spawns a structure at a fixed position in the overworld. All active structure entries are applied on server start.

Field	Type	Description
structureId	string (resource ID)	ID of the structure to spawn.
startPos	BlockPos ({"x":0,"y":0,"z":0})	Position to spawn the structure at.
rotation	string	One of NONE, CLOCKWISE_90, CLOCKWISE_180, COUNTERCLOCKWISE_90. Defaults to NONE.

Example:

{
  "structureId": "mymod:watchtower",
  "startPos": { "x": 500, "y": 70, "z": -300 },
  "rotation": "CLOCKWISE_90"
}

---

apibalego:datapack

Downloads a datapack from a URL and activates it on the server. The file is managed by Apibalego and removed when the entry becomes inactive.

Requires remoteDatapackSync to be enabled. By default the download URL must be on the same origin as dataSyncUrl. Set remoteDatapackAllowExternalUrl to allow any URL.

Field	Type	Description
downloadUrl	string	URL to download the datapack zip from.
version	string	Version string used to identify the file on disk. Change this to force a fresh download. Defaults to "".

Example:

{
  "downloadUrl": "https://my-server.example/packs/event-pack.zip",
  "version": "1.2"
}

---

For mod developers

Register a handler for a custom entry type:

Apibalego.registerApiHandler(
    id("my_entry"),
    MyEntryData.serializer(),
    object : ApiEntryHandler<MyEntryData> {
        override fun handleApiUpdate(server: MinecraftServer, entries: Collection<ApiEntry<MyEntryData>>) {
            // called on each poll cycle with all active entries of this type
        }
        override fun handleApiJoin(player: ServerPlayer, entries: Collection<ApiEntry<MyEntryData>>) {
            // called when a player joins, with all currently active entries (optional)
        }
    }
)

MyEntryData must be a @Serializable Kotlin data class mapping to the details field.

Enable generateApiDocs in the config to dump all registered entries to apibalego-docs/ as markdown files on server start.