STYGION Documentation Search the docs

The interface — every route

All 76 paths of the local API in 0.3.0: the scope each needs, what it takes, what it answers — and how to wire your own tooling to it, from this machine and from outside.

Keystone 0.4.3 Updated 16 min read

This page is older than Keystone 0.4.3, released 15 November 2026. Something may have changed since.

On this page 20 parts
  1. Before you call anything
  2. 1. Make a key
  3. 2. Call it
  4. 3. What the answers mean
  5. How to reach it
  6. From this machine only (the default, and the safe one)
  7. From your own computer, over a tunnel (recommended on a hosted server)
  8. From your home network
  9. From outside, behind a reverse proxy or a tunnel
  10. The live stream
  11. Status and measurement
  12. People and permissions
  13. How to build a shop on it
  14. Operations
  15. Settings and the record
  16. Console, chat and Discord
  17. The assistant
  18. Addons on the JVM
  19. What is written down
  20. Every route in 0.3.0

The interface — every route

This list is not written from memory. The mod generates a document about itself out of its own routes (GET /v1/openapi.json), so it cannot be wrong about what exists — and this page was pulled out of that with scripts/reference.sh in the mod's repository. When you are unsure, ask your server rather than this page.

Current for 0.3.0. There are 76 paths (78 operations); the full list is at the end.


Before you call anything

#

1. Make a key

#
Code
/keystone key new my-tool status.read players.read

A key is printed once and never again. Give it the narrowest set of scopes that does the job: a script watching whether the server is up wants status.read and nothing else.

2. Call it

#
Code
curl -sS -H "Authorization: Bearer ks_…" \
  http://127.0.0.1:25586/v1/status

GET takes its parameters in the address; POST sends them as a form:

Code
curl -sS -X POST -H "Authorization: Bearer ks_…" \
  -d "player=Steve" -d "group=vip" -d "for=30d" \
  -d "note=bought on the site" \
  http://127.0.0.1:25586/v1/players/group

3. What the answers mean

#
Code What it is
200 It worked.
400 Something in the request was wrong, and the answer says what.
403 The key is real but does not hold the scope this route needs.
404 No such route — or no key at all. Those answer identically on purpose, so an unauthenticated caller learns nothing about this server.
429 Past what this key is allowed per minute.

How to reach it

#

From this machine only (the default, and the safe one)

#
Code
[api]
enabled = true
address = "127.0.0.1"
port = 25586

Nothing is visible from outside. The panel and your scripts run on the same machine.

#

Leave the mod on loopback and bring the port to you:

Code
ssh -L 25586:127.0.0.1:25586 you@your-server
curl -sS -H "Authorization: Bearer ks_…" http://127.0.0.1:25586/v1/status

Nothing is exposed, and /keystone panel opens in your own browser.

From your home network

#
Code
/keystone set keystone.api.address 0.0.0.0
/keystone set keystone.api.reachable-at 192.168.1.50

The first says where it listens; the second says which address the mod writes into the editor link and into openapi.json — 0.0.0.0 is a good answer to the first and a useless one to the second. Then open the port to the LAN only, not the world:

Code
sudo ufw allow from 192.168.1.0/24 to any port 25586 proto tcp

From outside, behind a reverse proxy or a tunnel

#

Leave the mod on loopback and put something that speaks TLS in front of it:

Code
location /keystone/ {
    proxy_pass http://127.0.0.1:25586/;
    proxy_set_header Host $host;
}
Code
/keystone set keystone.api.reachable-at keystone.yourserver.eu

Never put api.address on a public address without TLS. The key travels in a header, and over plain http:// across the internet anybody on the path reads it. And the API can do everything the mod can do.


The live stream

#
Code
curl -N -H "Authorization: Bearer ks_…" \
  http://127.0.0.1:25586/v1/events

It holds the connection open and writes events down it as they happen (text/event-stream). Three lines in a browser:

Code
const events = new EventSource('/v1/events');
events.onmessage = (e) => console.log(JSON.parse(e.data));

It is authenticated like everything else and answers 404 without a key.


Status and measurement

#
Method Path Scope What it is for
GET /v1/status status.read What this server is and how it is doing
GET /v1/metrics status.read What it is doing right now, and the last quarter of an hour
GET /v1/metrics/history status.read A minute at a time, as far back as the settings keep it
GET /v1/entities status.read What is loaded in the world, and what a sweep would remove right now
GET /v1/gate status.read Whether the server is open, and how many places are held back
GET /v1/catalog status.read Everything this pack has loaded: the registries, what is in one (?of=minecraft:item, with from/limit/like), or its tags (&tags=true)
GET /v1/bench server.read Load test runs this server has made (?id= for one in full)
GET /v1/openapi.json status.read This document
Code
curl -sS -H "Authorization: Bearer ks_…" \
  "http://127.0.0.1:25586/v1/catalog?of=minecraft:item&like=diamond&limit=20"

