MarginNote 4 本地 Agent Bridge 完整 HTTP 接口文档（Bridge API v0.49 / 72 路由）

MarginNote Agent Bridge HTTP API

本地 Bridge 的完整 HTTP 接口文档。适用于 MarginNote 4（App 4.5.0 / Bridge API v0.49）。

Base URL：http://127.0.0.1:{port}/bridge/v1（端口现查，默认 42340 起扫 20 个）
路由总数：72（以运行时 GET /capabilities 为准）
鉴权：除 GET /status 外一律 Authorization: Bearer $TOKEN；不要带 Origin 头
订阅门：读/搜索/渲染/导航/prepare 不要求 Max；创建或修改内容/持久状态要求 Max（以 requiresMax 为准）
权威顺序：运行时 /capabilities 清单＞运行时 GET /guide ＞本站

本站是构建时刻的静态快照，不是权威。连上实例后第一件事是读运行时 GET /status（对 guideVersion/guideHash）→ GET /guide → GET /capabilities，不一致时以运行时为准。发即执行的危险端点先读危险端点纪律。

连接与鉴权发现

标准工作流

错误处理与纪律

交互式 API 参考

快速连通性检查

# 1. 免鉴权探活（200 = Bridge 活着）
curl -s http://127.0.0.1:42340/bridge/v1/status

# 2. 带 token 对账（authorized 应为 true）
TOKEN=$(cat ~/.config/mn-bridge/token)
curl -s http://127.0.0.1:42340/bridge/v1/status -H "Authorization: Bearer $TOKEN"
curl -s http://127.0.0.1:42340/bridge/v1/capabilities -H "Authorization: Bearer $TOKEN" | head -c 500

令牌获取：MarginNote 设置 → Lab →「Copy Agent Setup Command」，粘进终端执行。安装码 10 分钟有效、只能用一次。跨设备走局域网配对（见指南）。

来源

raw/：一次性安装链接的原始响应存档与运行时 /status /capabilities /guide 快照
openapi/openapi.yaml：由 raw/capabilities.json 经 scripts/build-openapi.py 生成的 OpenAPI 3.1（含 72 路由），本站交互式参考即由它渲染
语义细节来自运行时 GET /guide（mn-bridge Skill v0.49），已提炼进各参考页

简介