vite-press init

docs/en/reference/api.md

@@ -0,0 +1,44 @@
+# API Conventions
+
+Management API and Agent API both use JSON.
+
+## Response Shape
+
+Success and failure responses should include a clear `message`:
+
+```json
+{
+  "success": true,
+  "message": "",
+  "data": {}
+}
+```
+
+## Paths
+
+| Type | Convention |
+| --- | --- |
+| Management API | Authenticated by management Session |
+| Agent API | Fixed under `/api/agent/*` |
+| Read-only endpoints | `GET` |
+| Mutating endpoints | `POST` |
+
+## Authentication
+
+Management endpoints reuse the existing login, role, and Session system.
+
+Agent requests use the node-specific `agent_token`. First-time registration can use a global `discovery_token`. The header is:
+
+```http
+X-Agent-Token: <token>
+```
+
+Do not log full tokens.
+
+## Swagger
+
+After logging in:
+
+```text
+/swagger/index.html
+```