API 文档

5 分钟上手

1. 拿 key：在线自助订阅 / 充值已开通 —— 选档位跳收银台付款，凭 request_id 一键领取 saler_… 明文密钥（仅显示一次）；或邮件 service@saler.ai 由我们代开。
2. 先免费试一下：GET /api/v1/diagnose?domain=example.com 不需要 key，可直接验证网络与响应形状。
3. 先问价，再下单：每个扣费端点都有对应的报价端点（*_estimate），报价不扣费，只返回售价。
4. 正式调用：带上 authorization: Bearer $SALER_API_KEY，建议同时传 idempotency_key（重试不重复扣费）。

curl 'https://api.saler.ai/api/v1/diagnose?domain=example.com'

鉴权与响应封套

• 租户密钥走 HTTP 头：authorization: Bearer $SALER_API_KEY。
• 成功统一封套：{ "code": "OK", "data": <负载>, "meta": { "locale": "…" } }。
• 失败同形状：{ "code": …, "message": …, "retryable": …, "action": … }。
• 公开端点（/api/v1/diagnose、/api/v1/openapi.json）无需 key，但带配额。

错误与「404 双语义」

404 有两种含义，判据在 message 前缀而不在状态码： 路径不存在：… 表示路由没注册（客户端写错地址或该版本未部署）； 未找到：… 表示路由存在、但对象不存在（如品牌未授权/未登记）。 把两者都当成「地址写错」会误诊——前者改地址，后者查授权。

401 也有两种语境：响应要求租户 key 说明路由已注册；要求 ADMIN_TOKEN 说明该路径属于管理面。

定价速查

两种买法：按次（用一次付一次，报价端点免费、下单前先问价）与 包月订阅（覆盖的品牌读窗口数据 $0）。

报价端点只返回售价（按 kind / 窗口的固定牌价）。

订阅覆盖内的窗口查询为 $0：品牌若已被下方的「品牌监测订阅」覆盖， 读 30 / 90 / 365 天窗口不再单独计费。覆盖范围与理由由自助端点 GET /api/v1/billing/subscriptions/me、以及每次扣费响应里的 subscription 字段给出一一 两处走同一套判定， 不会出现「自助页说免费、实际却照收」。未被覆盖、或有效授权品牌数超过档位上限时， 一律按上表窗口价正常计费（fail-closed：拿不准就按收费处理，绝不静默免费）。

按次窗口仅对「已在采集范围」的品牌开放：日采样持续进行中的品牌（已在采） 可按次立查；不在采集范围的新品牌请走订阅 —— 订阅费覆盖其持续采集成本，覆盖内查询 $0。 定位上，按次窗口是订阅的价格锚与试用入口：临时查一次用按次，长期监测选订阅更划算。

品牌监测订阅（按月）自助购买已开放

把品牌 AI 可见度监测做成包月：档位内已授权品牌的窗口查询不再单独计费（$0）。 适合要持续盯多个品牌的团队，以及按月给客户出报告的 SEO / GEO 服务商。

点按钮即跳 Creem 收银台完成付款；付完后跳回页面凭 request_id 一键领取 API key（明文仅显示一次）。 订阅由持牌收单方（MoR）代收并开具发票。 「覆盖品牌数」以当前已授权品牌数为准：超过档位上限时整体不覆盖（fail-closed）， 需先撤销多余授权或升档 —— 我们不做「按前几个品牌免费」，那种边界你无法预期、我们也解释不清。

自助登记品牌（拿 key 后无需等我们）

订阅 / 充值并领取 API key 后，品牌登记完全自助：用你自己的 key 调一次即可，不再需要管理员后台代操作。 订阅允许多个品牌（Starter 3 / Growth 10 / Scale 20），且支持一次建满：可以在下单时直接带品牌， 也可以在领 key 后批量登记。

