Align API specs with current backend behavior

api-reference/agents.mdx

@@ -17,7 +17,7 @@ Create, manage, and interact with agents.
 GET /api/agents
 ```
 
-Returns all agents owned by the authenticated user. When no session is present, returns an empty list instead of a `401` error.
+Returns all agents owned by the authenticated user. The web proxy returns an empty list when no session is present. The backend returns `401` when the bearer token is missing and `403` when it is invalid.
 
 ### Response (backend)
 
@@ -133,6 +133,8 @@ GET /api/agents/:id
 
 Requires authentication and ownership of the agent.
 
+<Note>Ownership is enforced only when the agent's `ownerEmail` field is populated. Agents created before ownership tracking was added (or without an authenticated session) may not have `ownerEmail` set, in which case any authenticated user can access the agent.</Note>
+
 ### Response (backend)
 
 The backend returns the agent object directly without a wrapper:
@@ -1188,10 +1190,10 @@ POST /api/agents/:id/verify
 |-------|------|----------|-------------|
 | `verificationType` | string | Yes | One of: `eas`, `coinbase`, `ens`, `webauthn` |
 | `attestationUid` | string | Conditional | Attestation UID from EAS. Required when `verificationType` is `eas`. |
-| `walletAddress` | string | Conditional | Address of the verifying wallet. Required when `verificationType` is `ens`. Optional for `coinbase`. |
-| `signature` | string | Conditional | Cryptographic signature or attestation data. Required when `verificationType` is `coinbase`, `ens`, or `webauthn`. |
+| `walletAddress` | string | Conditional | Address of the verifying wallet. Required when `verificationType` is `ens`. Optional for `coinbase`. **Web proxy only** — this field is not recognized by the backend. |
+| `signature` | string | Conditional | Cryptographic signature or attestation data. Required when `verificationType` is `coinbase`, `ens`, or `webauthn`. **Web proxy only** — this field is not recognized by the backend. |
 
-<Note>The web API always sets `verified: true` on success and computes the `verifierAddress` and `metadata` fields internally based on the verification type. When calling the backend directly, you can pass `verified`, `verifierAddress`, and `metadata` explicitly — see the additional backend parameters below.</Note>
+<Note>The `walletAddress` and `signature` fields are accepted and validated by the web proxy only. The backend does not read these fields. When calling the backend directly, pass `verificationType`, `verified`, `attestationUid`, `verifierAddress`, and `metadata` directly — see the additional backend parameters below.</Note>
 
 #### Additional backend parameters
 
@@ -1575,7 +1577,7 @@ When the backend path succeeds and `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET` are con
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `telegramToken` | string | Conditional | Telegram bot token. At least one channel token is required unless `autoProvision` is `true` or `agentType` is `business`. |
-| `telegramUserId` | string | No | Telegram user ID for owner binding |
+| `telegramUserId` | string | No | Telegram user ID for owner binding. This field is accepted by the backend but is not currently used in the backend provisioning logic. The web proxy may use it for Telegram owner binding. |
 | `whatsappToken` | string | Conditional | WhatsApp API token. At least one channel token is required unless `autoProvision` is `true` or `agentType` is `business`. |
 | `discordBotToken` | string | Conditional | Discord bot token. At least one channel token is required unless `autoProvision` is `true` or `agentType` is `business`. |
 | `aiProvider` | string | No | AI provider (default: `openrouter`). Options: `openrouter`, `gemini`, `groq`, `anthropic`, `openai`. Each provider maps to a default model — see [AI provider defaults](#ai-provider-defaults) below. |
@@ -1715,12 +1717,12 @@ When calling the backend provisioning service directly, the response includes ad
 | 400 | Invalid plan value (backend only). The `plan` field must be one of `solo`, `collective`, `label`, or `network`. The web proxy defaults to `label` when forwarding to the backend, so this error is only returned when calling the backend directly with an unrecognized value. Since the `plan` field defaults to `free` when omitted, and `free` is not a valid plan, callers must always specify an explicit paid plan. The error message is: `Invalid plan. Supported: solo, collective, label, network`. |
 | 401 | Authentication required. Returned when no valid session is present, or the session email does not match a configured admin email. The body `email` field is not used for authentication. |
 | 403 | Active subscription required (web proxy). Returned when the authenticated user does not have an active subscription and is not an admin. The response body includes `success: false` and an `error` message: `Active subscription required. Please purchase a plan to deploy.` |
-| 402 | No free tier available. Returned when `plan` is `free` (the default when omitted). The response body includes `code: "PAYMENT_REQUIRED"` and the message `"No free tier. Choose a paid plan to get started."` You must explicitly specify a paid plan (`solo`, `collective`, `label`, or `network`). |
+| 402 | **Deprecated (unreachable).** The intent was to return this status when `plan` is `free`, but the `400` plan validation catches `free` first because it is not in the valid plan list. In practice, omitting `plan` (which defaults to `free`) returns `400` with message `"Invalid plan. Supported: solo, collective, label, network"`. |
 | 402 | Active subscription required (backend). Returned when a valid paid plan is specified but no Stripe subscription ID is provided and the caller is not an admin. The response body includes `code: "PAYMENT_REQUIRED"` and `success: false`. |
 | 402 | Agent limit reached for your plan. The response body includes a `code` field set to `AGENT_LIMIT_REACHED`, along with `current` (current agent count) and `limit` (maximum allowed) fields. Provisioning limits: `solo` 1, `collective` 3, `label` 10, `network` unlimited. |
 | 500 | Internal server error |
 | 502 | Provisioning service unavailable. All backend URLs failed or returned non-JSON/error responses, and Railway direct provisioning also failed or is not configured. The error message from the last attempted path is included in the response. |
-| 503 | Provisioning is temporarily disabled (kill switch active) or provisioning service misconfigured. |
+| 503 | Provisioning is temporarily disabled (kill switch active) or provisioning service misconfigured. Response body: `{ "success": false, "error": "Provisioning is temporarily disabled. Contact support." }` |
 
 ### AI provider defaults
 
@@ -1765,7 +1767,7 @@ Every new user instance is provisioned with a complete configuration template. T
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `agents.defaults.workspace` | `/home/node/.openclaw/workspace` | Path to the agent's workspace directory inside the container |
-| `agents.defaults.model.primary` | `openrouter/xiaomi/mimo-v2-pro` | Primary AI model used for completions |
+| `agents.defaults.model.primary` | Varies by provider (see [container config models](#container-config-models)) | Primary AI model used for completions. Defaults to `moonshotai/kimi-k2.5` for the `openrouter` provider, `google/gemini-2.0-flash` for `gemini`, `groq/gemma2-9b-it` for `groq`, `anthropic/claude-sonnet-4-5` for `anthropic`, and `openai/gpt-4o` for `openai`. |
 | `agents.defaults.heartbeat.every` | `30m` | Heartbeat interval (30 minutes) |
 | `agents.defaults.heartbeat.lightContext` | `true` | Use lightweight context during heartbeat checks to reduce token usage |
 | `agents.defaults.heartbeat.isolatedSession` | `true` | Run heartbeat checks in an isolated session to avoid polluting conversation state |
@@ -1794,6 +1796,8 @@ All channels are pre-configured at provisioning time. Webchat is enabled by defa
 | `whatsapp` | `false` | `pairing` |
 | `webchat` | `true` | — |
 
+<Note>The table above describes the web proxy (Railway direct) provisioning path. The backend provisioning path behaves differently: when a channel token is provided, the channel is set to `enabled: true`; when no token is provided, the channel entry is omitted entirely from the configuration rather than being set to `enabled: false`.</Note>
+
 ### Cron defaults
 
 Cron is enabled by default on all new instances with the following limits:
@@ -1821,7 +1825,7 @@ Sessions use per-sender scoping with automatic daily resets:
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `tools.profile` | `coding` | Tool profile applied to the agent (includes shell commands, code execution) |
+| `tools.profile` | `coding` (or `messaging` for Solo plan) | Tool profile applied to the agent. Defaults to `messaging` for Solo plan agents and `coding` for all other plans (Collective, Label, Network). See [tool profiles](#tool-profiles). |
 | `tools.exec.backgroundMs` | `10000` | Maximum time in milliseconds for background execution tasks |
 | `tools.exec.timeoutSec` | `1800` | Maximum execution timeout in seconds (30 minutes) |
 | `tools.web.search.enabled` | `true` | Web search tool is available to the agent |

api-reference/ai.mdx

@@ -19,6 +19,8 @@ GET /api/ai/health
 
 Requires bearer token authentication. Returns the availability status of configured AI providers.
 
+<Note>The `/health`, `/models`, and `/models/:provider` endpoints were originally designed to be public (as indicated by source code comments), but mount-level authentication on the `/api/ai` router requires a bearer token for all requests. If you need unauthenticated model discovery, use the OpenAI-compatible `/v1/models` endpoint instead.</Note>
+
 ### Response
 
 ```json

