diff --git a/docs.json b/docs.json
index 7eca5601..62707301 100644
--- a/docs.json
+++ b/docs.json
@@ -115,7 +115,8 @@
"introduction/create",
"introduction/control",
"introduction/observe",
- "introduction/scale"
+ "introduction/scale",
+ "search"
]
},
{
diff --git a/reference/cli.mdx b/reference/cli.mdx
index a5a61e8c..7ad72b9b 100644
--- a/reference/cli.mdx
+++ b/reference/cli.mdx
@@ -4,6 +4,8 @@ title: "Kernel CLI"
The Kernel CLI helps you access and manage your Kernel resources.
+For web search from your terminal, use the [Search API examples](/search). CLI releases that include Search also support `kernel search`; otherwise, use the HTTP examples.
+
## Installation
```bash
diff --git a/reference/mcp-server/tools/search-docs.mdx b/reference/mcp-server/tools/search-docs.mdx
index 91789e46..56d04da4 100644
--- a/reference/mcp-server/tools/search-docs.mdx
+++ b/reference/mcp-server/tools/search-docs.mdx
@@ -5,6 +5,10 @@ description: "Search Kernel platform documentation and guides"
Search Kernel platform documentation for guides, tutorials, and API references. Use it when you need to understand how Kernel features work or to troubleshoot issues.
+
+This tool searches Kernel documentation, not the web. The [Search API](/search) is a separate HTTP API; web search support depends on the hosted MCP server release and your organization's Search access. When available, the `web_search` tool is exposed from the Search entitlement. MCP entitlement snapshots are cached per credential and connection for up to 30 minutes; the Search API remains authoritative when a search runs.
+
+
## Parameters
| Parameter | Description |
diff --git a/search.mdx b/search.mdx
new file mode 100644
index 00000000..bbed7535
--- /dev/null
+++ b/search.mdx
@@ -0,0 +1,97 @@
+---
+title: "Search"
+description: "Search the web through Kernel's HTTP API and discover provider capabilities."
+---
+
+Search the web with `POST /search`. Kernel routes your query to a configured search provider and returns normalized results, provider attempt history, and warnings.
+
+
+Search requires access to be enabled for your organization. A `404` with code `search_disabled` means your organization doesn't have access. Contact Kernel to request access. Provider availability depends on the service configuration.
+
+
+## Run a search
+
+Create an [API key](/info/api-keys) and set `KERNEL_API_KEY` in your environment. These examples use HTTP directly, so they don't require a particular Kernel SDK version.
+
+
+```bash cURL
+curl --fail-with-body https://api.onkernel.com/search \
+ -H "Authorization: Bearer $KERNEL_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"query":"Playwright browser automation","max_results":5}'
+```
+
+```typescript TypeScript
+const response = await fetch("https://api.onkernel.com/search", {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${process.env.KERNEL_API_KEY}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ query: "Playwright browser automation",
+ max_results: 5,
+ }),
+});
+if (!response.ok) throw new Error(await response.text());
+const search = await response.json();
+console.log(search.results);
+console.log(search.warnings);
+```
+
+```python Python
+import json
+import os
+from urllib.request import Request, urlopen
+
+request = Request(
+ "https://api.onkernel.com/search",
+ data=json.dumps({
+ "query": "Playwright browser automation",
+ "max_results": 5,
+ }).encode(),
+ headers={
+ "Authorization": f"Bearer {os.environ['KERNEL_API_KEY']}",
+ "Content-Type": "application/json",
+ },
+ method="POST",
+)
+with urlopen(request) as response:
+ search = json.load(response)
+print(search["results"])
+print(search["warnings"])
+```
+
+
+If your installed CLI release includes Search, the equivalent command is:
+
+```bash
+kernel search "Playwright browser automation" --max-results 5
+```
+
+Inspect `results` for ranked URLs, titles, and descriptions. Check `warnings` for parameters that were approximated or omitted, and `attempts` for provider execution history. Save the response if you need it beyond its `expires_at` timestamp; `GET /search/{id}` retrieves retained results, not a fresh search.
+
+## Discover providers and filters
+
+Use discovery rather than assuming a provider is available:
+
+```bash
+curl --fail-with-body https://api.onkernel.com/search/providers \
+ -H "Authorization: Bearer $KERNEL_API_KEY"
+```
+
+The response describes configured providers, their filter and content capabilities, and provider-native option schemas. Omitting `strategy` uses automatic routing, which is the recommended default. Provider-specific strategies and native options are advanced features; review the applicable provider availability and terms before using them.
+
+Portable parameters include `max_results`, `country`, `language`, `include_domains`, `exclude_domains`, `recency`, `start_date`, `end_date`, and `safe_search`. Support varies by provider. Set `strict_params: true` when supplied portable parameters must be honored exactly; otherwise, inspect warnings for unsupported or approximated values. Domain and safety filters aren't authorization boundaries.
+
+## Content retrieval limits
+
+Some providers support inline content. Check provider discovery before requesting it. Don't assume a result includes full page text or that every provider supports the same content options.
+
+Deferred retrieval through `POST /search/{id}/contents` isn't available yet and returns `404`. Its presence in the API schema doesn't indicate that it is ready to use.
+
+## CLI and MCP access
+
+The current released Kernel CLI might not include `kernel search` yet. If your installed release includes it, use the CLI example above; otherwise, use the HTTP examples with an API key. `kernel login` isn't required for HTTP requests.
+
+The hosted Kernel MCP server exposes [`search_docs`](/reference/mcp-server/tools/search-docs) for Kernel documentation. Web Search API support is a separate MCP capability and depends on the server release and your organization's Search access. In releases that include it, `web_search` appears only when the Search entitlement is enabled. The MCP server checks entitlements when listing tools or calling an entitlement-gated tool and caches the snapshot per credential and connection for up to 30 minutes. The Search API remains authoritative when a search runs, so visibility can lag an entitlement change within an existing connection.