From 76e9ecb5f23de714f6a3c717ef200c2be8084210 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 4 Apr 2026 04:49:20 +0000 Subject: [PATCH] Add support API docs and ensure-compatibility endpoint for token auto-healing Generated-By: mintlify-agent --- api-reference/maintenance.mdx | 37 ++++++++++ api-reference/overview.mdx | 3 + api-reference/support.mdx | 127 ++++++++++++++++++++++++++++++++++ docs.json | 3 +- troubleshooting.mdx | 26 +++++++ 5 files changed, 195 insertions(+), 1 deletion(-) create mode 100644 api-reference/support.mdx diff --git a/api-reference/maintenance.mdx b/api-reference/maintenance.mdx index f77b232..747421d 100644 --- a/api-reference/maintenance.mdx +++ b/api-reference/maintenance.mdx @@ -232,6 +232,43 @@ When a restart or factory reset fails: Factory reset pins the agent to the platform's configured default image. After a factory reset, you can update to a newer version later through the normal update flow. +## Ensure OpenClaw compatibility + +```http +POST /api/openclaw/ensure-compatibility +``` + +Requires session authentication. Checks whether the authenticated user's OpenClaw setup is compatible with the current platform version (2026.4.2) and automatically applies any required fixes. This includes plugin configuration migration, agent pairing scope corrections, and gateway token generation. + +### Response + +```json +{ + "compatible": true, + "fixes": ["migrated_plugin_config", "fixed_pairing_scope"], + "errors": [], + "message": "Applied 2 compatibility fixes" +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `compatible` | boolean | `true` when the setup is compatible (either already compatible or all fixes were applied successfully) | +| `fixes` | string[] | List of fixes that were applied. Empty when no fixes were needed. | +| `errors` | string[] | List of errors encountered during compatibility checks. Empty on success. | +| `message` | string | Human-readable summary of the result | + +### Errors + +| Code | Description | +|------|-------------| +| 401 | Unauthorized — missing or invalid session | +| 500 | Internal error during compatibility check | + +This endpoint is idempotent. Calling it multiple times on an already-compatible setup returns `compatible: true` with an empty `fixes` array and the message "No fixes needed". + +--- + ## OpenClaw runtime version ```http diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx index 121c2c3..0f1aacb 100644 --- a/api-reference/overview.mdx +++ b/api-reference/overview.mdx @@ -291,6 +291,9 @@ curl -X POST https://agentbot.sh/api/ai/chat \ | `/api/version` | GET | Get platform version (no auth) | | `/api/openclaw/maintenance` | GET | Get agent health status (liveness and readiness) | | `/api/openclaw/maintenance` | POST | Restart agent container (runs doctor and migrations on startup) | +| `/api/openclaw/ensure-compatibility` | POST | Check and fix OpenClaw 2026.4.2 compatibility (session auth) | +| `/api/support/heal-token` | POST | Auto-heal (regenerate) gateway tokens (session auth) | +| `/api/support/diagnostics` | GET | Platform diagnostics snapshot (session auth) | | `/api/openclaw-version` | GET | Get OpenClaw runtime version (web proxy, fallback `2026.4.2`) | | `/api/openclaw/version` | GET | Get OpenClaw runtime version (backend only) | | `/api/openclaw/instances` | GET | List running agent instances (backend only, requires auth) | diff --git a/api-reference/support.mdx b/api-reference/support.mdx new file mode 100644 index 0000000..28c4a6b --- /dev/null +++ b/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. | + +The dashboard calls this endpoint automatically on load when a gateway token is missing. You typically do not need to call this endpoint manually. + +--- + +## 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 | diff --git a/docs.json b/docs.json index 5bda1bf..95ea31b 100644 --- a/docs.json +++ b/docs.json @@ -144,7 +144,8 @@ "api-reference/admin-summary", "api-reference/export", "api-reference/wallet-monitor", - "api-reference/market-intel" + "api-reference/market-intel", + "api-reference/support" ] }, { diff --git a/troubleshooting.mdx b/troubleshooting.mdx index 5b6f875..cdab466 100644 --- a/troubleshooting.mdx +++ b/troubleshooting.mdx @@ -134,6 +134,32 @@ Skills are loaded at agent startup. If a skill fails to load, the agent will sta + + +Gateway tokens are now auto-healed. When you open the dashboard, the system checks for a valid gateway token and generates a new one automatically if it is missing or expired. No manual refresh is required. + +If auto-healing does not resolve the issue, you can trigger it manually: + +```http +POST /api/support/heal-token +``` + +This returns a new token and updates the Control UI URL. See the [support API](/api-reference/support#heal-gateway-token) for details. + +To check overall platform health and token status, use the diagnostics endpoint: + +```http +GET /api/support/diagnostics +``` + +If you recently updated to OpenClaw 2026.4.2, run the compatibility check to apply any required migrations: + +```http +POST /api/openclaw/ensure-compatibility +``` + + + ## Billing Issues