Repository navigation
Plugin protocol
The plugin opens one streaming request per question. The backend agent (Mastra) streams back what it is doing, and when it needs to know something about the game it asks the plugin to run a tool and post the result back. Web search runs on the backend.
This page covers who is asking, the request, the stream, a dropped connection, tool results, and compatibility. The rest of the contract lives on its own pages:
- Client tools: the game tools the plugin runs, items, automation tools, and operator tools.
- Expansions and server tools: other plugins' tools and prompt lines, and the tools the backend runs itself.
- Automation agents and memory: agents' wakes, sessions, memories, and the player endpoints.
- Billing and the admin panel: BYOK, the subscription, licenses, paying, and the panel's first account.
HTTP API gives the short tour of every endpoint.
Server 6.0 keeps the paths and the bodies of v2 but breaks one thing on purpose: every request identifies its server. A plugin before 6.0 (Allay 5.x) gets 401 from a 6.0 backend until it sends the credentials below.
Since 6.0. Every endpoint below wants Authorization: Bearer …, except GET /api/health, POST /api/v2/license without a license, a player's copy by link (GET /api/v2/exports/{token}, since 6.9), and Telegram's webhook:
-
A hosted backend (billing on) wants the server's license,
<license id>.<secret>. A license only identifies: a server that brings its own key (BYOK) gets one free fromPOST /api/v2/licenseand sends it next toX-Provider-Key. Paying for it is what turns on the backend's own key. -
A self-hosted backend (
SELFHOSTED=1) wants itsPLUGIN_TOKEN, a secret of at least 24 characters the operator sets in the backend's environment and in the plugin'sserver.token. A backend without one answers no plugin at all (503 TOKEN_NOT_SET), never everyone.
| Code | Status | Meaning |
|---|---|---|
LICENSE_REQUIRED |
401 | A hosted backend got no Authorization (before 6.0: 402 without a key) |
LICENSE_INVALID |
401 | Unknown license, wrong secret, or a license the backend revoked after a refund |
TOKEN_REQUIRED |
401 | A self-hosted backend got no token |
TOKEN_INVALID |
401 | The token isn't the backend's PLUGIN_TOKEN
|
TOKEN_NOT_SET |
503 | The self-hosted backend has no PLUGIN_TOKEN of 24 characters or more |
The caller's tenant is license:<id> on a hosted backend and self on a self-hosted one. Every piece of player data is kept by tenant and user_id: a caller names any user_id it likes, but only ever reaches the players of its own tenant. The same Minecraft account on two servers is two players who never meet. Rate limits count per tenant, never per anything the body claims.
user_id is 1–64 letters, digits, -, or _ (a UUID, console). Anything else is 400.
POST /api/v2/chat
Headers: Content-Type: application/json, Accept: text/event-stream, X-Plugin-Version, Authorization (see Who is asking), and for the server's own key X-Provider-Key with a provider block (since 5.0, see Providers and billing). The v1 header X-OpenRouter-Token still works as such a key with the default models.
{
"mode": "ask", // "ask" answers a question; "askx" turns a request into commands; "task" wakes an automation agent (since 5.5)
"visibility": "private", // "public" when every player online sees the question and the answer (since 3.0)
"message": "what should I do next?", // ≤ 1000 chars for ask, ≤ 500 for askx, ≤ 2000 for task
"platform": "minecraft",
"user_id": "5627dd98-e6be-3c21-b8a8-e92344183641",
"locale": "ru_ru",
"timezone": "Europe/Moscow",
"player": { "name": "Steve", "uuid": "5627dd98-…", "op": false, "dimension": "the_nether", "position": { "x": -212, "y": 64, "z": 540, "dimension": "the_nether", "world": "world_nether" }, "game_mode": "survival" },
"server": { "id": "0f8c…", "software": "Paper", "version": "26.3", "plugin_version": "3.0.0", "loader": "spigot", "side": "server" },
"tools": ["get_player_status", "get_inventory", "get_surroundings", "look_at", "get_world", "get_statistics", "get_advancements", "get_recipes", "locate_structure", "get_server"]
}timezone is the asker's IANA time zone (optional, since 2.3). The backend puts their real date and time in front of each ask question, as [Mon, 12 Oct 2026, 23:42 Europe/Moscow] question, and keeps it in the session history. Without it the time is UTC.
visibility (since 3.0) is private by default. public marks a question from /askall or ? in chat mode: the plugin shows the question and the answer to every player online, the prompt tells the model so, and the run goes without write_book. askx is always private. A public question reads and extends the server's shared thread instead of the asker's session (see Conversation memory). server.id, a random id the plugin keeps for its server, names that thread within the caller's tenant (since 6.0: another server sending the same id reaches its own thread, not this one).
player.dimension (optional, since 5.1) is the dimension the player stood in when they asked: overworld, the_nether, or the_end. The prompt tells the model, so a place named without a dimension lands where the player is. Any other value is dropped.
server.address and server.port (optional, since 6.6) say where players join: the address the server's owner set in the plugin and the game port. The admin panel shows them with the address the request came from. A bad value is dropped, not refused.
server.loader and server.side (optional, since 6.12) say what Allay runs on and where. loader is spigot (the plugin for Bukkit, Spigot, Paper, and their forks), fabric, or neoforge. side is server for a dedicated server, integrated for the server inside a player's own game (a singleplayer world, or one opened to LAN), and client for a mod in the player's game on a server that runs no Allay. Without them a request counts as spigot on a server, as every plugin before 6.10 is. The prompt tells the model where it runs, and that a modded game has blocks and items the vanilla game doesn't. The admin panel shows both. Unknown values are dropped, not refused. PUT /api/v2/server and POST /api/v2/license take the same two.
server.about (optional, since 6.20) is what the server's operator wrote about it in the plugin's server.about: what the server is, its rules and places, and how they'd like Allay to talk with players. A question's prompt (mode ask) carries it under “About this server”, after the base prompt and the expansions' notes, framed so that Allay's own rules still come first. askx and automation agents don't get it. The backend trims it and reads at most 10,000 characters, cutting the rest rather than refusing the request. The plugin warns past 2,000, since every question pays for it. It isn't stored or shown in the admin panel.
player.position (optional, since 6.9) is where the player stands: whole x, y, z, a dimension as above, and the Bukkit world (≤ 64 chars). The backend measures distances and directions to remembered places and deaths from it, and the memories tool saves here there. A bad one is dropped, not refused.
player.game_mode (optional, since 6.33) is survival, creative, adventure, or spectator. The prompt's Player line names it, so the model never asks a player in creative for blocks. One the backend doesn't know is dropped.
Every request through OpenRouter carries provider: { data_collection: "deny" } since 6.9, so OpenRouter routes it only to providers that don't store or train on it (OPENROUTER_DATA_COLLECTION=allow lifts that).
building (optional, since 6.33, plugin 6.37) is { "max_blocks"?, "max_size"?, "data_version"? }: the biggest build the player may build on this server, its longest side, and the server's game. search_schematics keeps to them; the model can't lift them.
player.private (optional, since 6.5) is true while the player has full privacy on. The backend then keeps no name, UUID, or operator status for the admin panel and forgets what it had, so the panel knows the player by pseudonym only. Memories, the session, and traces work as before.
tools lists the client tools this plugin offers (server admins can switch some off). The backend registers only those for this run. The plugin lists operator tools only when the asking player is an operator, and the backend drops them anyway when player.op is false. An askx run gets only the tools that read the game: no actions (point_to, show_marks, reminders, goals, books, automations) and no operator tools. Since 6.16 it finds the player's memories but never changes them. Since 5.5 the backend also sorts the automation tools by mode (see Automation agents): ask keeps start_task, message_task, and cancel_task and drops the ones only agents use, and a public ask drops those three too.
tasks (optional, since 5.5) lists the asker's running automations, at most 8 since 6.22 (4 before, and a newer plugin then sends the newest 4 again when the backend refuses more): [{ "id": "k3f9", "name": "Furnaces", "state": "working" | "waiting" | "asking", "question"?: "≤ 200 chars" }]. id is [a-z0-9]{1,16}, name ≤ 40 chars, question what a task in state asking asked the player. Since plugin 5.14, asking means the agent showed buttons or a picking mode, said a line with a question mark, or said a line with no job and no sub-agent left to wake it. A line said while a job runs (“smelting takes 3 minutes”) leaves it waiting. Its question stays until the player answers ([player], [button], or the end of picking), so a [job] or [timer] wake in between doesn't drop it. The prompt shows them to the model as data, so it can pass a free-text answer on with message_task. Since 5.10.1, task mode takes it too: there it lists the waking agent's own running sub-agents, so the agent never claims an ended one still works. askx ignores it.
expansion_tools and expansions (optional, since 6.14, from plugin 6.12) carry what other plugins and mods add through Allay's expansion API (chat.allay:allay-expansion): see Expansions. task mode ignores both.
task (required with mode: "task", since 5.5) names the automation agent the run wakes: { "id": "k3f9", "name": "Сортировка сундуков", "depth": 1 | 2, "kind": "chests" | "furnaces" | "brewing" | "crafting" | "building" }, with the same limits on id and name. A task run is always private, and ask and askx ignore the field. Since 6.22 a kind this backend doesn't know answers TASK_KIND_UNKNOWN (400) instead of BAD_REQUEST, so a newer plugin can tell the player the backend needs an update. Before, it was BAD_REQUEST with a message about task.kind, which plugin 6.22 reads the same way. Since plugin 6.22 a task's id is six characters and never names another task while the server runs.
Content-Type: text/event-stream. Every event is event: <name> + data: <json>. A : ping comment goes out every 15 s.
| Event | Data | Meaning |
|---|---|---|
start |
{ "run_id": "uuid", "model": "…" } |
The run began. run_id addresses tool results |
reasoning |
{ "delta": "…" } |
A piece of the model's reasoning, when the model exposes it |
tool_call |
{ "call_id": "…", "name": "get_inventory", "args": { … } } |
The plugin must run this client tool and post the result |
tool_status |
{ "call_id": "…", "name": "search_web", "kind": "client" | "server", "state": "started" | "finished" | "failed", "args": { … }, "summary": "5 sources", "summary_key"?: "sources", "summary_values"?: { "count": 5 } } |
Progress of any tool, for display. Client tools get started right before tool_call. Since 2.4, server tools add summary_key and summary_values so the plugin can show the summary in the player's language, and summary stays in English |
text |
{ "delta": "…" } |
A piece of the answer, in & codes (see Answer text below). In task mode, a piece of the agent's note to itself: don't show it |
commands |
{ "is_sequence": true, "commands": ["give @s diamond_sword 1"] } |
askx only: the commands to run (≤ 12, no leading slash) |
usage |
{ "input_tokens": 0, "output_tokens": 0, "reasoning_tokens": 0, "cost": 0.0 } |
Totals for the run so far: sent after every model step and once more, final, right before done. Each one replaces the last |
done |
{ "answer": "full text", "duration_ms": 5321 } |
The run finished. For askx answer may be a short note, for task it is the agent's note to itself, often empty |
error |
{ "code": "AI_REQUEST_FAILED", "message": "…" } |
The run failed, and the stream ends after it. Codes stay compatible with v1 (QUESTION_TOO_LONG, NETWORK_ERROR, …) plus TOOL_TIMEOUT, RUN_NOT_FOUND
|
Since backend 6.18, when the plugin offers search_commands (plugin 6.16), an askx run checks the model's commands before it sends commands: the backend calls search_commands with { "check": ["sethome base", …] } (no leading slash, as the model wrote them) as an ordinary tool_call. The plugin answers { "checks": [{ "command", "ok": bool, "error"?, "source"?, "usage"? }] } in the same order: ok is false for a command this server doesn't have (the error names close ones), one the player may not run, one in blocked_commands, or, in the mods, arguments the game can't parse. A hidden plugin's command reads as unknown. When any isn't ok, the backend gives the model the reasons once, and sends whatever it answers then. The plugin checks again before it runs anything: unless every command exists and is the player's, nothing runs and the player hears why. A failed check call (an older plugin, a timeout) sends the commands as before.
The answer is Minecraft text: & codes and button tags, never Markdown. Since server 6.18.2 the backend turns any Markdown the model slips into codes before text, done, and the session get it, and does the same to say's text and finish's summary: **x** and __x__ become &lx&r, *x* and _x_ &ox&r, a # heading a bold line. Backticks and code fences go. After the &r the color the line had comes back. Stars and underscores inside words, around spaces, or around a possible player name (_Steve_) stay, as do button tags and links. So that a ** split over two deltas still pairs up, text arrives by whole lines in Minecraft runs, the last piece of a step when it ends. Joined, the deltas are done's answer.
Since server 6.11 the model writes buttons straight into the answer text, and the plugin (Allay 6.9 or newer) turns each into a clickable [Label] in place when it shows the finished answer. The tool that put buttons under the answer is gone, with no fallback: older plugins show the tags as text. The backend passes the tags through untouched in text and done.
<button action="ACTION" attr="value" …>Label</button>
- The label is the element's text: a word or two, at most 24 characters, in the answer's language, with no tags or line breaks inside.
- Attribute values go in double quotes.
",&,<, and>are the only escapes. - At most 8 buttons in one answer, anywhere in it: mid-sentence, at the end of a line, or on a line of their own.
- A tag the plugin can't use (an unknown action, a missing attribute, a recipe that doesn't exist, a player not on the locator bar) shows as its plain label without a click. The model gets no error back.
action |
Attributes | The click | In a public answer |
|---|---|---|---|
ask |
question (≤ 200) |
Asks Allay that question, as if typed | Yes: asks everyone again |
point |
x, z, y?, dimension? |
A trail and the compass to the spot | Yes |
point |
player: an exact name on the clicker's locator bar |
A trail that follows that player | Yes |
copy |
text (≤ 200), such as -20 95 120
|
Puts the text into the clipboard | Yes |
note |
text (≤ 200), x, z, y?, dimension? |
Saves a memory with that place | Yes |
recipe |
item |
The recipe window | Yes |
brewing |
potion, form? (potion, splash_potion, lingering_potion) |
The brewing steps window | Yes |
anvil |
slots? (inventory slots 0–35, comma separated) |
The anvil plan for the item in hand | The asker only |
enchants |
– | The enchanting window for the item in hand | Yes |
villagers |
item? |
The villagers around and their trades | Yes |
command |
command, starting with /
|
Runs it as the player who clicks, minus the plugin's blocked_commands
|
Never: private answers only |
say |
text (≤ 256) |
Sends the text to the public chat as the player who clicks, as if typed | Never: private answers only |
dimension is overworld, the_nether, or the_end, and x, y, and z are integers. Books (write_book) and automation agents' say keep their own buttons.
Since 6.31 a plugin that sends request_id (8–64 letters, digits, -, or _, the same on every try of one question) gets a run that outlives its connection. Each event then comes with id: <n>, counting from 1.
-
Reading on. When the connection drops, the run goes on and waits up to
RUN_DETACH_SECONDS(240) for the plugin.GET /api/v2/chat/{run_id}/eventswithLast-Event-ID: <n>streams every event aftern, then the rest live. A second reader replaces the first. While nobody reads, client calls' timeouts stop, and each unanswered call gets its whole timeout again once the plugin is back. -
Asking again. A
POST /api/v2/chatwith arequest_idwhose run still runs or just ended reads that run from the start, or fromLast-Event-ID: one question never runs or pays twice, even when its first answer never arrived. -
After the end. A finished run's events stay for
RUN_LINGER_SECONDS(120), so a plugin that lost the last of them still readsdone. -
Cancelling. Closing the connection no longer stops such a run.
DELETE /api/v2/chat/{run_id}stops it at once:200 { "cancelled": true }. -
Answers.
404 RUN_NOT_FOUNDfor a run that's unknown, over and gone, or another tenant's.410 RUN_GONEwhen the run kept more thanRUN_JOURNAL_BYTESsinceLast-Event-ID, so the plugin can only ask again.
Without request_id a run stops with its connection, as before.
POST /api/v2/chat/{run_id}/tools/{call_id} with
{ "ok": true, "result": { … } }
{ "ok": false, "error": "player is offline" }with the same Authorization as the question. Since 6.24 either may add "timing": { "queued_ms": 3, "run_ms": 12 }: how long the tool waited for the server thread and then ran there, for the run's trace. The backend drops a timing it can't read rather than refuse the answer. Answers: 200 { "accepted": true }, 401 without credentials, 404 unknown or finished run or call, or another tenant's run (since 6.0), 409 already answered. The backend waits up to 15 s per client call. Past that the model gets an error result and the run goes on. A plugin that posts again after a dropped connection takes 409 as delivered.
POST /api/ask and POST /api/askx keep their v1 request and response shapes, and since 6.0 want the same Authorization as v2 and a user_id of letters, digits, -, or _ when they send one. They run the same agent without client tools.
GET /api/health answers { "name": "Allay", "status": "ok", "version", "billing", "policy_revision" }. Since 6.0 it says nothing about the process, and since 6.9 the privacy policy's revision.
| Plugin | Server before 6.0 | Server 6.0 |
|---|---|---|
| Allay 5.x | Works |
401 everywhere: it sends no token, and a BYOK server sends no license |
| Allay 6.0 | Works, and a self-hosted backend ignores the token | Works |
Since server 6.11 buttons come inline in the answer text (see Buttons in the answer) and the tool that put buttons under the answer is gone. Allay 6.8 and older keep working against it, but show the tags as text. Allay 6.9 or newer is needed for buttons.
Since server 6.9 the backend keeps what the plugin kept on disk. Allay 6.6 and older keep working against it: their own death history and their files stay as they were until the plugin updates, but since 6.16 the model no longer gets their notes tool. Allay 6.7 needs server 6.9: against an older backend its deaths, state, and export link answer 404, and it keeps them in memory only.
Since server 6.31 a run with a request_id outlives a dropped connection (see A dropped connection). Allay 6.34 and older send none, and their runs stop with the connection, as before. Allay 6.35 against an older backend sees no event ids and asks again from the start when the connection drops before the answer began.
Next: Client tools