People and permissions

#
Method Path Scope What it is for
GET /v1/players players.read Who is online right now
GET /v1/progress players.read What one player has done, or the board for one counter
GET /v1/skins players.read What each player is wearing and where it came from
GET /v1/accounts players.read How many accounts have a password, and who is waiting to prove themselves
GET /v1/bans players.read Every ban that still stands
GET /v1/tickets players.read The tickets on this server (?id= for one with everything said in it, ?player=)
GET /v1/votes players.read Votes this server has been sent, and how the party is doing (?player=, ?limit=)
GET /v1/discord/links players.read Which Minecraft accounts one Discord user has linked here (?discord=<id>)
GET /v1/groups permissions.read Every permission group, heaviest first
POST /v1/players/check permissions.read Whether somebody may do a thing, and which rule decided
POST /v1/players/group permissions.write Put somebody in a group, or extend how long they are in it
POST /v1/players/perk perks.write Give somebody a named benefit, optionally until a date
POST /v1/players/grants perks.read What one player holds, where each came from and when it ends

What they take:

Path Takes
/v1/players/check player — the name of somebody online · permission — the permission to ask about
/v1/players/grants player — the name of somebody online
/v1/players/group player · group — the group id · for — 30d, 12h, 90m, or leave it out for forever · note — why, for whoever reads this later
/v1/players/perk player · perk — what they get · for · note

How to build a shop on it

#

On a server that is not in online mode, a name typed into a form proves nothing. The order is this:

Code
# 1. Who that person is in game — by the Discord they signed in with
curl -sS -H "Authorization: Bearer ks_…" \
  "http://127.0.0.1:25586/v1/discord/links?discord=123456789012345678"

# 2. Deliver what they bought, with an end date
curl -sS -X POST -H "Authorization: Bearer ks_…" \
  -d "player=Steve" -d "group=vip" -d "for=30d" -d "note=order 4821" \
  http://127.0.0.1:25586/v1/players/group

The rank ends on the day by itself. Nobody has to remember to take it back.

Operations

#
Method Path Scope What it is for
GET /v1/operations operations.read What is scheduled and how long is left
GET /v1/operations/history operations.read What has run lately, most recent first
POST /v1/operations/run operations.run Run one now, or after a delay, with its usual warnings
POST /v1/operations/cancel operations.run Call off what is pending and go back to the schedule
POST /v1/gate/maintenance operations.run Close the server for maintenance, or open it again
GET /v1/backups backup.read Every backup there is, newest first, and what they cost on disk
POST /v1/backups/restore backup.restore Put a backup back — staged, and done at the start of the next boot

What they take:

Path Takes
/v1/operations/run operation — which one · in — how many seconds from now, 0 for immediately
/v1/operations/cancel operation — which one
/v1/gate/maintenance closed — true to close, false to open · reason — what is happening, shown to anybody who tries to join · until — when it is expected to end, in your own words
/v1/backups/restore backup — the backup's name, or cancel to call one off

Settings and the record

#
Method Path Scope What it is for
GET /v1/settings settings.read Every setting every module declared, with what each one is and what it holds
POST /v1/settings settings.write Change one. Refused with the reason if the value does not fit what it is
GET /v1/settings/history settings.read Every settings change, newest first, with what each value was before it
POST /v1/settings/rollback settings.write Undo what one version changed. Undoing is itself a version, so it can be undone
POST /v1/reload settings.write Re-read every settings file. Nothing restarts and nobody is disconnected
GET /v1/audit audit.read Who changed what over this interface, newest first. Reading is not recorded; changes and refusals are
GET /v1/keys keys.read The keys this server has issued, without their secrets

What they take: /v1/settings takes setting (its full name, such as operations.restart.when) and value; /v1/settings/rollback takes version.

Code
curl -sS -X POST -H "Authorization: Bearer ks_…" \
  -d "setting=operations.restart.when" -d "value=every 6h" \
  http://127.0.0.1:25586/v1/settings

Everything there is to set is on every setting.

Console, chat and Discord

#
Method Path Scope What it is for
GET /v1/console console.read The last lines this server printed, oldest first. Held in memory, not in the database
GET /v1/chat chat.read The last things said in chat, oldest first
GET /v1/events events.read The live stream of events
GET /v1/discord server.read Whether the Discord bridge is connected, and how far behind it is

The assistant