• 最省事 · 下单即带品牌：POST /api/billing/subscribe/public 传 {"tier":"growth","brands":[{"brand_id":"acme-foods"},{"brand_id":"acme-drinks"}]}（数量 ≤ 该档上限）。付款后凭 request_id 领 key 的同一刻自动授权这些品牌，买完即用；万一授权未成会以 brand_warnings 如实告知，绝不影响你拿到 key。
• POST /api/v1/brands —— 授权一个或多个品牌给自己：单条 {"brand_id":"acme-foods"}，或批量 {"brands":[{"brand_id":"acme-foods"},{"brand_id":"acme-drinks"}]}（数组元素也可直接写纯字符串）。若品牌已在目录中存在可直接授权，不存在则自动建一个 core 品牌（进入每日采样），无需审核。
• GET /api/v1/brands —— 查看已授权品牌详情 + 额度条：每条给出品牌名 / 域名 / 品类 / 采样状态，以及 self_editable_missing（你还能自己补录哪些字段）；顶层 quota 直接告诉你还剩几个名额（{tier, brand_limit, used, remaining}），不用猜。
• PATCH /api/v1/brands/{brandId} —— 自助补录域名 / 品类，仅限当前为空的字段。已有值会被 409 拒绝：品牌目录是跨租户共享的，改已有值会影响其他租户的报告口径，这类修改请交给我们（这是刻意的分工，不是遗漏）。品牌展示名与内部字段（采样层、实体类型、别名）客户侧不可改。
• DELETE /api/v1/brands/{brandId} —— 撤销自己某个品牌的授权（幂等，重复撤销如实返回 revoked:false）。
• 受两道纪律约束（与后台同源）：非订阅租户只能授权「已在采」品牌；订阅租户授权数不超过档位上限。批量登记整批先校验再落库 —— 超限则整批拒绝、一行都不写，不会出现「建了 4 个、还差 6 个」。

例如一次给租户加上两个品牌：curl -X POST https://api.saler.ai/api/v1/brands -H "Authorization: Bearer <你的key>" -d '{"brands":[{"brand_id":"acme-foods"},{"brand_id":"acme-drinks"}]}'。 授权成功后，GET /api/brand-visibility 即可看到它们，随后 POST /api/brand-visibility/:brandId 便能查询时序。

接入通道（REST / MCP / CLI）

同一账户、同一套计费。REST 与 MCP 走租户 API Key（Authorization: Bearer）鉴权，匿名不可调用（会花钱）；CLI 是仓库内的运维/自托管入口，需管理员令牌，不对外分发。

• REST API：所有响应为 JSON，机器可读规格同源渲染于 /api/openapi.json；适合服务端集成与脚本。
• MCP：POST /mcp（JSON-RPC 2.0 over Streamable HTTP），含 6 个工具（见下方实时面板）；专为 AI 智能体直接调用设计，长任务返回 job_id 轮询。发现端点 /.well-known/mcp.json（免鉴权 GET）。
• CLI（bin/saler）：仓库内的本地命令行入口，与 REST 共用账户与计费，用于我们自己的运维动作（采样交付、上游校准、令牌轮换、品牌授权等）。它不是客户工具，没有订阅命令，也不对外分发 —— 客户接入请走 REST 或 MCP。

MCP 工具（实时）

口径披露（会影响你怎么解读数据）

• 空档日不是 0：某天没采样时可见度为 null，绝不用 0 填补（0 会被读成「掉了」）。
• 口径带版本号：可见度得分口径为 vs2（分母排除无 AI 概览的查询）。跨口径的报告不能直接比较。
• 样本不进交付物但会披露：is_sample 的数据行参与计数、但不作为结论交付。
• 能生成 ≠ 能交付：若窗口内有效样本不足，响应会给出覆盖天数与空档天数，趋势字段为 N/A 而不是编一个数。

端点参考

以下由线上 OpenAPI 规格实时渲染；想给智能体直接读机器规格，用 /api/openapi.json。