aboutsummaryrefslogtreecommitdiff
path: root/castle-search/README.md
diff options
context:
space:
mode:
authorIgor Soarez <igor@soarez.org>2026-11-17 08:46:39 +0000
committerIgor Soarez <igor@soarez.org>2026-11-17 08:46:39 +0000
commit4c1f9b4ea943d03e9610f13344c372e630db5b9d (patch)
tree95bf9424161c98af6d384ecbc73379379373e546 /castle-search/README.md
parent561f0ee076c684a79fd5671af1bad0894f33e4de (diff)
castle-search: serve searches over HTTP for clients that are not pi
src/http.ts speaks Open WebUI's external web search protocol. A failed search answers 502 with its reason, never an empty list, so a captcha cannot pass for nothing found.
Diffstat (limited to 'castle-search/README.md')
-rw-r--r--castle-search/README.md18
1 files changed, 18 insertions, 0 deletions
diff --git a/castle-search/README.md b/castle-search/README.md
index f3fb5e9..7e4fd5c 100644
--- a/castle-search/README.md
+++ b/castle-search/README.md
@@ -29,6 +29,24 @@ the model picks.
It returns titles, URLs and snippets — **search results only**. It does not fetch
the linked pages; follow up with a read/fetch tool for full content.
+## Over HTTP, for clients that are not pi
+
+`src/http.ts` serves the same search as a small HTTP service, in Open WebUI's
+"external" web search protocol: POST `{"query": "...", "count": 5}` to `/`,
+get back `[{"link", "title", "snippet"}]`.
+
+```
+CCS_SEARCH_ENGINE=duckduckgo node --experimental-strip-types src/http.ts 127.0.0.1:11158
+```
+
+Engine and browser are chosen as for the pi tool. A failed search answers
+HTTP 502 with `{"error": "<why>"}`, never an empty list, so a captcha cannot
+pass for "nothing found"; zero hits is reported as an error too, since a
+rate-limited engine serves exactly that. The message adds that the caller cannot
+switch engines, because this protocol has no field for one. There is no
+authentication: bind it to loopback (the default) or a trusted address.
+`GET /health` answers `{"status": true}`.
+
## Engines
Four, with independent indexes and independent rate limits. That last part is