Docs menu

API reference

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
Commands22 (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 keys22 in 6 sections, plus [properties] for any other vanilla key
Control API endpoints11 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.

Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.

Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.