Rozhraní — úplný seznam
Všech 76 cest lokálního API ve 0.3.0: co potřebují za scope, co berou, co vrací — a jak si na to napojit vlastní nástroj, z téhle mašiny i zvenčí.
Stránka je starší než Keystone 0.4.3, vydaný 15. listopadu 2026. Od té doby se něco mohlo změnit.
Na téhle stránce 20 částí
- Než něco zavoláš
- 1. Vyrob si klíč
- 2. Zavolej
- 3. Co znamenají odpovědi
- Kudy se k tomu dostaneš
- Jen z téhle mašiny (výchozí, a je to ta bezpečná volba)
- Z tvého počítače, přes tunel (doporučené u hostovaného serveru)
- Z domácí sítě
- Zvenčí, přes reverzní proxy nebo tunel
- Živý proud
- Stav a měření
- Lidi a oprávnění
- Jak z toho udělat obchod
- Provoz
- Nastavení a záznam
- Konzole, chat a Discord
- Asistent
- Addony na JVM
- Co se zapisuje
- Všechny cesty ve 0.3.0
Rozhraní — úplný seznam
Tenhle seznam není psaný z hlavy. Mod si dokument o sobě generuje ze svých vlastních rout (GET /v1/openapi.json), takže se nemůže mýlit v tom, co existuje — a tahle stránka je z něj vytažená příkazem scripts/reference.sh v repozitáři modu. Když si nejsi jistý, ptej se svého serveru, ne téhle stránky.
Platí pro 0.3.0. Cest je 76 (78 operací); úplný seznam je na konci.
Než něco zavoláš
#1. Vyrob si klíč
#/keystone key new muj-nastroj status.read players.read
Klíč se vypíše jednou a nikdy víc. Dej mu tu nejužší sadu scopů, která odvede práci: skript, co hlídá, jestli server běží, chce status.read a nic dalšího.
2. Zavolej
#curl -sS -H "Authorization: Bearer ks_…" \
http://127.0.0.1:25586/v1/status
GET bere parametry v adrese, POST je posílá jako formulář:
curl -sS -X POST -H "Authorization: Bearer ks_…" \
-d "player=Honza" -d "group=vip" -d "for=30d" \
-d "note=koupeno na webu" \
http://127.0.0.1:25586/v1/players/group
3. Co znamenají odpovědi
#| Kód | Co to je |
|---|---|
200 |
Vyšlo to. |
400 |
Něco v požadavku nesedělo, a odpověď říká co. |
403 |
Klíč je pravý, ale nemá scope, který ta cesta chce. |
404 |
Taková cesta není — nebo nemáš klíč vůbec. Odpovídá se stejně schválně: volající bez klíče se o tomhle serveru nedozví nic. |
429 |
Překročil jsi, co ten klíč smí za minutu. |
Kudy se k tomu dostaneš
#Jen z téhle mašiny (výchozí, a je to ta bezpečná volba)
#[api]
enabled = true
address = "127.0.0.1"
port = 25586
Nic není vidět zvenčí. Panel i tvoje skripty běží na tom samém stroji.
Z tvého počítače, přes tunel (doporučené u hostovaného serveru)
#Nechej mod na loopbacku a přines si port k sobě:
ssh -L 25586:127.0.0.1:25586 ty@tvuj-server
curl -sS -H "Authorization: Bearer ks_…" http://127.0.0.1:25586/v1/status
Nic se nevystavuje a /keystone panel se otevře u tebe v prohlížeči.
Z domácí sítě
#/keystone set keystone.api.address 0.0.0.0
/keystone set keystone.api.reachable-at 192.168.1.50
První říká, kde se poslouchá, druhé, jakou adresu si má mod napsat do odkazu na editor a do openapi.json — 0.0.0.0 je dobrá odpověď na to první a nepoužitelná na to druhé. K tomu pusť port jen z LAN, ne ze světa:
sudo ufw allow from 192.168.1.0/24 to any port 25586 proto tcp
Zvenčí, přes reverzní proxy nebo tunel
#Nech mod na loopbacku a postav před něj něco, co umí TLS:
location /keystone/ {
proxy_pass http://127.0.0.1:25586/;
proxy_set_header Host $host;
}
/keystone set keystone.api.reachable-at keystone.tvujserver.eu
Nikdy nedávej api.address na veřejnou adresu bez TLS. Klíč jde v hlavičce a přes http:// po internetu ho přečte kdokoliv po cestě. A API umí všechno, co umí mod.
Živý proud
#curl -N -H "Authorization: Bearer ks_…" \
http://127.0.0.1:25586/v1/events
Drží spojení otevřené a píše do něj události, jak se dějí (text/event-stream). Tři řádky v prohlížeči:
const events = new EventSource('/v1/events');
events.onmessage = (e) => console.log(JSON.parse(e.data));
Ověřuje se jako všechno ostatní a bez klíče odpoví 404.
Stav a měření
#| Metoda | Cesta | Scope | K čemu |
|---|---|---|---|
GET |
/v1/status |
status.read |
Co tenhle server je a jak mu je |
GET |
/v1/metrics |
status.read |
Co dělá právě teď a poslední čtvrthodina |
GET |
/v1/metrics/history |
status.read |
Po minutách, tak daleko dozadu, jak to nastavení drží |
GET |
/v1/entities |
status.read |
Co je načtené ve světě a co by úklid teď sebral |
GET |
/v1/gate |
status.read |
Jestli je server otevřený a kolik míst se drží stranou |
GET |
/v1/catalog |
status.read |
Všechno, co tenhle pack načetl: registry, obsah jednoho (?of=minecraft:item, s from/limit/like), nebo jeho tagy (&tags=true) |
GET |
/v1/bench |
server.read |
Zátěžové běhy, které tenhle server udělal (?id= pro jeden celý) |
GET |
/v1/openapi.json |
status.read |
Tenhle dokument |
curl -sS -H "Authorization: Bearer ks_…" \
"http://127.0.0.1:25586/v1/catalog?of=minecraft:item&like=diamond&limit=20"
Lidi a oprávnění
#| Metoda | Cesta | Scope | K čemu |
|---|---|---|---|
GET |
/v1/players |
players.read |
Kdo je právě online |
GET |
/v1/progress |
players.read |
Co jeden hráč udělal, nebo žebříček jednoho počítadla |
GET |
/v1/skins |
players.read |
Co má kdo na sobě a odkud to je |
GET |
/v1/accounts |
players.read |
Kolik účtů má heslo a kdo čeká, až se prokáže |
GET |
/v1/bans |
players.read |
Každý ban, který ještě stojí |
GET |
/v1/tickets |
players.read |
Tickety (?id= pro jeden se vším, co se v něm řeklo, ?player=) |
GET |
/v1/votes |
players.read |
Hlasy, které serveru přišly, a jak je na tom party cíl (?player=, ?limit=) |
GET |
/v1/discord/links |
players.read |
Které herní účty má jeden Discord uživatel propojené (?discord=<id>) |
GET |
/v1/groups |
permissions.read |
Každá skupina oprávnění, nejtěžší první |
POST |
/v1/players/check |
permissions.read |
Jestli někdo něco smí — a které pravidlo o tom rozhodlo |
POST |
/v1/players/group |
permissions.write |
Dej někoho do skupiny, nebo mu v ní prodluž čas |
POST |
/v1/players/perk |
perks.write |
Dej někomu pojmenovanou výhodu, případně do data |
POST |
/v1/players/grants |
perks.read |
Co jeden hráč drží, odkud to má a kdy to končí |
Parametry:
| Cesta | Bere |
|---|---|
/v1/players/check |
player — jméno někoho online · permission — na které oprávnění se ptáš |
/v1/players/grants |
player — jméno někoho online |
/v1/players/group |
player · group — id skupiny · for — 30d, 12h, 90m, nebo vynech pro napořád · note — proč, pro toho, kdo to bude číst později |
/v1/players/perk |
player · perk — co dostane · for · note |
Jak z toho udělat obchod
#Na serveru, který není v online režimu, jméno napsané do formuláře nedokazuje nic. Pořadí je tohle:
# 1. Kdo je ten člověk ve hře — podle Discordu, kterým se přihlásil na webu
curl -sS -H "Authorization: Bearer ks_…" \
"http://127.0.0.1:25586/v1/discord/links?discord=123456789012345678"
# 2. Doruč mu, co si koupil, s datem konce
curl -sS -X POST -H "Authorization: Bearer ks_…" \
-d "player=Honza" -d "group=vip" -d "for=30d" -d "note=objednávka 4821" \
http://127.0.0.1:25586/v1/players/group
Hodnost skončí sama v ten den. Nikdo si nemusí pamatovat, že ji má sundat.
Provoz
#| Metoda | Cesta | Scope | K čemu |
|---|---|---|---|
GET |
/v1/operations |
operations.read |
Co je naplánované a kolik zbývá |
GET |
/v1/operations/history |
operations.read |
Co v poslední době proběhlo, nejnovější první |
POST |
/v1/operations/run |
operations.run |
Spusť jednu teď, nebo se zpožděním, s obvyklými varováními |
POST |
/v1/operations/cancel |
operations.run |
Odvolej, co je rozjeté, a vrať se k rozvrhu |
POST |
/v1/gate/maintenance |
operations.run |
Zavři server na údržbu, nebo ho zase otevři |
GET |
/v1/backups |
backup.read |
Každá záloha, nejnovější první, i s tím, co stojí na disku |
POST |
/v1/backups/restore |
backup.restore |
Vrať zálohu — připraví se a udělá při příštím startu |
Parametry:
| Cesta | Bere |
|---|---|
/v1/operations/run |
operation — která · in — za kolik vteřin, 0 hned |
/v1/operations/cancel |
operation — která |
/v1/gate/maintenance |
closed — true zavřít, false otevřít · reason — co se děje, uvidí to každý, kdo se pokusí připojit · until — kdy to má skončit, tvými slovy |
/v1/backups/restore |
backup — jméno zálohy, nebo cancel pro odvolání |
Nastavení a záznam
#| Metoda | Cesta | Scope | K čemu |
|---|---|---|---|
GET |
/v1/settings |
settings.read |
Každé nastavení, co který modul deklaroval, co to je a co v tom stojí |
POST |
/v1/settings |
settings.write |
Změň jedno. Odmítne se i s důvodem, když hodnota neodpovídá tomu, co ta věc je |
GET |
/v1/settings/history |
settings.read |
Každá změna, nejnovější první, i s tím, jaká byla hodnota předtím |
POST |
/v1/settings/rollback |
settings.write |
Vrať, co jedna verze změnila. Vrácení je samo verze, takže jde vrátit taky |
POST |
/v1/reload |
settings.write |
Přečti znovu všechny soubory s nastavením. Nic se nerestartuje a nikoho to nevyhodí |
GET |
/v1/audit |
audit.read |
Kdo co přes tohle rozhraní změnil, nejnovější první. Čtení se nezapisuje, změny a odmítnutí ano |
GET |
/v1/keys |
keys.read |
Klíče, které tenhle server vydal, bez jejich tajemství |
Parametry: /v1/settings bere setting (celé jméno, třeba operations.restart.when) a value; /v1/settings/rollback bere version.
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
Co všechno jde nastavit, je na stránce Všechna nastavení.
Konzole, chat a Discord
#| Metoda | Cesta | Scope | K čemu |
|---|---|---|---|
GET |
/v1/console |
console.read |
Poslední řádky, co server vypsal, nejstarší první. Drží se v paměti, ne v databázi |
GET |
/v1/chat |
chat.read |
Poslední, co padlo v chatu, nejstarší první |
GET |
/v1/events |
events.read |
Živý proud událostí |
GET |
/v1/discord |
server.read |
Jestli je most na Discord připojený a jak moc je pozadu |
Asistent
#| Metoda | Cesta | Scope | K čemu |
|---|---|---|---|
POST |
/v1/assistant/ask |
assistant.write |
Zeptej se ho. Odpověď přijde tímhle voláním |
POST |
/v1/assistant/incident |
assistant.write |
Podej mu poslední úsek konzole a chatu a zeptej se, co vypadá špatně |
POST |
/v1/assistant/decide |
assistant.write |
Souhlas s navrženou změnou, nebo ji nech být |
GET |
/v1/assistant/proposals |
assistant.read |
Změny, které chce udělat a nikdo o nich zatím nerozhodl |
GET |
/v1/assistant/threads |
assistant.read |
Konverzace, které byly, nejnovější první |
GET |
/v1/assistant/thread |
assistant.read |
Jedna konverzace, nejstarší zpráva první |
Parametry: /v1/assistant/ask bere question; /v1/assistant/decide bere proposal (která) a answer (yes nebo no).
Addony na JVM
#Když stavíš addon v Javě, přes HTTP nemluvíš. Kompiluješ proti keystone-api, který jede uvnitř toho samého jaru (META-INF/jarjar/eu.stygion.keystone.api-<verze>.jar) a nemá žádné vlastní závislosti, ani logovací. Registruje se přes něj vlastní modul, příkaz, oprávnění, zdroj hodností — a taky vlastní route, která pak vypadá v tomhle seznamu a v openapi.json úplně stejně jako ty naše.
Co se zapisuje
#Každá změna přes rozhraní je auditní řádek: který klíč, co, kdy — a každé odmítnutí taky. Klíč, který opakovaně zkouší, co nesmí, je jediná stopa, kterou o převzaté integraci dostaneš. Citlivé příkazy se maskují z auditu, konzole i logu.
Všechny cesty ve 0.3.0
#Vytažené z openapi.json serveru 0.3.0; popisy jsou ty, které mod u cesty deklaruje (anglicky). Sekce výš vysvětlují ty nejčastější.
| Metoda | Cesta | Scope | K čemu (text z modu) | Bere |
|---|---|---|---|---|
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 |
Pomohla vám tahle stránka?
Otevře panel zpětné vazby s touhle stránkou v příloze. Přistane do jedné fronty se vším ostatním.