官方接口文档

POST/api/web/search

搜索网页并返回候选信息源。provider=auto 时先按 region 选择 CN / GLOBAL Route，再执行对应免费 Provider Chain。

请求参数

示例

curl -X POST 'http://localhost:8080/api/web/search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"OpenReach AI Agent","limit":5,"region":"US","provider":"auto","timeRange":"month"}'

响应字段：provider、query、region、timeRange、count、latencyMs、items[]。provider=auto 时响应仍为 auto，每个 item 的 source 表示具体结果渠道。

POST/api/web/image-search

根据文本搜索图片与来源页面。v0.1.4 会继续对原始 imageUrl 做公网 URL/重定向校验和真实图片字节探测，只把当前可直接下载的被动图片格式返回给调用方。

请求参数

示例

curl -X POST 'http://localhost:8080/api/web/image-search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"杭州西湖夜景","limit":8,"region":"auto","provider":"auto"}'

下载保证：返回的 imageUrl 已通过服务端即时下载探测；失效链接、403/404、HTML 防盗链页、伪图片以及 SVG 主动内容会被过滤。网络状态仍可能在响应之后变化，因此它表示“响应生成时可直接下载”。

验证边界：默认候选放大为 limit × 3，最多验证 60 个；单图验证超时 4 秒、最多 3 次跳转、读取最多 64 KiB，并发 6。支持 JPEG / PNG / GIF / WebP / BMP / TIFF / ICO / AVIF / HEIC 等被动图片签名。

响应 items 可包含：rank、title、imageUrl、thumbnailUrl、sourcePageUrl、provider、source、domain、width、height、imageFormat、license、licenseUrl。顶层 provider=auto 时仍返回 auto，具体图片渠道看 item 的 provider/source。

POST/api/web/read

获取公网文本网页并提取标题、正文、元数据和页面链接。读取链路包含 SSRF 防护、跳转限制、浏览器导航兼容请求头与瞬时 5xx 有界重试；不用于读取调用方内网附件、图片二进制或非 80/443 服务端口。

请求参数

示例

curl -X POST 'http://localhost:8080/api/web/read' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://spring.io/projects/spring-boot/","maxChars":20000}'

响应字段：url、finalUrl、title、content、contentType、reader、truncated、latencyMs、metadata、links。若公网目标明确返回 403/412/521 等状态，仍保持 HTTP 502 + UPSTREAM_ERROR 兼容，同时附加 failureType、upstreamStatus、retryable，便于 Agent 判断换源还是结束重试。

POST/api/web/curl

Safe Curl 用于读取公网 HTTP(S) 的 JSON、文本和源码内容，典型场景是 GitHub REST API、raw.githubusercontent.com、公开 OpenAPI/JSON/YAML 数据源。它不是 shell curl 透传，也不允许写请求。

请求参数

GitHub 源码读取示例

curl -X POST 'http://localhost:8080/api/web/curl' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://raw.githubusercontent.com/changluya/openreach/main/README.md","method":"GET","maxChars":100000}'

强制安全边界：目标 URL 每一跳都先执行 SSRF 校验；禁止 localhost、RFC1918/链路本地/保留地址、云 Metadata、非 80/443 端口，并额外禁止请求 OpenReach 自身。自请求识别会综合当前请求的 Host/serverName/localAddr、本机所有网卡地址以及 OPENREACH_CURL_BLOCKED_HOSTS 配置的额外域名/通配域名，防止该接口被用于回打自身管理面或爆破自身服务。

内容边界：只接收文本类响应（text/*、JSON、XML、JavaScript、YAML/TOML 等）；图片、压缩包、可执行文件等二进制内容直接拒绝。GitHub 私有仓库或需要登录/Token 的内容不应通过该接口获取。

响应字段：url、finalUrl、method、statusCode、contentType、body、truncated、redirects、latencyMs、headers。