diff --git a/api-reference/agents.mdx b/api-reference/agents.mdx
index a3b58b7..0a11f87 100644
--- a/api-reference/agents.mdx
+++ b/api-reference/agents.mdx
@@ -82,7 +82,7 @@ Requires authentication and ownership of the agent.
 
 ## Delete agent
 
-<Warning>`DELETE /api/agents/:id` is deprecated. Use the lifecycle endpoints to manage agent state (for example, [`POST /api/instance/:userId/stop`](#stop-agent)).</Warning>
+<Warning>`DELETE /api/agents/:id` is deprecated. Use the lifecycle endpoints to manage agent state (for example, [`POST /api/agents/:id/stop`](#stop-agent)).</Warning>
 
 ## Provision agent
 
@@ -220,7 +220,7 @@ Requires authentication and ownership of the agent.
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `limit` | integer | 50 | Max log entries to return (max 100) |
-| `level` | string | — | Filter by log level (for example, `info`, `error`, `warn`) |
+| `level` | string | — | Filter by log level (for example, `info`, `error`, `warning`, `debug`) |
 
 ### Response
 
@@ -232,7 +232,7 @@ Requires authentication and ownership of the agent.
       "timestamp": "2026-03-19T00:00:00Z",
       "level": "info",
       "message": "Agent started successfully",
-      "source": "system",
+      "source": "agent",
       "agentId": "agent_123"
     }
   ],
@@ -278,6 +278,8 @@ GET /api/agents/:id/messages
 
 The `sender` field is either `user` or `agent`. The `platform` field indicates the messaging channel: `telegram`, `discord`, or `whatsapp`.
 
+<Note>The `total` field represents the current offset plus the number of messages returned, not the absolute total message count. Use it as a cursor for pagination.</Note>
+
 ## Get agent stats
 
 ```http
@@ -332,25 +334,25 @@ When the backend is unavailable, mock data is returned with `"status": "mock"`:
 
 ## Agent lifecycle
 
-Lifecycle operations use the `/api/instance/:userId` endpoint pattern. These endpoints require session authentication and proxy to the backend agent management service.
+Lifecycle operations use the `/api/agents/:id` endpoint pattern on the backend service. The web application proxies these requests via `/api/instance/:userId` routes, which forward to the backend. These endpoints require session authentication.
 
 ### Start agent
 
 ```http
-POST /api/instance/:userId/start
+POST /api/agents/:id/start
 ```
 
 ```json
 {
   "success": true,
-  "status": "running"
+  "status": "active"
 }
 ```
 
 ### Stop agent
 
 ```http
-POST /api/instance/:userId/stop
+POST /api/agents/:id/stop
 ```
 
 ```json
@@ -363,20 +365,25 @@ POST /api/instance/:userId/stop
 ### Restart agent
 
 ```http
-POST /api/instance/:userId/restart
+POST /api/agents/:id/restart
 ```
 
 ```json
 {
   "success": true,
-  "status": "running"
+  "status": "active",
+  "healedLegacyModel": false,
+  "healMessage": null,
+  "openclawVersion": "2026.3.13"
 }
 ```
 
+The `healedLegacyModel` field indicates whether a legacy model was automatically migrated during the restart. When `true`, `healMessage` contains a description of the migration.
+
 ### Update agent image
 
 ```http
-POST /api/instance/:userId/update
+POST /api/agents/:id/update
 ```
 
 Triggers an image update on the backend.
@@ -384,14 +391,18 @@ Triggers an image update on the backend.
 ```json
 {
   "success": true,
-  "status": "running"
+  "status": "active",
+  "image": "agentbot:2026.3.13",
+  "previousImage": "agentbot:2026.3.12",
+  "backupPath": "/backups/agent_123_1710806400",
+  "openclawVersion": "2026.3.13"
 }
 ```
 
 ### Repair agent
 
 ```http
-POST /api/instance/:userId/repair
+POST /api/agents/:id/repair
 ```
 
 Returns the backend response directly.
@@ -406,7 +417,7 @@ Returns the backend response directly.
 ### Reset agent memory
 
 ```http
-POST /api/instance/:userId/reset-memory
+POST /api/agents/:id/reset-memory
 ```
 
 Returns the backend response directly.
@@ -435,44 +446,48 @@ All lifecycle endpoints return the following shape on failure:
 | 502 | Backend service unavailable |
 | 500 | Internal server error |
 
-## Get instance details
+## Get agent details (backend)
 
 ```http
-GET /api/instance/:userId
+GET /api/agents/:id
 ```
 
-Returns the current status and metadata for an agent instance.
+Returns the current status and metadata for an agent from the backend service.
 
 ### Response
 
 ```json
 {
-  "userId": "user_123",
-  "status": "running",
+  "id": "agent_123",
+  "status": "active",
   "startedAt": "2026-03-01T00:00:00Z",
-  "subdomain": "user_123.agents.localhost",
-  "url": "https://user_123.agents.localhost",
+  "subdomain": "agent_123.agents.localhost",
+  "url": "https://agent_123.agents.localhost",
   "plan": "free",
-  "openclawVersion": "2026.2.17"
+  "openclawVersion": "2026.3.13",
+  "verified": false,
+  "verificationType": null,
+  "attestationUid": null,
+  "verifiedAt": null
 }
 ```
 
-## Get instance stats
+## Get agent stats (backend)
 
 ```http
-GET /api/instance/:userId/stats
+GET /api/agents/:id/stats
 ```
 
-Returns resource usage statistics for an agent instance.
+Returns resource usage statistics for an agent from the backend service.
 
 ### Response
 
 ```json
 {
-  "userId": "user_123",
+  "id": "agent_123",
   "cpu": "0.15%",
   "memory": "128MiB",
-  "status": "running",
+  "status": "active",
   "plan": "starter",
   "openclawVersion": "2026.3.13"
 }
@@ -481,7 +496,7 @@ Returns resource usage statistics for an agent instance.
 ## Get agent gateway token
 
 ```http
-GET /api/instance/:userId/token
+GET /api/agents/:id/token
 ```
 
 Returns an auto-generated gateway token for the agent. A new token is created if none exists.
@@ -506,7 +521,7 @@ Agents can be verified using multiple verification types: `eas` (Ethereum Attest
 ### Get verification status
 
 ```http
-GET /api/agents/:id/verify
+GET /api/agents/:id/verification
 ```
 
 ```json
@@ -596,12 +611,42 @@ The request is proxied to the backend provisioning service. A dedicated Mux live
 {
   "success": true,
   "userId": "a1b2c3d4e5",
+  "agentId": "agent_789",
+  "id": "agent_789",
+  "telegramToken": "***",
+  "discordToken": null,
+  "whatsappToken": null,
+  "aiProvider": "openrouter",
+  "aiProviderConfig": {},
+  "plan": "free",
+  "streamKey": "sk-ab12-cd34-ef56",
+  "liveStreamId": "x7k9m2p4q1",
+  "rtmpServer": "rtmps://global-live.mux.com:443/app",
+  "playbackUrl": "https://stream.mux.com/abc123.m3u8",
   "subdomain": "dj-a1b2c3d4e5.agentbot.raveculture.xyz",
   "url": "https://dj-a1b2c3d4e5.agentbot.raveculture.xyz",
-  "streamKey": "sk-ab12-cd34-ef56",
-  "liveStreamId": "x7k9m2p4q1"
-}
-```
+  "hls": "https://stream.mux.com/abc123.m3u8",
+  "rtmp": "rtmps://global-live.mux.com:443/app/sk-ab12-cd34-ef56",
+  "status": "active",
+  "createdAt": "2026-03-19T00:00:00Z",
+  "metadata": {}
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `agentId` | string | Unique agent identifier |
+| `id` | string | Alias for `agentId` |
+| `aiProvider` | string | AI provider used by the agent |
+| `aiProviderConfig` | object | Provider-specific configuration |
+| `plan` | string | Plan tier assigned to the agent |
+| `rtmpServer` | string | RTMP server URL for live streaming |
+| `playbackUrl` | string | HLS playback URL for the live stream |
+| `hls` | string | HLS stream URL |
+| `rtmp` | string | Full RTMP ingest URL including stream key |
+| `status` | string | Agent status after provisioning |
+| `createdAt` | string | ISO 8601 creation timestamp |
+| `metadata` | object | Additional metadata from the provisioning service |
 
 ### Errors
 
diff --git a/api-reference/ai.mdx b/api-reference/ai.mdx
index 36bb37d..0007d3c 100644
--- a/api-reference/ai.mdx
+++ b/api-reference/ai.mdx
@@ -61,7 +61,14 @@ Returns all available AI models across providers.
   "models": [
     {
       "id": "anthropic/claude-sonnet-4-20250514",
-      "provider": "openrouter"
+      "name": "Claude Sonnet",
+      "provider": "openrouter",
+      "description": "Fast, intelligent model for everyday tasks",
+      "tags": ["general", "coding"],
+      "inputCost": 3.0,
+      "outputCost": 15.0,
+      "contextWindow": 200000,
+      "available": true
     }
   ],
   "count": 1,
@@ -70,6 +77,20 @@ Returns all available AI models across providers.
 }
 ```
 
+Each model object includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Model identifier |
+| `name` | string | Human-readable model name |
+| `provider` | string | Provider serving the model |
+| `description` | string | Short description of the model |
+| `tags` | string[] | Task categories the model is suited for |
+| `inputCost` | number | Cost per million input tokens (USD) |
+| `outputCost` | number | Cost per million output tokens (USD) |
+| `contextWindow` | number | Maximum context length in tokens |
+| `available` | boolean | Whether the model is currently available |
+
 ### Errors
 
 | Code | Description |
@@ -99,6 +120,12 @@ GET /api/ai/models/:provider
 }
 ```
 
+### Errors
+
+| Code | Description |
+|------|-------------|
+| 500 | Failed to fetch models for provider |
+
 ## Select model
 
 ```http
@@ -119,7 +146,14 @@ Automatically selects the best model for a given task type.
 {
   "model": {
     "id": "anthropic/claude-sonnet-4-20250514",
-    "provider": "openrouter"
+    "name": "Claude Sonnet",
+    "provider": "openrouter",
+    "description": "Fast, intelligent model for everyday tasks",
+    "tags": ["general", "coding"],
+    "inputCost": 3.0,
+    "outputCost": 15.0,
+    "contextWindow": 200000,
+    "available": true
   },
   "taskType": "general",
   "timestamp": "2026-03-19T00:00:00Z"
@@ -131,6 +165,7 @@ Automatically selects the best model for a given task type.
 | Code | Description |
 |------|-------------|
 | 404 | No models available |
+| 500 | Internal server error |
 
 ## Chat completion
 
@@ -210,3 +245,4 @@ Estimate the cost of a request based on token counts and model pricing.
 | Code | Description |
 |------|-------------|
 | 400 | Model, inputTokens, and outputTokens are all required |
+| 500 | Internal server error |
diff --git a/api-reference/gateway.mdx b/api-reference/gateway.mdx
index 082887a..c98255d 100644
--- a/api-reference/gateway.mdx
+++ b/api-reference/gateway.mdx
@@ -137,7 +137,7 @@ When paid via MPP, the response includes a `Payment-Receipt` header and the `pay
 
 ## CORS
 
-The gateway supports CORS preflight via `OPTIONS /api/v1/gateway`. Allowed methods are `GET`, `POST`, and `OPTIONS`. The `Authorization`, `Content-Type`, `X-Plugin-Id`, and `X-Payment-Method` headers are permitted.
+The gateway supports CORS preflight via `OPTIONS /api/v1/gateway`. Allowed methods are `POST` and `OPTIONS`. The `Authorization`, `Content-Type`, `X-Plugin-Id`, and `X-Payment-Method` headers are permitted.
 
 ## Rate limits
 
diff --git a/api-reference/keys.mdx b/api-reference/keys.mdx
index 924e083..506faca 100644
--- a/api-reference/keys.mdx
+++ b/api-reference/keys.mdx
@@ -111,3 +111,4 @@ Requires ownership of the key.
 |------|-------------|
 | 401 | Unauthorized |
 | 404 | Key not found |
+| 500 | Internal server error |
diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx
index cb525ba..e62860d 100644
--- a/api-reference/overview.mdx
+++ b/api-reference/overview.mdx
@@ -39,7 +39,7 @@ API keys use the `sk_` prefix and are shown only once at creation time. See the
 | `/api/v1/gateway` | 100/min |
 | `/api/agents` | 100/min |
 | `/api/chat` | 60/min |
-| `/api/instance` | 30/min |
+| `/api/agents/:id/*` | 30/min |
 | `/api/provision` | Rate-limited per IP |
 | `/api/register` | Rate-limited per IP |
 | `/api/auth/forgot-password` | Rate-limited per IP |
@@ -93,18 +93,18 @@ API keys use the `sk_` prefix and are shown only once at creation time. See the
 | `/api/agents/:id/config` | PUT | Update agent configuration |
 | `/api/agents/:id/messages` | GET | Get agent messages |
 | `/api/agents/:id/stats` | GET | Get agent stats |
-| `/api/agents/:id/verify` | GET | Get verification status |
+| `/api/agents/:id/verification` | GET | Get verification status |
 | `/api/agents/:id/verify` | POST | Verify an agent |
 | `/api/agents/:id/verify` | DELETE | Remove verification |
-| `/api/instance/:userId` | GET | Get instance details |
-| `/api/instance/:userId/start` | POST | Start an agent |
-| `/api/instance/:userId/stop` | POST | Stop an agent |
-| `/api/instance/:userId/restart` | POST | Restart an agent |
-| `/api/instance/:userId/update` | POST | Update agent image |
-| `/api/instance/:userId/repair` | POST | Repair an agent |
-| `/api/instance/:userId/reset-memory` | POST | Reset agent memory |
-| `/api/instance/:userId/token` | GET | Get agent gateway token |
-| `/api/instance/:userId/stats` | GET | Get instance stats |
+| `/api/agents/:id` | GET | Get agent details (backend) |
+| `/api/agents/:id/start` | POST | Start an agent |
+| `/api/agents/:id/stop` | POST | Stop an agent |
+| `/api/agents/:id/restart` | POST | Restart an agent |
+| `/api/agents/:id/update` | POST | Update agent image |
+| `/api/agents/:id/repair` | POST | Repair an agent |
+| `/api/agents/:id/reset-memory` | POST | Reset agent memory |
+| `/api/agents/:id/token` | GET | Get agent gateway token |
+| `/api/agents/:id/stats` | GET | Get agent stats (backend) |
 | `/api/agents/provision` | POST | Provision a new agent |
 | `/api/agents/provision` | GET | List provisioned agents |
 | `/api/chat` | GET | List message history |
@@ -150,6 +150,7 @@ API keys use the `sk_` prefix and are shown only once at creation time. See the
 | `/api/stripe/checkout` | GET | Redirect to Stripe checkout (accepts `plan` query param: `solo`, `collective`, `label`, `network`) |
 | `/api/stripe/credits` | GET | Redirect to Stripe credit purchase (accepts `price` query param) |
 | `/api/stripe/storage-upgrade` | POST | Upgrade storage plan |
+| `/health` | GET | Health check (backend only, no `/api` prefix) |
 | `/api/metrics/:userId/historical` | GET | Get historical time-series metrics (backend only) |
 | `/api/metrics/:userId/performance` | GET | Get current performance metrics (backend only) |
 | `/api/metrics/:userId/summary` | GET | Get music industry metrics summary (backend only) |
diff --git a/api-reference/wallet.mdx b/api-reference/wallet.mdx
index 81437e3..56e8b7a 100644
--- a/api-reference/wallet.mdx
+++ b/api-reference/wallet.mdx
@@ -90,7 +90,14 @@ Creates a new wallet for the authenticated user.
 }
 ```
 
-Returns `400` if a wallet already exists.
+Returns `400` if a wallet already exists. The error response includes the existing wallet address:
+
+```json
+{
+  "error": "Wallet already exists",
+  "address": "0x..."
+}
+```
 
 ### Action: `get_seed`
 
@@ -193,7 +200,7 @@ Creates a new wallet using the Coinbase Developer Platform SDK.
 | Code | Description |
 |------|-------------|
 | 400 | Email required |
-| 500 | CDP not configured (set `CDP_PROJECT_ID` in environment) |
+| 500 | CDP not configured. Response includes `error` and `setup` fields: `{ "error": "CDP not configured", "setup": "Set CDP_PROJECT_ID in environment" }` |
 
 ## CDP wallet status