#
Method Path Scope What it is for
POST /v1/assistant/ask assistant.write Ask it something. The answer comes back with this call
POST /v1/assistant/incident assistant.write Hand it the last stretch of console and chat and ask what looks wrong
POST /v1/assistant/decide assistant.write Agree to a proposed change, or leave it alone
GET /v1/assistant/proposals assistant.read Changes it wants made and nobody has decided on yet
GET /v1/assistant/threads assistant.read The conversations there have been, newest first
GET /v1/assistant/thread assistant.read One conversation, oldest message first

What they take: /v1/assistant/ask takes question; /v1/assistant/decide takes proposal (which one) and answer (yes or no).


Addons on the JVM

#

If you are building an addon in Java you do not talk over HTTP. You compile against keystone-api, which travels inside that same jar (META-INF/jarjar/eu.stygion.keystone.api-<version>.jar) and has no dependencies of its own, not even a logging framework. It is how you register your own module, command, permission, source of ranks — and your own routes, which then appear in this list and in openapi.json exactly like ours.


What is written down

#

Every change through the interface is an audit line: which key, what, when — and every refusal too. A key repeatedly trying what it may not do is the only sign you will get that an integration has been taken over. Sensitive commands are masked out of the audit, the console and the log.


Every route in 0.3.0

#

Pulled out of the 0.3.0 server's openapi.json, with the summary the mod declares for each. The sections above explain the common ones.

