Add support API and compatibility check endpoints

api-reference/support.mdx

@@ -0,0 +1,127 @@
+---
+title: Support API
+description: "Token auto-healing, diagnostics, and self-service support endpoints"
+---
+
+# Support API
+
+Self-service endpoints for diagnosing issues and automatically repairing gateway tokens. These endpoints help restore connectivity when tokens expire or go missing without requiring manual intervention.
+
+## Heal gateway token
+
+```http
+POST /api/support/heal-token
+```
+
+Requires session authentication. Automatically retrieves or generates a new gateway token for the authenticated user. The endpoint first checks for an existing user-specific token in the database and generates a new one if none is found.
+
+Gateway health is checked before token operations. If the gateway is degraded, the response still returns a valid token but includes the degraded health status.
+
+### Response (success)
+
+```json
+{
+  "healed": true,
+  "token": "a1b2c3d4e5f6...64-character-hex-string",
+  "isNew": true,
+  "health": {
+    "name": "OpenClaw Gateway",
+    "status": "ok",
+    "detail": null
+  },
+  "message": "New gateway token generated successfully"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `healed` | boolean | `true` when a valid token was returned |
+| `token` | string | The gateway token (64-character hex string). This is either an existing valid token or a newly generated one. |
+| `isNew` | boolean | `true` when a new token was generated, `false` when an existing token was returned |
+| `health` | object | Gateway health check result |
+| `health.name` | string | Service name (`OpenClaw Gateway`) |
+| `health.status` | string | Gateway health status: `ok`, `degraded`, or `down` |
+| `health.detail` | string \| null | Additional detail when the gateway is not healthy |
+| `message` | string | Human-readable description of the outcome |
+
+### Response (failure)
+
+```json
+{
+  "healed": false,
+  "message": "Failed to generate gateway token. Support has been alerted.",
+  "health": {
+    "name": "OpenClaw Gateway",
+    "status": "down",
+    "detail": "Connection refused"
+  }
+}
+```
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 401 | Unauthorized — missing or invalid session |
+| 500 | Token generation failed. An automatic support alert is sent when this occurs. |
+
+<Note>The dashboard calls this endpoint automatically on load when a gateway token is missing. You typically do not need to call this endpoint manually.</Note>
+
+---
+
+## Get diagnostics
+
+```http
+GET /api/support/diagnostics
+```
+
+Requires session authentication (email must be present). Returns a snapshot of platform health, active trial counts, recent agent errors, and gateway token status.
+
+### Response
+
+```json
+{
+  "serviceHealth": [
+    {
+      "name": "OpenClaw Gateway",
+      "status": "ok",
+      "detail": null
+    }
+  ],
+  "trialCount": 12,
+  "tokenStatus": "present",
+  "recentErrors": [
+    {
+      "id": "agent_abc",
+      "name": "My Agent",
+      "updatedAt": "2026-04-04T10:00:00.000Z",
+      "status": "error"
+    }
+  ],
+  "gatewayUrl": "https://openclaw-gw-ui-production.up.railway.app",
+  "timestamp": "2026-04-04T12:00:00.000Z"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `serviceHealth` | array | Health status of monitored backend services |
+| `serviceHealth[].name` | string | Service name |
+| `serviceHealth[].status` | string | Health status: `ok`, `degraded`, or `down` |
+| `serviceHealth[].detail` | string \| null | Error detail when the service is not healthy |
+| `trialCount` | number | Number of users currently on an active free trial |
+| `tokenStatus` | string | Gateway token status: `present` or `missing`. When `missing`, a support alert is sent automatically. |
+| `recentErrors` | array | Up to 5 most recently updated agents in `error` status |
+| `recentErrors[].id` | string | Agent identifier |
+| `recentErrors[].name` | string | Agent display name |
+| `recentErrors[].updatedAt` | string | ISO 8601 timestamp of the last status update |
+| `recentErrors[].status` | string | Agent status (always `error` in this list) |
+| `gatewayUrl` | string | The OpenClaw gateway URL used for health checks |
+| `timestamp` | string | ISO 8601 timestamp of the diagnostics snapshot |
+
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 401 | Unauthorized — missing or invalid session, or email not present |
+| 500 | Diagnostics query failed |