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

Source: https://stygion.eu/cs/docs/keystone/api-reference
Updated: 2026-10-25

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](#vsechny-cesty-ve-030).

---

## 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

```bash
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ář:

```bash
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)

```toml
[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ě:

```bash
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:

```bash
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:

```nginx
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

```bash
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:

```js
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 |

```bash
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:

```bash
# 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`.

```bash
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í](/docs/keystone/settings-reference).

## 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=<id>) | — |
| `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` |
