STYGION Dokumentace Hledat v dokumentaci

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čí.

Keystone 0.4.3 Aktualizováno 15 min čtení

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í
  1. Než něco zavoláš
  2. 1. Vyrob si klíč
  3. 2. Zavolej
  4. 3. Co znamenají odpovědi
  5. Kudy se k tomu dostaneš
  6. Jen z téhle mašiny (výchozí, a je to ta bezpečná volba)
  7. Z tvého počítače, přes tunel (doporučené u hostovaného serveru)
  8. Z domácí sítě
  9. Zvenčí, přes reverzní proxy nebo tunel
  10. Živý proud
  11. Stav a měření
  12. Lidi a oprávnění
  13. Jak z toho udělat obchod
  14. Provoz
  15. Nastavení a záznam
  16. Konzole, chat a Discord
  17. Asistent
  18. Addony na JVM
  19. Co se zapisuje
  20. 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íč

#
Kód
/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

#
Kód
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ář:

Kód
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)

#
Kód
[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ě:

Kód
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ě

#
Kód
/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:

Kód
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:

Kód
location /keystone/ {
    proxy_pass http://127.0.0.1:25586/;
    proxy_set_header Host $host;
}
Kód
/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

#
Kód
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:

Kód
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
Kód
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:

Kód
# 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.

Kód
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.