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

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

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](#every-route-in-030).

---

## Before you call anything

### 1. Make a key

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

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

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

```toml
[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.

### From your own computer, over a tunnel (recommended on a hosted server)

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

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

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

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

```nginx
location /keystone/ {
    proxy_pass http://127.0.0.1:25586/;
    proxy_set_header Host $host;
}
```

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

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

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

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

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

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

Everything there is to set is on [every setting](/docs/keystone/settings-reference).

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