跳到主要内容

本地 API

基础信息​

服务默认端口说明
分享服务8721健康检查、配对、文件下载
API 服务8722/api/v1/ 路由前缀

鉴权​

  • 本地请求免鉴权 — Host 为 127.0.0.1 / localhost / [::1] 时跳过 Bearer 校验
  • 远程请求需令牌 — Authorization: Bearer <api_key>

API Key 在应用「配置中心」查看，为 64 位十六进制随机串。

为什么本地免鉴权

员工本地调用是主要场景，要求每次带令牌会大幅提高上手成本。远程访问才需要鉴权保护。

错误响应​

所有错误统一格式：

{
  "error": "error_code",
  "message": "中文描述"
}
HTTPerror场景
400bad_request参数错误、文件不存在、base64 解码失败
401auth_failed非本地请求且 API Key 无效
404not_found分享/队列项不存在

健康检查​

GET /health​

无需鉴权。返回应用信息与配对码。

{
  "app": "sidekick-desktop",
  "version": "1.0.0.0",
  "status": "ok",
  "pairing_code": "123456"
}

状态​

GET /api/v1/status​

{
  "version": "1.0.0.0",
  "share_port": 8721,
  "api_port": 8722,
  "share_count": 3,
  "hotkey_installed": true,
  "hotkey_last_trigger": 1729584000,
  "hotkey_last_result": "已发完 2 条，耗时 1700ms",
  "foreground_im": "微信 4.x",
  "foreground_window": "Qt51514QWindowIcon | 微信 | Weixin"
}

hotkey_* 字段用于诊断快捷键是否触发、发送结果如何。

队列​

POST /api/v1/queue​

统一入口，通过 type 区分内容类型。

字段类型必填说明
typestring是text / file / base64 / url
contentstring视类型text=文字, file=本地路径, url=下载地址
filenamestringbase64 必填base64 时的文件名；url 时可用于自定义
data_base64stringbase64 必填base64 编码的文件内容
labelstring是显示名
groupstring否分组号，不传归入 default

type=text

{"type":"text","content":"你好","label":"问候","group":"batch-1"}

type=file（本地文件）

{"type":"file","content":"C:\\Users\\admin\\report.pdf","label":"周报"}

type=base64（浏览器直接传文件）

{"type":"base64","filename":"photo.png","data_base64":"iVBORw0KGgo...","label":"截图"}

type=url（网络文件，自动下载后入队）

{"type":"url","content":"https://example.com/manual.pdf","label":"手册"}

响应：{"id":"0f7e752fb570378f"}

文件名来源
type传 filename不传
url用自定义名（非法字符已清洗）从 URL 或 Content-Disposition 推断
base64用自定义名魔数推断扩展名（file.pdf / file.png）
file不可改本地文件真实名

GET /api/v1/queue​

[
  {
    "id": "0f7e752fb570378f",
    "kind": "text",
    "content": "你好",
    "label": "问候",
    "group": "default"
  }
]

DELETE /api/v1/queue/{id}​

移除指定待发送项。

POST /api/v1/queue/send-next​

从当前激活分组取队首 → 写剪贴板 → 自动 Ctrl+V。

{"status":"sent","remaining":2}

空队列返回 400。

POST /api/v1/queue/clear​

清空当前激活分组的待发送项。

GET /api/v1/queue/groups​

["batch-1", "batch-2"]

GET /api/v1/queue/active-group​

{"active_group":"batch-1"}

POST /api/v1/queue/active-group​

{"group":"batch-2"}

GET /api/v1/queue/sent​

已发送列表，支持 ?group=xxx 过滤。

[
  {
    "id": "a1b2c3d4",
    "kind": "text",
    "content": "你好",
    "label": "问候",
    "group": "default",
    "sent_at": 1729584000,
    "sent_at_readable": "2026-10-22 17:07:11"
  }
]

POST /api/v1/queue/restore​

body行为
{}还原全部已发送项
{"group":"default"}只还原该分组
{"id":"a1b2c3d4"}只还原指定项

响应：{"restored":3}

GET /api/v1/queue/mode · POST /api/v1/queue/mode​

{"mode":"auto"}

auto = 一次触发发完整个分组；single = 每次只发一条。

GET /api/v1/queue/timing · POST /api/v1/queue/timing​

{
  "paste_settle_ms": [250, 700],
  "file_settle_ms": [400, 900],
  "item_gap_ms": [600, 2600],
  "typing_sim": false
}

可设字段：settle_min settle_max file_settle_min file_settle_max gap_min gap_max typing_sim。

分享​

GET /api/v1/shares​

分享列表。

POST /api/v1/shares​

{"path":"C:\\Users\\admin\\Documents"}

DELETE /api/v1/shares/{id}​

快传​

POST /api/v1/quick-transfer​

{"url":"https://example.com/file.zip"}

下载并放入剪贴板。

打印​

POST /api/v1/print​

{"path":"C:\\test.pdf"}

或网络文件：

{"url":"https://example.com/doc.pdf","printer":"Microsoft Print to PDF"}

传输历史​

GET /api/v1/transfers​

最近 100 条传输记录。

分享服务端点​

以下端点运行在 8721 端口。

GET /s/{token}​

授权后展示文件/目录列表与下载入口。

GET /s/{token}/download​

下载文件（目录打包为 zip）。

令牌过期返回 410，不存在返回 404。

POST /pair​

设备配对，提交配对码。

GET /pairing-code​

获取当前配对码。

更新​

GET /api/v1/queue/timing 之外的更新端点​

更新相关通过 Tauri 命令提供（check_update / download_update / install_update）， 因为需要访问应用上下文与本地文件系统。详见更新机制。