Method Path Scope What it is for Takes
GET /v1/accounts players.read How many accounts have a password, and who is waiting to prove themselves —
GET /v1/announce server.read What the server list ping tells launchers, what is wrong with the settings, and the manifest's state —
GET /v1/announce/manifest server.read The manifest as written: every mod file a player needs, with its hashes —
POST /v1/announce/pack settings.write Set the modpack the server list announces from a link or a project id, after looking it up and detecting the version; with check, only show what launchers would see check · pack
POST /v1/assistant/ask assistant.write Ask the assistant something. The answer comes back with this call question
POST /v1/assistant/decide assistant.write Agree to a proposed change, or leave it alone answer · proposal
POST /v1/assistant/incident assistant.write Hand it the last stretch of console and chat and ask what looks wrong —
GET /v1/assistant/proposals assistant.read Changes the assistant wants made and nobody has decided on yet —
GET /v1/assistant/thread assistant.read One conversation, oldest message first —
GET /v1/assistant/threads assistant.read The conversations there have been, newest first —
GET /v1/audit audit.read Who changed what over this interface, newest first. Reading is not recorded; changes and refusals are —
GET /v1/backups backup.read Every backup there is, newest first, and what they cost on disk —
POST /v1/backups/restore backup.restore Put a backup back — staged, and done at the start of the next boot backup
GET /v1/bans players.read Every ban that still stands —
GET /v1/bench server.read Load test runs this server has made (?id= for one in full) —
GET /v1/catalog status.read Everything this pack has loaded: the registries, what is in one (?of=minecraft:item, with from/limit/like), or its tags (&tags=true) —
GET /v1/chat chat.read The last things said in chat, oldest first —
GET /v1/chat/channels settings.read The chat channels as the server reads them now: whether they are on, every channel with its keys, and how many players online write in and hear each one —
POST /v1/chat/channels/preview settings.read Read a channel list that may not be saved yet and draw one example line in each channel, with the chat format as it is or as drafted message · chat.format.default · chat.channels.list
POST /v1/chat/preview settings.read One chat line drawn for an example sender of every group, from the settings as they are or with some of them replaced - so a draft can be seen before it is applied message · chat.format.default · preset
GET /v1/chat/styles settings.read The ready-made chat formats, each shown for two example senders, with the names a format may use and the built-in shortcodes —
GET /v1/console console.read The last lines this server printed, oldest first. Held in memory, not in the database —
GET /v1/discord server.read Whether the Discord bridge is connected, and how far behind it is —
GET /v1/discord/links players.read Which Minecraft accounts one Discord user has linked here (?discord=) —
GET /v1/discord/stats stats.read Vanilla statistics of every player linked to Discord (?keys=category/id,category/*,keystone:placed) —
GET /v1/entities status.read What is loaded in the world, and what a sweep would remove right now —
POST /v1/export pack.read Write the pack data dump (items, tags, recipes, advancements, loot, names; Workbench's format 1) on this running server; answers with its id. One at a time —
GET /v1/export pack.read How a pack data dump is going (?id=, else the latest): running, done with its size and counts, or failed with why id
GET /v1/export/zip pack.read The finished pack data dump itself, as application/zip (?id=) id
GET /v1/gate status.read Whether the server is open, and how many places are held back —
POST /v1/gate/maintenance operations.run Close the server for maintenance, or open it again closed · until · reason
GET /v1/groups permissions.read Every permission group, heaviest first —
GET /v1/guard status.read A summary of the update guard: boots, a hold, how much changed, the state of the update, off-site backups and the drill, the last crashes with their suspects (no stack, no error text, no paths) —
GET /v1/guard/detail backup.restore Everything the update guard knows: the full diff, crash reports with their stacks, the staged plan, error texts and where off-site backups go (never a key, password or user) —
POST /v1/guard/drill backup.restore Read the newest off-site backup back now (answers at once; GET /v1/guard says the result) —
POST /v1/guard/rollback backup.restore Go back to the last good start: the mods and config files as they were, done at the next stop (cancel=true calls it off) cancel
POST /v1/guard/update backup.restore check=true asks CurseForge now; apply=true restarts in a minute to put a prepared update in check · apply
GET /v1/homes homes.read Players' homes: whose, the name, where it leads and when it was set; with the limit per group player
POST /v1/homes/delete homes.write Delete a player's home name · player
GET /v1/keys keys.read The keys this server has issued, without their secrets —
GET /v1/languages settings.read Every language the server has, which ones it offers, its default, and English as the jar carries it (?code= adds one language's own file) —
POST /v1/languages/save languages.write Write a language file whole and read the messages again. Placeholders are checked against English; a line left out falls back to English file · code · entries
POST /v1/links/redeem perks.write Spend a link code a player got in game with /link, for an account on your own site; answers who it belongs to (one use; 10 wrong codes a minute per key) code
GET /v1/metrics status.read What the server is doing right now, and the last quarter of an hour —
GET /v1/metrics/history status.read A minute at a time, as far back as the settings keep it —
GET /v1/mutes players.read Every mute that still stands: whose, why, by whom and until when —
GET /v1/openapi.json status.read This document —
GET /v1/operations operations.read What is scheduled and how long is left —
POST /v1/operations/cancel operations.run Call off what is pending and go back to the schedule operation
GET /v1/operations/history operations.read What has run lately, most recent first —
POST /v1/operations/run operations.run Run one now, or after a delay, with its usual warnings operation · in
GET /v1/players players.read Who is online right now —
POST /v1/players/check permissions.read Whether somebody may do a thing, and which rule decided permission · player
POST /v1/players/grants perks.read What one player holds, where each came from and when it ends player
POST /v1/players/group permissions.write Put somebody in a group, or extend how long they are in it note · for · group · player · from
POST /v1/players/perk perks.write Give somebody a named benefit, optionally until a date for · player · perk · note
POST /v1/players/ungroup permissions.write Take somebody out of a group, but only what this key put them in. Other sources' grants stay. Answers how many were removed; 0 is fine group · player
GET /v1/profiler status.read The profiler's reports, newest first, and whether a run is going —
POST /v1/profiler/live status.read Live view: keeps ten-second runs going for a minute after the last ask and answers the newest —
GET /v1/profiler/report status.read One report: mods in ms per tick, the flame graph, the costliest things and chunks (?id=) —
POST /v1/profiler/start operations.run Start a run of so many seconds (default 60) seconds
GET /v1/progress players.read What one player has done, or the board for one counter —
POST /v1/reload settings.write Re-read every settings file. Nothing restarts and nobody is disconnected —
GET /v1/settings settings.read Every setting every module declared, with what each one is and what it holds —
POST /v1/settings settings.write Change one setting. Refused with the reason if the value does not fit what it is value · check · setting
GET /v1/settings/history settings.read Every settings change, newest first, with what each value was before it —
POST /v1/settings/rollback settings.write Undo what one version changed. Undoing is itself a version, so it can be undone version
GET /v1/skins players.read What each player is wearing and where it came from —
GET /v1/status status.read What this server is and how it is doing —
POST /v1/tablist/preview settings.read The tab list drawn for an example player of every group: the header, the footer and the row, from the lines given - so a draft can be seen before it is applied teams.colour · teams.colours · name · footer · teams.nametag-suffix · teams.nametag · afk.mark · header · language
GET /v1/tickets players.read The tickets on this server (?id= for one with everything said in it, ?player=) —
POST /v1/tickets/close tickets.write Close a ticket; the player is told in the game ticket · by
POST /v1/tickets/reply tickets.write Answer a ticket as the team; the player reads it in the game author · ticket · said
GET /v1/votes players.read Votes this server has been sent, and how the party is doing (?player=, ?limit=) —
GET /v1/votes/lists players.read The vote sites in votes.lists, and with ?player= when that player can vote on each (asks the sites that can say) —
GET /v1/votes/top players.read Who voted most in a month (?month=2026-10, this month by default) —
GET /v1/warps server.read Every warp: its name, where it leads, who set it and when, and whether its world is loaded —
POST /v1/warps/delete warps.write Delete a warp by name name

Did this page help?

Opens the feedback panel with this page attached. It lands in the same queue as everything else.