FilePulse 本地 HTTP API

开发者 API

通过 FilePulse Web 界面正在使用的本地 HTTP API，让 AI、脚本、启动器和内部工具调用 FilePulse 的搜索与预览能力。

示例 Base URLhttp://127.0.0.1:80

示例使用 config_default.json 中的默认 HTTP 端口 80。实际部署时请以用户本机 config.json 中的端口为准。

从这里开始

鉴权流程

先探活，再登录获取 token，之后把返回的 token 直接放到 Authorization header。不要添加 Bearer 前缀。

01
GET/api/ver

探活并读取版本

返回 ver 和 plan。Online 版本还可能返回 uid 与 license_remaining_hours。这个接口不需要 token。

请求示例：/api/ver
curl http://127.0.0.1:80/api/ver
02
POST/api/login

创建访问 token

用 JSON 发送 username 和 password。响应里包含 server_name 与 access_token。

请求示例：/api/login
curl -X POST http://127.0.0.1:80/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"root","password":"root"}'
03
HEADERAuthorization: <access_token>

调用受保护 API

后续请求直接把 token 放到 Authorization header，也可以放到 Authorization 查询参数。

请求示例：Authorization: <access_token>
curl http://127.0.0.1:80/api/search_scope_targets \
  -H "Authorization: $FILEPULSE_TOKEN"

核心接口

常用公开端点

这些接口最适合 AI 辅助工作流：发现范围、搜索、预览、下载，并且只在用户确认后打开文件。

GET/api/search_scope_targets
Token

可搜索磁盘与范围

返回已经建立索引的搜索目标。需要限制搜索范围时，把返回的 drive index 放进 drive_scope。

关键字段

  • 返回的磁盘编号可传入 drive_scope.drive_indices。
  • AI 工作流如果要避开远程挂载目标，可使用 drive_scope.local_only。
请求示例：/api/search_scope_targets
curl http://127.0.0.1:80/api/search_scope_targets \
  -H "Authorization: $FILEPULSE_TOKEN"
POST/api/search
Token

文件名与路径搜索

按文件/文件夹元数据搜索，支持通配符或正则、过滤、排序和分页。

关键字段

  • mode: regex 或 wildcard
  • search_by: name 或 full_path
  • sort_by: name、full_path、size、modified 或 ext
  • kind: 0 表示文件和文件夹，1 表示文件夹，2 表示文件
  • pin_priority/use_groups 控制置顶优先级和分组行为
  • inline_icon.size 请求接口返回内联图标数据
  • start/end 是包含边界的结果下标
文件搜索示例
curl -X POST 'http://127.0.0.1:80/api/search' \
  -H 'Content-Type: application/json' \
  -H "Authorization: $FILEPULSE_TOKEN" \
  --data-raw '{
    "search_content": "a",
    "mode": "wildcard",
    "case_sensitive": false,
    "search_by": "name",
    "sort_by": "modified",
    "sort_asc": false,
    "content_plugin": [""],
    "kind": 0,
    "pin_priority": false,
    "use_groups": false,
    "start": 0,
    "end": 13,
    "inline_icon": {
      "size": 32
    }
  }'
POST/api/content_search
Token

全文内容搜索

搜索文档文本、OCR 文本和已配置内容处理器的索引内容。AI 需要命中上下文时建议开启 snippet。

关键字段

  • linear 为 false 时支持 regular、regex、prefix、fuzzy
  • linear 为 true 时支持 wildcard 与 regex 遍历模式
  • sort_by: none、file 或 score
  • file_search_condition 可复用 /api/search 的过滤条件
  • snippet 控制是否返回命中上下文
  • pin_priority/use_groups 控制置顶优先级和分组行为
  • inline_icon.size 请求接口返回内联图标数据
请求示例：/api/content_search
curl -X POST 'http://127.0.0.1:80/api/content_search' \
  -H 'Content-Type: application/json' \
  -H "Authorization: $FILEPULSE_TOKEN" \
  --data-raw '{
    "linear": false,
    "search_content": "a",
    "mode": "regular",
    "fuzzy_distance": 2,
    "score_top_k": 100,
    "sort_by": "score",
    "sort_asc": false,
    "snippet": false,
    "snippet_radius": 100,
    "pin_priority": false,
    "use_groups": false,
    "start": 0,
    "end": 13,
    "inline_icon": {
      "size": 32
    }
  }'
GET/api/visual_status
Token

视觉搜索状态

返回视觉搜索是否启用、索引进度、可搜索文件数、向量行数和 ffmpeg 可用性。

关键字段

  • 发送图片或视频查询前先检查 enabled 和 ready_files。
  • 可用 indexing/current_file_count/total_file_count 判断是否需要等待索引完成。
