服务与鉴权
鉴权
API Key
在 NexBrowser → API MCP 页面开启 OpenAPI 后，复制客户端生成并持久化的访问密钥。密钥保存在用户主目录的客户端配置中，重启客户端后保持不变；重置密钥后旧密钥立即失效。
除公共的 GET /health 外，所有接口都需要请求头 Authorization: Bearer <api-key>。Bearer 关键字不区分大小写，密钥本身不能含空格。
curl -H "Authorization: Bearer <API_KEY>" http://127.0.0.1:45536/team/list
访问密钥可调用本机 OpenAPI，包括会扣减余额的付费业务接口；请勿将它分享给未授权人员或写入可公开访问的文件。
团队上下文
团队、账号、代理、窗口列表与窗口创建、打开等转发接口，以及全部付费业务接口，都使用客户端当前登录态。先通过 GET /team/list 取得 data[].id，它就是其他接口需要的 teamId。账号与代理保存时，服务端会按当前登录团队覆盖 teamId，请求中传入无效。
未登录时，转发接口返回 Backend command requires login token。/health、/user/info、/user/config 与 /browser/connection_info 只读本机状态。
语言
本机生成的提示（参数错误、批量操作失败原因、检测失败原因等）固定为简体中文，不随客户端界面语言变化。请求带 Accept-Language（zh-CN 或 en-US）时会原样转发给服务端，服务端返回的 msg、账单说明等按该语言生成；未传时按 zh-CN。
自动化客户端标识
/automation/* 除公共鉴权外，还需提供 X-Nex-Client-Id。其值须匹配 [A-Za-z0-9._:-]{8,128}。
会话按该标识归属：只有创建会话的客户端能读写它；登录账号或团队发生变化后，旧会话会返回 UNAUTHORIZED。
服务地址与健康检查
默认服务地址是 http://127.0.0.1:45536，且仅监听 127.0.0.1。默认端口被占用时会自动向后顺延，实际端口以客户端 API MCP 页面显示为准。
GET /health 是公共接口，不需要 Authorization 请求头：
curl http://127.0.0.1:45536/health
业务服务接口
代理商店（/ip/*）、云手机号（/sms/*）、邮箱服务（/mail/*）、验证码识别（/captcha/*）与账单流水（/billing/*）统称业务服务接口，遵循以下额外约定。
| 约定 | 说明 |
|---|---|
| 严格校验 | 非 /sms/* 接口按白名单校验，未知字段或类型不符返回 code: -1100，msg 为 字段: 原因 列表；/sms/buy 仅接受 countryId、projectId、quantity，多传字段返回 code: 1 |
| 直接扣费 | 购买、续费与提交识别任务只传业务参数，服务端按当前价格核算并扣费；客户端不再预查价格、库存或套餐，权限、余额与可用性由服务端校验 |
| 上下文标识 | 成功响应在信封顶层附带 contextId，标识本次请求的登录与团队 |
| 不重复未知扣费 | 每次请求只提交一次；结果不明时先查对应记录接口与 /billing/trades，无法证实则停止；确认业务失败后可由调用端在恢复上限内更换资源 |
可选请求头：
| 请求头 | 说明 |
|---|---|
X-Nex-Service-Context | 传入之前响应里的 contextId，把多步操作固定在同一登录与团队下；登录或团队已变化时返回 code: "SESSION_CONTEXT_CHANGED" 且不执行。验证码自动化动作必须带此请求头 |
X-Nex-Request-Deadline | 毫秒时间戳形式的请求期限，必须是十进制整数；客户端据此缩短向服务端的等待时间，/proxy/detect 批量检测也按它安排批次 |
curl -X POST http://127.0.0.1:45536/captcha/schema \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-H "Accept-Language: zh-CN" \
-d '{"productCode":"RECAPTCHA_V2"}'
已授权任务所需的付费服务直接提交，无需报价或额外费用确认。maxTotalPrice 已移除：/sms/buy 携带该字段或其他未知字段返回 code: 1，其余购买与续费接口返回 code: -1100。服务端业务错误原样透传。购买网络超时或结果不明时先核对记录与账单，无法证实则停止，不重复扣费；确认业务失败或收码/收信等待超时后，可按自动化规则换购。
内置 Agent 与 MCP 自动化的交互恢复默认短信等 120 秒、邮件等 180 秒，每类流程含首次最多 3 次，无需逐次回复。国家/项目或邮箱后缀/类型切换仍须匹配站点和用户硬性要求，不重置次数。-1208 或 insufficient_balance 会停止后续付费和额度消耗。HTTP 接口本身每次只执行所请求的一次操作，不隐式执行整套换购；nex_service_recovery 仅为内置 Agent 工具，不对应公共 MCP 工具或 HTTP 路由。邮箱 MCP 本地等待/过滤参数不属于 /mail/pull 的请求字段。