RustNotMC/docs/api/server.md

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

1. horizon-server init in an empty folder, then horizon-server start (hosting.md).
2. From a script: horizon-server status --json, horizon-server cmd say hi, horizon-server backup.
3. From a program: read .horizon/api.json (address and token), then GET /api/v1/status with Authorization: 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 cmd and the files).
• Console stream: the log as a stream (server-sent events) rather than logs?since=N polling; 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 status already 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.toml from each release line.

Changelog

• api::ROUTES lists the endpoints; the reference is generated from it.
• /api/v1: status, metrics, logs, command, stop, restart, backups, restore, update, panel login.