请求示例：/api/visual_status
curl http://127.0.0.1:80/api/visual_status \
  -H "Authorization: $FILEPULSE_TOKEN"
POST/api/visual_search
Token

图片与视频相似搜索

用 multipart form data 提交图片、截图、视频，或 FilePulse 主机上的绝对 query_path。

关键字段

  • 必须提供 file 或 query_path
  • drive_indices 接收 JSON 数组字符串
  • top_k 限制返回数量
  • fast_mode 用精度换速度
  • search_detail 和 min_match_count 可调视频匹配
请求示例：/api/visual_search
curl -X POST 'http://127.0.0.1:80/api/visual_search' \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -F 'file=@query.jpg' \
  -F 'top_k=20' \
  -F 'drive_indices=[0]' \
  -F 'fast_mode=true'
GET/api/download/{encodedPath}
Token

下载或预览文件

流式返回本机或代理文件路径。请把完整路径 URL encode 后放进路径，并携带 Authorization。底层文件服务支持 Range 请求。

关键字段

  • x-proxy 只用于已注册的远程 server_name。
  • 只接受文件路径；文件夹会返回错误。
请求示例：/api/download/{encodedPath}
curl 'http://127.0.0.1:80/api/download/D%3A%5Cdocs%5Creport.pdf' \
  -H "Authorization: $FILEPULSE_TOKEN" \
  --output report.pdf
POST/api/folder_preview
Token

预览文件夹子项

返回一个小型、排序后的文件夹列表，避免一次性拉取全部子项。

关键字段

  • path 必填
  • limit 默认 80，最大 200
  • 响应包含 total_children 和 truncated
请求示例：/api/folder_preview
curl -X POST http://127.0.0.1:80/api/folder_preview \
  -H "Content-Type: application/json" \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -d '{"path":"D:\\docs","limit":50}'
POST/api/content_match_preview
Token

预览内容命中上下文

为某条内容搜索结果获取 HTML/文本上下文，方便 AI 在要求打开文件前先检查命中位置。

关键字段

  • path、modified、search_content、mode 必填
  • linear 和 fuzzy_distance 应与原始内容搜索请求保持一致
请求示例：/api/content_match_preview
curl -X POST http://127.0.0.1:80/api/content_match_preview \
  -H "Content-Type: application/json" \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -d '{
    "path": "D:\\docs\\report.pdf",
    "modified": 1717113600,
    "search_content": "invoice",
    "mode": "regular",
    "linear": false,
    "fuzzy_distance": 2
  }'
POST/api/openfile
Token

在主机上打开文件

在 FilePulse 所在机器上启动文件或可执行程序。这个操作有副作用，AI 工具应该先让用户明确确认。

关键字段

  • path 必填
  • work_folder 可留空并自动推断父目录
  • admin 表示在支持的平台上尝试管理员权限启动
请求示例：/api/openfile
curl -X POST http://127.0.0.1:80/api/openfile \
  -H "Content-Type: application/json" \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -d '{"path":"D:\\docs\\report.pdf","work_folder":"","admin":false}'
POST/api/quick_launcher
Token

快速启动器搜索

搜索可启动应用、文件夹和快捷方式，请求体基本沿用 /api/search 的结构。

关键字段

  • 请求体遵循 SearchReqJson
  • 适合 AI 先定位应用或常用目录，再由用户确认是否启动。
请求示例：/api/quick_launcher
curl -X POST http://127.0.0.1:80/api/quick_launcher \
  -H "Content-Type: application/json" \
  -H "Authorization: $FILEPULSE_TOKEN" \
  -d '{
    "search_content": "chrome",
    "mode": "wildcard",
    "case_sensitive": false,
    "search_by": "full_path",
    "sort_by": "modified",
    "sort_asc": false,
    "content_plugin": [""],
    "kind": 0,
    "start": 0,
    "end": 9
  }'

AI 调用建议

推荐 AI 工作流

让模型保持在窄路径上：鉴权、搜索、检查，然后在打开或变更文件前请求用户确认。

ver
login
search / content_search / visual_search
preview / download
user-confirmed openfile

不要把密码长期交给模型

建议由用户或宿主程序提供短会话 token。不要把密码保存到模型记忆、长日志或可复用提示词里。

openfile 必须先确认

打开文件可能启动程序或暴露本地数据。AI 应该展示准确路径，并等待用户批准。

先请求小分页

建议先用 end 9 或 end 19，检查文件名和摘要，再按需请求更多结果。

本页不覆盖

高级与内部 API

下面这些接口有意不放进公开入门页，因为它们属于内部通信、破坏性操作、管理接口，或更适合单独写高级文档。

sync/**_internal配置写入分享配置LLM 配置重复文件清理upload
返回首页