HTTP API

The backend speaks two versions of its API. v2 streams the agent's work and is what the Allay plugin uses. v1 returns one JSON answer and stays for the archived Telegram bot and plugins before 2.0. The full contract is docs/protocol-v2.md; a Postman collection sits in postman.json.

Who pays: the headers

Every question carries one of these:

• Authorization: Bearer <license> for a subscription.
• X-Provider-Key: <key> plus a provider block in the body, for the server's own key.
• Nothing, on a self-hosted backend (SELFHOSTED=1).

See Who pays for the model.

v1: one JSON answer

POST /api/ask answers a question; POST /api/askx turns a request into commands. They run the same agent without game tools.

curl -X POST https://allay.chat/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "How do I craft a diamond pickaxe?", "platform": "telegram", "user_id": "42"}'

{"answer": "...", "status": "success", "timestamp": "...", "platform": "telegram", "user_id": "42"}

v2: a stream of events

The plugin opens one POST /api/v2/chat per question:

curl -N -X POST https://allay.chat/api/v2/chat \
  -H "Content-Type: application/json" -H "Accept: text/event-stream" \
  -d '{"mode": "ask", "message": "what should I do next?", "user_id": "5627dd98-...", "player": {"name": "Steve"}, "tools": ["get_inventory"]}'

The server answers with Server-Sent Events while the agent works:

1. start names the run and the model.
2. reasoning carries pieces of the model's reasoning, when the model exposes it.
3. tool_call asks the plugin to run a game tool, such as the inventory. The plugin posts the result to POST /api/v2/chat/{run_id}/tools/{call_id}.
4. tool_status tells what the agent does right now: reading the inventory, searching the web.
5. text streams the answer as it's written, then usage and done close the run.

For /askx, a commands event with the command list replaces the text. An error event ends a failed run.

mode is ask, askx, or task (a wake of an automation agent). visibility: "public" marks a question everyone online sees.

Other endpoints

Request	What it does
GET /api/health	The name, status, version, and whether billing is on
DELETE /api/v2/users/{user_id}/session	Clears the player's session; memories stay
GET, POST, DELETE /api/v2/users/{user_id}/memories	Lists, adds, or deletes all of the player's memories
DELETE /api/v2/users/{user_id}/memories/{id}	Deletes one memory
GET, POST /api/v2/license	A subscription's license and its status
POST /api/v2/admin/init	A one-time setup or recovery link for the admin panel
POST /api/telegram/webhook	The payment bot's updates
/api/admin/*	The admin panel's own API

Errors

Before a stream starts, errors come as { "error": { "code", "message" } } with an HTTP status. After it starts, they come as an error event. The codes are listed in Troubleshooting and in the protocol.

Next: Architecture