From 9acd3f3d7665af06ae336118aefd549969735eec Mon Sep 17 00:00:00 2001
From: syntaxbullet <syntaxbullet@protonmail.com>
Date: Sun, 8 Feb 2026 16:41:31 +0100
Subject: [PATCH] docs: add API reference documentation

---
 docs/api.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)
 create mode 100644 docs/api.md

diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..c5c4a6f
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,141 @@
+# Aurora API Reference
+
+REST API server for Aurora bot management. Base URL: `http://localhost:3000`
+
+## Health
+
+### `GET /api/health`
+Returns server health status.
+
+**Response:** `{ "status": "ok", "timestamp": 1234567890 }`
+
+---
+
+## Items
+
+### `GET /api/items`
+List all items with optional filtering.
+
+| Query Param | Type | Description |
+|-------------|------|-------------|
+| `search` | string | Filter by name/description |
+| `type` | string | Filter by item type |
+| `rarity` | string | Filter by rarity (C, R, SR, SSR) |
+| `limit` | number | Max results (default: 100) |
+| `offset` | number | Pagination offset |
+
+**Response:** `{ "items": [...], "total": number }`
+
+### `GET /api/items/:id`
+Get single item by ID.
+
+### `POST /api/items`
+Create new item. Supports JSON or multipart/form-data with image.
+
+**Body (JSON):**
+```json
+{
+  "name": "Health Potion",
+  "description": "Restores HP",
+  "type": "CONSUMABLE",
+  "rarity": "C",
+  "price": "100",
+  "usageData": { "consume": true, "effects": [] }
+}
+```
+
+### `PUT /api/items/:id`
+Update existing item.
+
+### `DELETE /api/items/:id`
+Delete item and associated asset.
+
+### `POST /api/items/:id/icon`
+Upload/replace item image. Accepts multipart/form-data with `image` field.
+
+---
+
+## Quests
+
+### `GET /api/quests`
+List all quests.
+
+### `POST /api/quests`
+Create new quest.
+
+**Body:**
+```json
+{
+  "name": "Daily Login",
+  "description": "Login once",
+  "triggerEvent": "login",
+  "target": 1,
+  "xpReward": 50,
+  "balanceReward": 100
+}
+```
+
+### `PUT /api/quests/:id`
+Update quest.
+
+### `DELETE /api/quests/:id`
+Delete quest.
+
+---
+
+## Settings
+
+### `GET /api/settings`
+Get current bot configuration.
+
+### `POST /api/settings`
+Update configuration (partial merge supported).
+
+### `GET /api/settings/meta`
+Get Discord metadata (roles, channels, commands).
+
+---
+
+## Admin Actions
+
+### `POST /api/actions/reload-commands`
+Reload bot slash commands.
+
+### `POST /api/actions/clear-cache`
+Clear internal caches.
+
+### `POST /api/actions/maintenance-mode`
+Toggle maintenance mode.
+
+**Body:** `{ "enabled": true, "reason": "Updating..." }`
+
+---
+
+## Stats
+
+### `GET /api/stats`
+Get full dashboard statistics.
+
+### `GET /api/stats/activity`
+Get activity aggregation (cached 5 min).
+
+---
+
+## Assets
+
+### `GET /assets/items/:filename`
+Serve item images. Cached 24 hours.
+
+---
+
+## WebSocket
+
+### `ws://localhost:3000/ws`
+Real-time dashboard updates.
+
+**Messages:**
+- `STATS_UPDATE` - Periodic stats broadcast (every 5s when clients connected)
+- `NEW_EVENT` - Real-time system events
+- `PING/PONG` - Heartbeat
+
+**Limits:** Max 10 concurrent connections, 16KB max payload, 60s idle timeout.