api-reference/registration.mdx

@@ -84,9 +84,9 @@ Validates a bearer token by computing a SHA-256 hash of the raw key and looking
 POST /api/register-home
 ```
 
-Registers a Home mode installation. Requires identity headers (`x-user-email`, `x-user-id`, `x-user-role`) set by the authenticated frontend. The backend middleware extracts these headers but does not independently verify a bearer token on this route.
+Registers a Home mode installation. Requires identity headers (`x-user-email`, `x-user-id`, `x-user-role`) set by the authenticated frontend.
 
-<Note>The web proxy forwards identity headers from the active session. The backend `authenticate` middleware reads these headers and attaches them to the request context. If no headers are provided, `userId` defaults to `anonymous`.</Note>
+<Note>The registration routes use a different authentication middleware (header-based identity) than the API key authentication used by routes like `/api/agents` or `/api/deployments`. This middleware reads identity headers (`x-user-email`, `x-user-id`, `x-user-role`) from the request and attaches them to the request context. If no headers are provided, `userId` defaults to `anonymous`. The web proxy forwards these headers from the active session.</Note>
 
 ### Request body
 

api-reference/team-provisioning.mdx

@@ -121,7 +121,7 @@ The total number of custom agents must not exceed the plan's agent limit. If `cu
 GET /api/provision/team/templates
 ```
 
-Returns all available pre-built team templates and their categories. This endpoint does not apply authentication middleware at the route level. Authentication may be enforced at the application mount level depending on your deployment configuration.
+Returns all available pre-built team templates and their categories. Authentication is enforced at the application mount level. All requests must include a valid `Authorization: Bearer <token>` header.
 
 ### Response
 

docs.json

@@ -211,5 +211,4 @@
       "href": "https://agentbot.raveculture.xyz/signup"
     }
   }
-}Added channels to Getting Started
-Added channels to Integrations
+}