Hister API参考：add、search、history核心端点全解，快速对接你的私有搜索引擎
Hister API参考add、search、history核心端点全解快速对接你的私有搜索引擎【免费下载链接】histerYour own search engine项目地址: https://gitcode.com/GitHub_Trending/hi/histerHister是一款可自托管的「你自己的搜索引擎」它把浏览过的网页、本地文件、Mastodon 帖子等内容统一索引供你全文检索。除了 Web 界面和终端 TUIHister 还内置了一套简洁的 HTTPAPI——通过add、search、history这几个核心端点你可以把 Hister 快速接入自己的脚本、插件或 AI 助手。本文按端点逐一讲解请求方式、关键参数与典型用法帮你少走弯路。 Hister API 端点总览Hister 最棒的一点API 文档本身就是端点。请求GET /api会返回全部端点的 JSON 自描述文档无需依赖第三方文档站。端点定义集中注册在 api.go路由与鉴权封装在 endpoints.go。端点方法用途/apiGET返回完整 API 自描述文档JSON/api/addPOST添加并索引一篇文档/searchGET全文检索也支持 WebSocket 流式/suggestGETOpenSearch 输入建议/api/historyGET / POST读取 / 写入 / 删除浏览历史/api/history/timelineGET历史时间线聚合统计/api/documentGET按 URL 取回单篇文档/api/previewGET渲染文档预览/api/batchPOST一次执行最多 100 个批量操作/api/deletePOST按查询删除文档/api/labelPOST修改文档标签/api/rulesGET / POST跳过 / 优先 / 版本化规则/api/statsGET索引统计信息/api/login、/api/token-login、/api/logoutPOST会话认证/api/oauthGET启动 OAuth 登录流程/mcpPOSTMCP 协议端点AI 助手专用/healthGET健康检查➕ 端点一/api/add —— 添加文档这是 Hister 的入库入口提交一个 URLHister 负责抓取页面、运行提取器链、抽取正文并建立索引。POST/api/add支持application/x-www-form-urlencoded或application/json核心字段字段必填说明url✅要索引的文档 URLtitle❌文档标题缺省时从页面抽取text❌纯文本正文提供后会跳过服务端 HTML 抽取html❌原始 HTML由服务端抽取正文label❌用户自定义标签favicon❌Base64 编码的 faviconmetadata.ignore_skip_rules❌设为true可强制绕过 URL 跳过规则两种典型用法只传 URL让 Hister 自己抓取并抽取——这是默认行为传 URL text适合浏览器扩展等客户端直接推送已提取的纯文本服务端不再二次抓取。 老版本扩展还在调用/addPOST它仍是兼容路径但官方推荐改用/api/add。PDF 文件有专用端点POST /api/add_pdfdocument对象描述元信息pdf字段放 Base64 内容。 端点二/search —— 全文检索GET/search是 Hister API 的心脏。带q参数时直接返回 JSON 结果不带参数时它会升级为 WebSocket 连接持续推送结果——Web 界面的实时搜索框就是靠它实现的。常用查询参数参数说明q查询串支持完整查询语言过滤、sort:date等指令queryJSON 编码的 Query 对象q的替代方案date_from/date_to按更新时间过滤YYYY-MM-DDinclude_html0/1结果中附带原始 HTMLpage_key分页游标来自上一次响应的返回值sort排序建议直接在q里用sort:指令semantic0/1启用语义向量搜索semantic_threshold语义结果最低相似度分数q参数背后是 Hister 的查询语言这也是 API 威力最大的部分extractors domain:hister.org # 域名过滤 title:privacy policy # 精确短语 updated:90d # 90 天未更新的文档 label:research # 按标签检索 language:en # 按语言过滤 sort:-date # 按更新时间倒序完整语法参见官方文档 query-language.md。语义搜索能力取决于服务端是否配置了向量索引未配置时会自动回退为关键词搜索。 端点三/api/history —— 浏览历史历史体系是 Hister 的招牌功能它记录「你索引了什么」以及「你搜索、点开过什么」并可生成时间线视图。读取历史 —— GET/api/history常用参数参数说明openedtrue时返回搜索查询/点击历史否则返回最近索引的文档filter对标题或 URL 做不区分大小写过滤date_from/date_toUnix 时间戳区间过滤last/last_id/last_updated_at分页游标来自上次响应format设为rss时直接返回 RSS 2.0 订阅源写入历史 —— POST/api/historyJSON 字段包括字段说明url/title访问的页面query引导你到达该页面的搜索词pintrue/false置顶或取消置顶置顶项会作为优先结果参与搜索建议deletetrue时删除对应历史记录而非新增时间线聚合 —— GET/api/history/timeline返回按年/月/日分层的计数支持timezoneIANA 时区和date_from/date_to下钻是「历史时间线」页面的数据来源。 进阶端点速览POST /api/batch单次请求最多执行100 个add/delete/get操作请求体默认上限 40 MiB批量导入时的性能利器GET /api/document?url...按 URL 取回整篇已存文档URL 跨多个属主重复时用document_id精确指定GET /api/preview?url...返回可读渲染的预览可用extractor参数指定提取器GET /api/facets?q...不取文档只返回聚合统计域名、语言等切面计数POST /api/delete传入一个查询串即可删除所有匹配文档dry_run: true可先试算数量POST /api/update批量修改匹配文档的label、title、language、user_idGET /api/stats文档数、文件数、规则数等索引概览。 MCP 端点让 AI 助手用上你的搜索POST/mcp暴露了Model Context ProtocolJSON-RPC 2.0 / Streamable HTTP提供search、get_preview、get_history三个工具。接入后你的 AI 助手就能直接查询你的私有索引——包括语义搜索和日期范围过滤详见 mcp.md。所有工具返回的网页内容都会标记为untrusted客户端应做提示注入防护。 认证与 CSRF调用前的两件事访问令牌配置了app.access_token后所有受保护端点需携带Authorization: Bearer token或X-Access-Token请求头多用户模式下则在个人主页/profile生成专属令牌。开启app.public: true时标注为Public的端点/search、/api/preview、/api/stats等可匿名访问CSRF所有写操作add、delete、history写入等都带CSRFRequired标记需要有效会话/令牌保护。命令行脚本场景建议用静态访问令牌避免交互式 cookie。 三步开始部署Hister 提供 Docker 镜像与 Nix flake也可直接下载二进制配置文件见 configuration.md验证GET /health确认服务存活再请求GET /api拿到你本实例的端点清单试跑POST /api/addbody:{url:https://example.com}入库一篇文档GET /search?qexample验证可被搜到GET /api/history查看它出现在最近索引历史中。至此Hister API 的三大核心端点就全部跑通了。更多细节——每个参数、每种返回结构——都内置在服务里GET /api一键获取配合 api-docs 页面 的可视化呈现足以支撑绝大多数二次开发需求。【免费下载链接】histerYour own search engine项目地址: https://gitcode.com/GitHub_Trending/hi/hister创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考