Ludovic MarieandClaude Opus 5.5
0a1d3a7534
docs/api/ gets one page per surface other programs build on (mods, shaders, agent control, servers, the launcher, data formats), each with an overview measured from the source, the guide, the generated reference, examples, its stability, what is not there yet and a changelog, plus the policy every API follows (docs/api/stability.md): a version per API, semver lines, experimental / preview / stable, deprecation windows, compatibility tests and the level of every part today. The website gets a "Build on Horizon" page (website/docs/apis.md) that summarises them and links the repository's pages. Co-Authored-By: Claude Opus 5.5 <[email protected]>
3.0 KiB
Server API
What a host, a panel or a bot can do with a Horizon server: the horizon-server commands, server.toml and the
control API. How to host: hosting.md; the design: server.md.
Overview
horizon-server sets up a server folder, runs the game as a dedicated server under a supervisor (restarts on a crash,
backups on a schedule, updates with a rollback), and lets other programs manage it through a local HTTP API with a
token. The web panel uses that API.
| Count | |
|---|---|
| Commands | 22 (init, run, start, stop, restart, status, cmd, logs, backup, backups, restore, service, panel, update, rollback, config, config set, import, op, deop, whitelist, version) |
server.toml keys |
22 in 6 sections, plus [properties] for any other vanilla key |
| Control API endpoints | 11 under /api/v1 |
Guide
horizon-server initin an empty folder, thenhorizon-server start(hosting.md).- From a script:
horizon-server status --json,horizon-server cmd say hi,horizon-server backup. - From a program: read
.horizon/api.json(address and token), thenGET /api/v1/statuswithAuthorization: Bearer <token>.
Reference
server-reference.md, generated from horizon-server's source: the help text, every
server.toml key with its default and the server.properties key it writes, and every endpoint.
Examples
token=$(jq -r .token .horizon/api.json); address=$(jq -r .address .horizon/api.json)
curl -s -H "Authorization: Bearer $token" "http://$address/api/v1/status"
curl -s -H "Authorization: Bearer $token" -d '{"line": "list"}' "http://$address/api/v1/command"
Stability
Stable (stability.md): the commands, server.toml's keys and /api/v1. A new key or endpoint is an
addition; a change to one starts /api/v2, served beside /api/v1.
Not there yet
- Players: list with ping and position, kick, ban and pardon, op and deop, the whitelist, as endpoints (today only
through
cmdand the files). - Console stream: the log as a stream (server-sent events) rather than
logs?since=Npolling; chat, joins, leaves, deaths and crashes as typed events. - Metrics: a plain-text metrics endpoint any monitoring tool can scrape (TPS, MSPT percentiles, players, chunks,
entities, RAM, CPU), from the samples
statusalready takes. - Backups: delete and download one; restore a single dimension.
- Server mods: list, turn on and off, and their settings, once the mod API runs on the server (mods.md).
- An MCP server for the same endpoints, so a host's agent manages the server as it manages the game.
- Compatibility tests: golden replies per endpoint, and a
server.tomlfrom each release line.
Changelog
api::ROUTESlists the endpoints; the reference is generated from it./api/v1: status, metrics, logs, command, stop, restart, backups, restore, update, panel login.