API 概述

Fess 提供的 API

本文档介绍 Fess 提供的 Web API（v2）。 通过使用 API，您可以在现有的 Web 系统或单页应用程序（SPA）等中，将 Fess 作为搜索服务器使用。

Note

Fess 15.7 中，API 已升级为 v2 版本。原有的 /api/v1 JSON 搜索 API 和聊天 API 已废弃，统一整合至 /api/v2。 使用 /api/v1 的客户端请迁移至 /api/v2。

基础 URL

Fess v2 API 端点的基础 URL 如下：

http://<Server Name>/api/v2/

例如，在本地环境中运行时，URL 如下：

http://localhost:8080/api/v2/

响应信封

v2 的所有 JSON 响应均以公共信封结构返回。

{
  "response": {
    "status": 0,
    ...
  }
}

response.status 表示处理结果，沿用了 v1 的规约。

status 的取值
0 成功
1 客户端错误
9 系统错误

表: status 的取值

注意，response.status >= 1 与 HTTP 状态码 400 以上始终一致。

字段名

包括请求体、响应体及 SSE 事件数据在内，所有 JSON 的键均统一使用 snake_case。

错误响应

发生错误时，信封中会附加 error 对象。

{
  "response": {
    "status": 1,
    "error": {
      "code": "invalid_request",
      "message": "..."
    }
  }
}
error 的元素
code 稳定的错误码（snake_case）。建议客户端基于此值进行本地化处理。
message 人类可读的错误消息（英语）。显示时请由客户端根据 code 进行本地化。
details 包含附加结构化信息的可选对象（可能省略）。仅部分端点包含此字段。例如，Health API 会在 error.details.engine 下嵌入搜索引擎集群快照。

表: error 的元素

错误码与 HTTP 状态码

error.code 对应的默认 HTTP 状态码如下。

错误码一览
error.code HTTP 状态码 说明
invalid_request 400 请求不合法。
auth_required 401 需要认证，或认证信息不正确。
forbidden 403 操作不被允许（如缺少或过期的 CSRF 令牌等）。
not_found 404 找不到资源。
method_not_allowed 405 不允许使用该 HTTP 方法。响应的 Allow 头中会列举支持的方法。
not_acceptable 406 无法接受的请求。
conflict 409 发生了资源冲突。
payload_too_large 413 请求体超过大小限制。
unsupported_media_type 415 不支持的 Content-Type（大多数端点要求 application/json）。
rate_limited 429 超过速率限制。Retry-After 头中会指示需要等待的秒数。
internal_error 500 服务器内部发生了错误。
service_unavailable 503 服务暂时不可用。

表: 错误码一览

Note

method_not_allowed 的响应中，会附带列举了支持 HTTP 方法的 Allow 头。

认证与会话

v2 API 采用基于会话的认证方式。 登录通过 POST /auth/login 完成，成功后将建立会话并颁发 CSRF 令牌。 当前认证状态可通过 GET /auth/me 查询。详情请参阅 认证与会话 API。

无需登录的搜索等端点可以匿名使用（取决于系统设置中的”需要登录”选项）。

CSRF 令牌

修改状态的请求（POST / PUT / DELETE）需要携带 X-Fess-CSRF-Token 头。 CSRF 令牌可通过以下方式获取：

  • POST /auth/login 响应中的 csrf_token 字段

  • GET /ui/config 响应（当 csrf_required=true 时的 csrf_token 字段）

令牌会在每次登录、注销或修改密码时轮换。

Note

CSRF 验证在认证 之前 执行。因此，既没有有效会话也没有有效 CSRF 令牌 的状态变更请求，会收到 403 forbidden，而非 401 auth_required。 /auth/login 因为在登录前令牌不存在，所以不在 CSRF 验证范围之内。

流式响应格式

部分端点以流式格式（而非普通 JSON）返回响应。

流式响应格式
端点 Content-Type 说明
/chat/stream text/event-stream Server-Sent Events（SSE）。详情请参阅 Chat API。
/documents/all application/x-ndjson NDJSON（每行为 {"data":{...}} 格式的一条文档。仅当流中途失败时，最后一行为 {"error":{...}}）。详情请参阅 搜索 API。

表: 流式响应格式

API 种类

Fess 提供以下 v2 API。

种类 主要端点 说明
search /search , /documents/all 用于搜索文档及全量获取（滚动）的 API。
label /labels 用于获取已配置标签列表的 API。
suggest /suggest-words 用于获取建议词的 API。
popularword /popular-words 用于获取热门词的 API。
related /related-queries , /related-content 用于获取相关查询及相关内容的 API。
health /health 用于获取搜索引擎集群状态的 API。
auth /auth/login , /auth/logout , /auth/me , /auth/password 用于认证与会话操作（登录、注销、获取认证状态、修改密码）的 API。
ui /ui/config 用于获取 SPA 所需初始配置（UI 配置）的 API。
favorite /favorites , /documents/{docId}/favorite 用于操作收藏文档的 API。
click /click 用于记录搜索结果点击的 API。
cache /cache/{docId} 用于获取缓存文档正文的 API。
chat /chat , /chat/stream 用于使用 AI 搜索模式（RAG 聊天）功能的 API。

表: API 种类