From 31d535c4b00e3fbb060383a8dcce004e9eeed992 Mon Sep 17 00:00:00 2001 From: chruffins <23645059+chruffins@users.noreply.github.com> Date: Tue, 22 Sep 2026 16:02:40 +0000 Subject: [PATCH 1/6] Document Search API usage and client availability --- docs.json | 3 +- reference/cli.mdx | 2 + reference/mcp-server/tools/search-docs.mdx | 4 + search.mdx | 91 ++++++++++++++++++++++ 4 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 search.mdx 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..ae401d8b 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's cURL examples](/search). The released CLI doesn't yet include a `kernel search` command. + ## Installation ```bash diff --git a/reference/mcp-server/tools/search-docs.mdx b/reference/mcp-server/tools/search-docs.mdx index 91789e46..0682e8f8 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 and isn't yet exposed by the hosted MCP server. + + ## Parameters | Parameter | Description | diff --git a/search.mdx b/search.mdx new file mode 100644 index 00000000..2bc61990 --- /dev/null +++ b/search.mdx @@ -0,0 +1,91 @@ +--- +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"]) +``` + + +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. You can also select a pinned provider or an ordered fallback strategy; see the Search endpoints in the **API Reference** tab for request schemas. + +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 released Kernel CLI doesn't yet provide a `kernel search` command. Use the cURL examples above from your terminal with an API key; `kernel login` isn't required for these HTTP requests. + +The hosted Kernel MCP server doesn't yet expose the web Search API as a tool. Its [`search_docs`](/reference/mcp-server/tools/search-docs) tool searches Kernel documentation only. Installing MCP configuration with [`kernel mcp install`](/reference/cli/mcp) doesn't add web search support. From d0fd34499ca8517489cc2e20eca3fa11aa4c43b1 Mon Sep 17 00:00:00 2001 From: chruffins <23645059+chruffins@users.noreply.github.com> Date: Tue, 22 Sep 2026 19:58:09 +0000 Subject: [PATCH 2/6] Clarify search client availability --- reference/cli.mdx | 2 +- reference/mcp-server/tools/search-docs.mdx | 2 +- search.mdx | 10 ++++++++-- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/reference/cli.mdx b/reference/cli.mdx index ae401d8b..7ad72b9b 100644 --- a/reference/cli.mdx +++ b/reference/cli.mdx @@ -4,7 +4,7 @@ title: "Kernel CLI" The Kernel CLI helps you access and manage your Kernel resources. -For web search from your terminal, use the [Search API's cURL examples](/search). The released CLI doesn't yet include a `kernel search` command. +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 diff --git a/reference/mcp-server/tools/search-docs.mdx b/reference/mcp-server/tools/search-docs.mdx index 0682e8f8..a47fb232 100644 --- a/reference/mcp-server/tools/search-docs.mdx +++ b/reference/mcp-server/tools/search-docs.mdx @@ -6,7 +6,7 @@ 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 and isn't yet exposed by the hosted MCP server. +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. ## Parameters diff --git a/search.mdx b/search.mdx index 2bc61990..240efcb7 100644 --- a/search.mdx +++ b/search.mdx @@ -63,6 +63,12 @@ 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 @@ -86,6 +92,6 @@ Deferred retrieval through `POST /search/{id}/contents` isn't available yet and ## CLI and MCP access -The released Kernel CLI doesn't yet provide a `kernel search` command. Use the cURL examples above from your terminal with an API key; `kernel login` isn't required for these HTTP requests. +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 doesn't yet expose the web Search API as a tool. Its [`search_docs`](/reference/mcp-server/tools/search-docs) tool searches Kernel documentation only. Installing MCP configuration with [`kernel mcp install`](/reference/cli/mcp) doesn't add web search support. +The hosted Kernel MCP server currently 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. From a325ab2d28bcc846ef720db2a8a5e5735d2b2c65 Mon Sep 17 00:00:00 2001 From: chruffins <23645059+chruffins@users.noreply.github.com> Date: Tue, 22 Sep 2026 20:06:21 +0000 Subject: [PATCH 3/6] Use provider-neutral search examples --- search.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/search.mdx b/search.mdx index 240efcb7..b9d652c0 100644 --- a/search.mdx +++ b/search.mdx @@ -80,7 +80,7 @@ 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. You can also select a pinned provider or an ordered fallback strategy; see the Search endpoints in the **API Reference** tab for request schemas. +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. From 4ea7f8590cb270f45957fb36d20090872e5e275f Mon Sep 17 00:00:00 2001 From: chruffins <23645059+chruffins@users.noreply.github.com> Date: Thu, 24 Sep 2026 19:25:22 +0000 Subject: [PATCH 4/6] Document MCP Search entitlement caching --- reference/mcp-server/tools/search-docs.mdx | 2 +- search.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/mcp-server/tools/search-docs.mdx b/reference/mcp-server/tools/search-docs.mdx index a47fb232..56d04da4 100644 --- a/reference/mcp-server/tools/search-docs.mdx +++ b/reference/mcp-server/tools/search-docs.mdx @@ -6,7 +6,7 @@ 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. +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 diff --git a/search.mdx b/search.mdx index b9d652c0..bbed7535 100644 --- a/search.mdx +++ b/search.mdx @@ -94,4 +94,4 @@ Deferred retrieval through `POST /search/{id}/contents` isn't available yet and 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 currently 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. +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. From 7f4723cac1e053aace3d55110aea13b4912db5db Mon Sep 17 00:00:00 2001 From: chruffins <23645059+chruffins@users.noreply.github.com> Date: Fri, 25 Sep 2026 18:19:23 +0000 Subject: [PATCH 5/6] Hide internal Search endpoints in API reference --- search-api-overlay.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 search-api-overlay.yaml diff --git a/search-api-overlay.yaml b/search-api-overlay.yaml new file mode 100644 index 00000000..c6875014 --- /dev/null +++ b/search-api-overlay.yaml @@ -0,0 +1,14 @@ +overlay: 1.0.0 +info: + title: Hide internal Search API endpoints from the public reference + version: 1.0.0 +extends: https://api.onkernel.com/spec.json +actions: + - target: $.paths['/search'] + remove: true + - target: $.paths['/search/{id}'] + remove: true + - target: $.paths['/search/{id}/contents'] + remove: true + - target: $.paths['/search/providers'] + remove: true From 98ce61c6def6c6bc7dfdaf5c3f50a962435f5af5 Mon Sep 17 00:00:00 2001 From: chruffins <23645059+chruffins@users.noreply.github.com> Date: Fri, 25 Sep 2026 19:28:20 +0000 Subject: [PATCH 6/6] Revert "Hide internal Search endpoints in API reference" This reverts commit 7f4723cac1e053aace3d55110aea13b4912db5db. --- search-api-overlay.yaml | 14 -------------- 1 file changed, 14 deletions(-) delete mode 100644 search-api-overlay.yaml diff --git a/search-api-overlay.yaml b/search-api-overlay.yaml deleted file mode 100644 index c6875014..00000000 --- a/search-api-overlay.yaml +++ /dev/null @@ -1,14 +0,0 @@ -overlay: 1.0.0 -info: - title: Hide internal Search API endpoints from the public reference - version: 1.0.0 -extends: https://api.onkernel.com/spec.json -actions: - - target: $.paths['/search'] - remove: true - - target: $.paths['/search/{id}'] - remove: true - - target: $.paths['/search/{id}/contents'] - remove: true - - target: $.paths['/search/providers'] - remove: true