简介
欢迎使用 Performance Hub API。 此 API 管理俱乐部数据以及与您的俱乐部及其外部系统集成的关键系统，并非公开使用的 API。 如需进一步了解如何使用此 API 支持的各个 Performance Hub 系统，请参阅 [Performance Hub 文档](https://docs.performancehub.co)中相应系统的单独条目。
基础 URL
https://portal.hub.gymsystems.co身份验证
您的集成获批后，我们将提供身份验证详细信息。
设备上报的“代理轮次完成”事件（Web 推送触发器）
当从 Web 界面发起的代理运行结束且运行时长超过设备的通知阈值时，由已配对人工智能代理设备的 sidecar 调用（绝不由浏览器调用）。使用短期有效的每设备 HS256 JWT（aud 'events'）进行身份验证。按设备+会话+开始时间去重，并按设备限速，然后推送到发起用户的 HTML5 推送订阅，附带指向该对话的深层链接。
请求正文
端点
POST /ai/events/agent-turn-complete请求示例
curl -X POST https://portal.hub.gymsystems.co/ai/events/agent-turn-complete \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
代理发起的推送通知（ph-notify 技能）
由已配对人工智能代理设备的 sidecar 代表设备上的代理（ph-notify 技能）调用，用于向用户的浏览器和移动设备推送任意通知。使用短期有效的每设备 HS256 JWT（aud 'events'）进行身份验证。目标用户必须有权访问该设备（按代理的访问策略）；如果省略，通知将发送给设备所有者。按设备限速，与轮次完成事件分开计算。
请求正文
端点
POST /ai/events/agent-notify请求示例
curl -X POST https://portal.hub.gymsystems.co/ai/events/agent-notify \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
上传通知图片（ph-notify 技能）
接收来自已配对设备的原始图片正文（aud 'events' JWT），并以不可猜测的 UUID 键存储到公开的 notify-media 存储桶中。对象在 7 天后自动删除（S3 生命周期）。返回公开的 https URL，可在 /ai/events/agent-notify 中用作 `imageUrl`。上限 5 MB；仅支持 png/jpeg/gif/webp。
请求正文
端点
POST /ai/media/notify-image请求示例
curl -X POST https://portal.hub.gymsystems.co/ai/media/notify-image \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
用于 Connected Apps（外部 SaaS 工具）的设备 MCP 中继
供已配对的人工智能代理设备使用的 Streamable-HTTP MCP 端点（设备边车 :8790 监听器上的 "connected_apps" MCP 服务器）。使用短期有效的按设备 HS256 JWT 进行认证（aud 'mcp'，与 /mcp 使用相同凭据），并受代理的 Connected Apps 启用标志控制（连接按代理设备而非按设施划分）。请求会流式传输到代理自身的上游工具平台会话 MCP 服务器，会话标头在服务器端注入；上游凭据永远不会到达设备。工具名称和供应商品牌在传输过程中双向进行白标处理。上游返回 401/410（会话过期）时，会重新创建一次会话并重试。
端点
POST /mcp/apps请求示例
curl -X POST https://portal.hub.gymsystems.co/mcp/apps \
-H "x-api-key: YOUR_API_KEY"
响应
{}
搜索 API 审计日志（IAM 与管理模块访问权限）
使用高级筛选功能搜索和筛选 API 访问日志。用户只能查看其有权访问的组织的日志。
参数
organisationId `string` （可选） 用于 ACL 验证的组织 ID（必填）请求正文
端点
POST /api/admin/audit-logs/search请求示例
curl -X POST https://portal.hub.gymsystems.co/api/admin/audit-logs/search \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
从 Redis 获取缓存的审计日志统计信息（IAM 与管理模块访问权限）
从 Redis 缓存检索汇总统计信息，以便即时加载仪表板
参数
timeWindow `string` （可选） 统计信息的时间窗口（默认为 12h）端点
GET /api/admin/audit-logs/statistics-cached请求示例
curl -X GET https://portal.hub.gymsystems.co/api/admin/audit-logs/statistics-cached \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取审计日志统计信息（IAM 与管理模块访问权限）
检索仪表板的汇总统计信息。范围限于用户所属的组织。
参数
startTime `number` （可选） 开始时间（Unix 时间戳），默认为 24 小时前 endTime `number` （可选） 结束时间（Unix 时间戳），默认为当前时间端点
GET /api/admin/audit-logs/statistics请求示例
curl -X GET https://portal.hub.gymsystems.co/api/admin/audit-logs/statistics \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取审计日志的时间序列数据（IAM 与管理模块访问权限）
检索分桶的时间序列数据，用于请求时间线可视化
参数
timeWindow `string` （可选） 时间序列数据的时间窗口： - 1h：最近 1 小时（10 分钟分块） - 12h：最近 12 小时（10 分钟分块） - 24h：最近 24 小时（10 分钟分块） - 7d：最近 7 天（1 小时分块） - 14d：最近 14 天（1 小时分块）端点
GET /api/admin/audit-logs/timeseries请求示例
curl -X GET https://portal.hub.gymsystems.co/api/admin/audit-logs/timeseries \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取用户可查看审计日志的组织（IAM 与管理模块访问权限）
返回当前用户可查看审计日志的组织列表
端点
GET /api/admin/audit-logs/user-organisations请求示例
curl -X GET https://portal.hub.gymsystems.co/api/admin/audit-logs/user-organisations \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建新俱乐部的初始调用……请注意，此调用仅创建“模板”俱乐部对象，之后还需要第二个 API 请求来更新俱乐部的数据，例如营业时间、位置、社交媒体 URL 等。
参数
body `string` （必填） 要添加到系统中的新俱乐部的 JSON 对象。端点
POST /api/admin/clubs/addclub请求示例
curl -X POST https://portal.hub.gymsystems.co/api/admin/clubs/addclub \
-H "x-api-key: YOUR_API_KEY"
响应
{}
向系统添加新用户
参数
body `string` （必填） 要添加/更新的用户数据的 JSON 对象。端点
POST /api/users请求示例
curl -X POST https://portal.hub.gymsystems.co/api/users \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出有权访问后台系统/API 的所有用户（Google Apps 账户）
端点
GET /api/admin/users/listusers请求示例
curl -X GET https://portal.hub.gymsystems.co/api/admin/users/listusers \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出用户的 MCP 密钥（已脱敏）。用户可以列出自己的密钥。
参数
userId `string` （必填）端点
GET /api/users/{userId}/mcp-keys请求示例
curl -X GET https://portal.hub.gymsystems.co/api/users/{userId}/mcp-keys \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为用户创建新的 MCP API 密钥。用户可以创建自己的密钥。
参数
userId `string` （必填） body `object` （可选）端点
POST /api/users/{userId}/mcp-keys请求示例
curl -X POST https://portal.hub.gymsystems.co/api/users/{userId}/mcp-keys \
-H "x-api-key: YOUR_API_KEY"
撤销/移除 MCP API 密钥。用户可以删除自己的密钥。
参数
userId `string` （必填） keyId `string` （必填）端点
DELETE /api/users/{userId}/mcp-keys/{keyId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/users/{userId}/mcp-keys/{keyId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
移除用户的角色
参数
userId `string` （可选） 要移除其角色的用户的电子邮件地址。 roleId `string` （可选） 要从该用户移除的角色的 ID。端点
DELETE /api/users/{userId}/roles/{roleId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/users/{userId}/roles/{roleId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新现有用户的个人资料详细信息（firstName、lastName、phoneNumber）
参数
userId `string` （必填） 用户的电子邮件地址 body `object` （必填） 要更新的用户个人资料数据端点
PATCH /api/users/{userId}请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/users/{userId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
插入或更新用户角色
参数
body `object` （可选）端点
PUT /api/users/{userId}/roles请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/users/{userId}/roles \
-H "x-api-key: YOUR_API_KEY"
响应
{}
设施的人工智能代理上运行的 Live Services（发布选择器）
通过隧道获取设备 bridge 检测到的 Live Services，供小程序的“Publish to Performance Hub”选择器使用。需要 ph-ai-agent 模块以及 'open' 每设备访问权限（与发布本身的要求相同）。如果某个服务的端口已存在 Custom App，该服务会标注 publishedAppId。
参数
club `string` （必填） device `string` （必填）端点
GET /api/agent-apps/services/{club}/{device}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-apps/services/{club}/{device} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
内置于设施人工智能代理中的 MDI 图标名称索引（图标选择器）
通过隧道代理设备 bridge 内置的 MDI 图标索引（GET /__services/icons/mdi/index.json）。发布/编辑选择器使用小程序自带的目录（同样固定为 7.4.47 版本）；已发布应用的 SVG 从 portal-server 本地的 @mdi/js 包解析。访问要求与服务选择器相同（ph-ai-agent 模块 + 'open' 每设备访问权限）。
参数
club `string` （必填） device `string` （必填）端点
GET /api/agent-apps/mdi-index/{club}/{device}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-apps/mdi-index/{club}/{device} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从设施的人工智能代理批量获取 MDI 图标 SVG（选择器预览）
一次调用最多可从设备内置图标集中解析 60 个指定名称的 MDI 图标，并在服务器端使用与已保存应用图标相同的允许列表进行清理。图标选择器使用它来呈现搜索结果；未知名称返回 null。
参数
club `string` （必填） device `string` （必填）请求正文
端点
POST /api/agent-apps/mdi-icons/{club}/{device}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-apps/mdi-icons/{club}/{device} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
请求者可从此设施发布到的受众范围
供发布/编辑选择器使用的发布者可授予受众范围：其 ph-ai-agent 角色覆盖的设施（多设施范围），以及其是否在此设施所属品牌/组织中拥有面向整个品牌/整个组织受众所需的组织级权限。发布/更新时服务器端会再次执行相同规则（validatePublishAudience），此端点仅用于呈现界面。
参数
club `string` （必填）端点
GET /api/agent-apps/audience-options/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-apps/audience-options/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为指定用户应用受众自动补全同事
仅搜索请求者已可见的用户，即角色与请求者自身 ph-ai-agent 访问权限中至少一个设施/区域/组织重叠的人员。查询至少 2 个字符且最多返回 10 条结果，使该端点无法用于抓取数据；保存受众时，服务器端会再次执行相同的可达范围限制。
参数
club `string` （必填） q `string` （必填）端点
GET /api/agent-apps/user-search/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-apps/user-search/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将人工智能代理的 Live Service 发布为 Performance Hub Custom App
将设施人工智能代理托管的 Web 应用（bridge 检测到的 Live Service）注册为所选受众的“Custom Apps”侧边菜单项。需要此设施的 ph-ai-agent 模块以及 'open' 每设备访问权限；受众受发布者自身角色范围的限制（发布范围永远不能超出您可访问的范围）。服务标识从设备的 /__services 列表实时解析；http/https 协议永不保存。
参数
club `string` （必填）请求正文
端点
POST /api/agent-apps/publish/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-apps/publish/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
此设施可见的已发布 Custom Apps
返回受众覆盖此设施的有效已发布应用，格式与侧边菜单呈现的一致（appId、name、icon、description）。每次调用都会实时重新解析受众，因此访问权限更改会立即生效。
参数
club `string` （必填）端点
GET /api/agent-apps/menu/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-apps/menu/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从此设施管理的已发布应用（发布者视图）
返回主设施为此俱乐部的应用的完整应用记录，供小程序的“Published Apps”管理列表使用。每条记录都会针对请求用户（发布者）标注 canManage。
参数
club `string` （必填）端点
GET /api/agent-apps/manage/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-apps/manage/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为已发布的 Custom App 生成服务范围的查看者令牌
返回短期有效的签名 URL + 令牌，浏览器使用它直接在设备所在区域的中继网关上打开一个已发布应用。令牌带有指明服务端口的 svc 声明，因此网关会将会话限制在 /__services/proxy/
参数
club `string` （必填） appId `string` （必填）端点
POST /api/agent-apps/access/{club}/{appId}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-apps/access/{club}/{appId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
已发布 Custom App 的支持归属（所有者联系方式）
此用户发布应用的支持方：发布者的电子邮件地址（如无则为托管代理的所有者）。显示在查看者的离线/错误面板上，使支持请求发送给应用所有者而非 Performance Hub，因为已发布应用不属于 PH 核心支持范围。系统会先重新检查应用的受众；未获共享的查看者不会得到任何信息。已暂停的应用仍可解析（所有者也需要解答“为什么暂停了？”之类的问题）。
参数
club `string` （必填） appId `string` （必填）端点
GET /api/agent-apps/support-info/{club}/{appId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-apps/support-info/{club}/{appId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
通过电子邮件向已发布 Custom App 的所有者发送支持请求
将查看者的消息以品牌电子邮件形式发送给应用的支持联系人（发布者，如无则为代理所有者）：收件人为所有者，抄送查看者（作为其请求记录），回复地址为查看者，以便所有者直接回复。已发布应用由用户维护，因此其支持请求不会进入 Performance Hub 的队列。系统会重新检查受众；每位查看者对每个应用每 15 分钟只能发送一个请求（Redis 冷却，故障时放行）。
参数
club `string` （必填） appId `string` （必填）请求正文
端点
POST /api/agent-apps/support-request/{club}/{appId}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-apps/support-request/{club}/{appId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
更新已发布的 Custom App（名称、图标、描述、状态、受众）
仅限发布者。受众更改会根据编辑者的角色范围重新验证，限制规则与发布时相同。状态可在 active 和 paused 之间切换（已暂停的应用会从菜单中消失，并拒绝生成令牌）。
参数
club `string` （必填）请求正文
端点
POST /api/agent-apps/update/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-apps/update/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
取消发布 Custom App（软删除）
仅限发布者。软删除注册记录：应用会立即从菜单中消失，查看者令牌生成会被拒绝；已发放的网关会话在令牌到期时失效。
参数
club `string` （必填）请求正文
端点
POST /api/agent-apps/unpublish/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-apps/unpublish/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
转让已发布 Custom App 的所有权
与人工智能代理的重新分配所有者流程相同：当前发布者或账户所有者（计费模块）可以将应用移交给另一位用户，由其接手管理。新所有者必须拥有该应用主俱乐部的设施访问权限。
参数
club `string` （必填）请求正文
端点
POST /api/agent-apps/transfer-owner/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-apps/transfer-owner/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
某个技能版本的完整扫描报告（+ LLM 审核）
某个版本的完整问题列表，仅限发布者和组织管理员（审批审核）查看；安装者则在技能详情中查看汇总计数。
参数
club `string` （必填） skillId `string` （必填） version `string` （必填）端点
GET /api/agent-skills/scan-report/{club}/{skillId}/{version}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-skills/scan-report/{club}/{skillId}/{version} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
提交技能草稿版本（发布或加入审批队列）
根据组织的治理规则推进草稿版本。如果组织已启用 LLM 审核，会先运行指令审核（尽力而为；'fail' 结论会拒绝，'flag' 结论会强制进入审批队列）。除非治理规则要求审批，否则设施级共享会立即发布；组织库共享（品牌/组织受众）默认需要审批。发布会设置技能的 latestVersion，采用 'auto' 策略的安装会在下一次协调扫描时获取该版本。
参数
club `string` （必填）请求正文
端点
POST /api/agent-skills/submit/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-skills/submit/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
此设施可见的技能库（按受众筛选）
返回至少有一个已发布版本且受众覆盖此设施（或指定了查看者）的有效技能，并标注最新已发布版本摘要和组织采用情况（不同设施的数量，绝不提供原始安装次数）。每次调用都会实时重新解析受众。
参数
club `string` （必填）端点
GET /api/agent-skills/library/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-skills/library/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
技能详情（版本、要求、扫描摘要、采用情况）
某个库技能的完整详情：包含更新日志和扫描摘要的版本历史（每个版本的端点列表用于更新时的扫描对比）、清单中声明的要求、发布者来源以及按设施数量计算的采用情况。系统会重新检查受众，未获共享的查看者不会得到任何信息（发布者和组织管理员始终可见）。
参数
club `string` （必填） skillId `string` （必填）端点
GET /api/agent-skills/skill/{club}/{skillId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-skills/skill/{club}/{skillId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从此设施发布的技能（发布者的管理列表）
返回主设施为此俱乐部的完整技能记录，每条记录都针对请求用户标注 canManage 及其最新版本摘要（包括草稿和待审批版本，这是发布者的工作视图）。
参数
club `string` （必填）端点
GET /api/agent-skills/manage/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-skills/manage/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将库技能安装到设施的人工智能代理上
受治理规则控制：组织的 installSources 必须允许，技能的受众必须覆盖此设施（或指定了请求者），版本必须已发布，并且请求者必须满足目标设备的 whoCanInstall 级别（所有者/允许的用户/设施管理员/组织管理员，详见治理规则）。写入安装生命周期记录（作为事实来源）并立即尽力推送；设备可访问后，协调定时任务可确保交付。
参数
club `string` （必填）请求正文
端点
POST /api/agent-skills/install/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-skills/install/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
批准某个安装的待处理技能更新
将安装的 desiredVersion 移至最新已发布版本（这是 'notify' 和 'pinned' 策略的手动步骤，也是治理规则将 updatePosture 设为 'approvalRequired' 时的路径）。保留当前版本作为一步回滚目标，并清除回滚后设置的任何更新固定（skipVersion）。所需 whoCanInstall 权限级别与安装相同。
参数
club `string` （必填）请求正文
端点
POST /api/agent-skills/update-approve/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-skills/update-approve/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
将已安装的技能回滚到上一个版本
将 desiredVersion 设为安装记录的 previousVersion（每次版本变更时都会保留），并通过正常交付路径重新安装。仅回滚一步：两个版本互换，因此回滚两次会回到原来的版本。同时会固定更新（skipVersion = 回滚前的版本），使 auto/notify 策略保留回滚结果；当发布了更新的版本、执行 update-approve 或 set-policy 时，固定会被清除。
参数
club `string` （必填）请求正文
端点
POST /api/agent-skills/rollback/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-skills/rollback/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
从设施的人工智能代理卸载技能
将安装记录标记为 pending-uninstall 并推送目标状态；设备确认移除后（协调回读）会删除该记录。所需 whoCanInstall 权限级别与安装相同。
参数
club `string` （必填）请求正文
端点
POST /api/agent-skills/uninstall/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-skills/uninstall/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
为某台设备上的技能设置单个安装的更新策略
auto（协调时自动应用新发布的版本，除非组织的 updatePosture 要求审批）、notify（每个新版本通知所有者一次，由其手动应用）或 pinned（未经明确的 update-approve 绝不变更）。更改策略会清除回滚后设置的任何更新固定（skipVersion）。所需 whoCanInstall 权限级别与安装相同。
参数
club `string` （必填）请求正文
端点
POST /api/agent-skills/set-policy/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-skills/set-policy/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
设施人工智能代理上的技能安装（Skills 选项卡）
某台设备的安装生命周期记录，每条记录都标注了技能的列表字段以及是否存在更新的已发布版本。需要 'open' 每设备访问权限（Skills 选项卡位于代理抽屉中）。
参数
club `string` （必填） device `string` （必填）端点
GET /api/agent-skills/installs/{club}/{device}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-skills/installs/{club}/{device} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
此设施所属组织中等待审批的技能版本
组织管理员审批队列：组织所有技能中每个待审批的版本，附带技能列表信息和扫描/LLM 摘要。仅限组织管理员。
参数
club `string` （必填）端点
GET /api/agent-skills/approvals/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-skills/approvals/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
批准待审批的技能版本（将其发布）
仅限组织管理员。该版本变为已发布，技能的 latestVersion 随之更新，并通知发布者。采用 'auto' 策略的安装会在下一次协调扫描时获取该版本。
参数
club `string` （必填）请求正文
端点
POST /api/agent-skills/approve/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-skills/approve/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
拒绝待审批的技能版本
仅限组织管理员。该版本变为已拒绝并附带审核者的理由，同时通知发布者；发布者可以修复问题并提交新版本（版本不可更改）。
参数
club `string` （必填）请求正文
端点
POST /api/agent-skills/reject/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-skills/reject/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
此设施所属组织的有效 Agent Skill 治理规则
将存储的组织策略合并到平台默认值之上（没有存储记录的组织只看到默认值）。仅限组织管理员。
参数
club `string` （必填）端点
GET /api/agent-skills/governance/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agent-skills/governance/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新此设施所属组织的 Agent Skill 治理规则
部分更新：仅更改提供的字段，其他字段保留其存储值/默认值。仅限组织管理员。每设备覆盖设置通过现有的设备配置路由保存在注册记录中。
参数
club `string` （必填）请求正文
端点
POST /api/agent-skills/governance/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agent-skills/governance/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
获取设施的环境数据
返回指定俱乐部的当前天气状况，包括日出/日落时间（通过 Open-Meteo）以及设施室内温度（来自 Duress 传感器）。在 Redis 中缓存 30 分钟。
参数
clubId `string` （必填） 俱乐部/设施的内部 ID端点
GET /api/clubs/{clubId}/environment请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubId}/environment \
-H "x-api-key: YOUR_API_KEY"
响应
{}
添加通用 IoT 设备或将其关联到俱乐部。
参数
club `string` （必填） 要在其下添加设备的俱乐部的内部 ID。 body `string` （必填） 要关联的新屏幕的 JSON 对象。端点
POST /api/devices/addGenericDevice/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/addGenericDevice/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
移除显示屏并恢复出厂设置
移除屏幕当前的设施关联，并设置一个持久的恢复出厂设置指令。已关机的屏幕会在下次开机并重新连接后执行重置，然后返回其 HDMI 配对页面。历史计费记录会保留。
参数
club `string` （必填）请求正文
端点
POST /api/devices/display-screens/reset/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/display-screens/reset/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
将门禁控制器关联到设施。
参数
club `string` （必填）请求正文
端点
POST /api/devices/door-controllers/associate/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/door-controllers/associate/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
更新设施的门禁控制器设置。
参数
club `string` （必填）请求正文
端点
POST /api/devices/door-controllers/update/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/door-controllers/update/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
从设施中停用门禁控制器。
参数
club `string` （必填）端点
POST /api/devices/door-controllers/decommission/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/door-controllers/decommission/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回门禁控制器的继电器配置。
参数
uuid `string` （必填）端点
GET /api/devices/door-controllers/config/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/door-controllers/config/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设备的元数据
参数
uuid `string` （必填） 设备的唯一 ID端点
GET /api/devices/metadata/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/metadata/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设备的元数据。响应在顶层包含元数据记录（旧版格式），以及 `detectedType`（camera | ai-edge-processor | door-controller | ph-ai-agent | null）和 `online`（5 分钟内有更新时为 true）。
参数
deviceSerialNumber `string` （必填） 设备的序列号端点
GET /api/devices/metadata/serial/{serialNo}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/metadata/serial/{serialNo} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部的智能俱乐部数据。
参数
club_id `string` （必填） 要在其下添加设备的俱乐部的内部 ID。端点
GET /api/clubs/{club_id}/smart-club-data请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club_id}/smart-club-data \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回与单个俱乐部关联的所有设备。
参数
club `string` （必填） 要列出其设备的俱乐部的内部 ID。端点
GET /api/devices/list/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/list/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回 balena 设备的所有应用程序发布版本。
端点
GET /api/devices/listReleases请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/listReleases \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将设备移至新的设施（俱乐部）并更新相关系统。
参数
club `string` （必填） 源设施 ID（设备当前所在的俱乐部） body `object` （必填） 移动参数端点
POST /api/devices/move/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/move/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
通过选择俱乐部内最合适的设备并发送 MQTT 命令创建隧道，尝试与设施的路由器建立连接。
参数
facilityID `string` （必填） 正在尝试建立路由器连接的设施的内部 ID。端点
GET /api/devices/openRouterWebpage/{facilityID}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/openRouterWebpage/{facilityID} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
Cloud Agent 目录（区域、规格、实时售价）
参数
club `string` （必填）端点
GET /api/devices/ph-ai-agent/cloud/catalog/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/cloud/catalog/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取 Cloud Agent 报价（软件 + 托管）
端点
POST /api/devices/ph-ai-agent/cloud/quote/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/cloud/quote/{club} \
-H "x-api-key: YOUR_API_KEY"
启动 Cloud Agent（将配置加入队列 + 自动关联）
端点
POST /api/devices/ph-ai-agent/cloud/launch/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/cloud/launch/{club} \
-H "x-api-key: YOUR_API_KEY"
Cloud Agent 任务状态
端点
GET /api/devices/ph-ai-agent/cloud/jobs/{club}/{jobId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/cloud/jobs/{club}/{jobId} \
-H "x-api-key: YOUR_API_KEY"
彻底清除 Cloud Agent（虚拟机 + balena + 注册）
端点
POST /api/devices/ph-ai-agent/cloud/delete/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/cloud/delete/{club} \
-H "x-api-key: YOUR_API_KEY"
处理已搁置的 Cloud Agent 移除操作（重试备份、不备份直接删除或取消）
端点
POST /api/devices/ph-ai-agent/cloud/delete-decision/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/cloud/delete-decision/{club} \
-H "x-api-key: YOUR_API_KEY"
列出代理的 Connected Apps（套件 + 已连接账户的应用）
返回代理的 Connected Apps 状态：启用标志、按套件汇总的信息（Google Workspace、Microsoft 365），以及精选应用目录和每个应用的已连接账户（多账户：每个应用可为一个代理连接多个账户，每个账户可设置别名），这些信息从代理的上游会话解析得出。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。端点
GET /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
代理的完整 Connected Apps 市场目录
返回所有可连接的应用（完整的托管身份验证工具包目录，在服务器端缓存约 12h），包括精选/套件层级以及代理在每个应用中的已连接账户，另附按套件汇总的信息和代理的待处理连接请求，作为可在客户端搜索的应用市场的单一负载。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。端点
GET /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/catalog请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/catalog \
-H "x-api-key: YOUR_API_KEY"
响应
{}
忽略代理的待处理连接请求
将代理对某个工具包的待处理连接请求标记为已忽略（它会从市场的“Requested by your agent”部分消失）。此操作是幂等的：忽略非待处理的请求不会产生任何效果。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。请求正文
端点
POST /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/requests/dismiss请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/requests/dismiss \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
为代理启用或禁用 Connected Apps
保存代理的 Connected Apps 开关，并将 PH_APPS_MCP_ENABLED Balena 设备变量推送到该设备（尽力而为；PH 端的标志才是 MCP 中继的硬性控制）。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。请求正文
端点
POST /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/enable请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/enable \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
开始将单个应用连接到代理（Connect Link OAuth 流程）
为一个工具包启动托管的 Connect Link 流程，并返回要将用户引导至的 URL。可选的别名用于标记新账户（多账户：连接已连接的应用会再添加一个账户，每个应用最多 10 个）。使用与套件连接相同的链式回调（视为只含一个工具包的套件），因此完成后会返回 ph-ai-agent 小程序页面。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。请求正文
端点
POST /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/connect请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/connect \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
单个应用的连接准备负载（模式、凭据字段、设置指南）
连接对话框在开始连接前所需的全部信息：应用的连接方式（oauth = 托管授权流程，credentials = 产品内表单）、credentials 模式下要收集的凭据字段，以及产品内设置指南（重点应用有专门编写的指南，其他应用则根据其字段元数据生成，绝不链接到外部文档）。自带 OAuth 应用还会包含客户的 OAuth 应用是否已为此代理注册（byoConfigured），以及需要在提供商处注册的重定向 URL。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。 toolkit `string` （必填）端点
GET /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/connect-info/{toolkit}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/connect-info/{toolkit} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
使用用户提供的凭据连接应用（API 密钥等，不使用 OAuth）
直接通过产品内表单为 credentials 模式的应用创建已连接账户，无需托管授权流程。凭据字段来自应用的 connect-info 负载；必须提供所有必填字段。在支持的情况下会向提供商验证凭据（尽力而为；某些应用只有在代理首次调用工具时才会拒绝错误的密钥）。可选的别名用于标记新账户（多账户：连接已连接的应用会再添加一个账户）。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。请求正文
端点
POST /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/connect-credentials请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/connect-credentials \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
为自带应用注册客户自己的 OAuth 应用并启动其连接流程
适用于自带 OAuth 应用（Xero、Shopify 等）：接收客户在提供商处创建的 OAuth 应用的客户端 ID 和客户端密钥（应用的设置指南会逐步说明），为此代理注册该应用（密钥仅存储在上游集成平台，绝不存储在 Performance Hub 中），并立即针对该应用启动托管登录流程。返回要将用户引导至的授权 URL，约定与连接端点相同。重新提交会替换代理已注册的应用（例如在轮换密钥后），现有的已连接账户仍可继续使用。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。请求正文
端点
POST /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/connect-oauth-app请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/connect-oauth-app \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
为代理启动一键套件连接（链式 Connect Link 流程）
为整个套件（例如 google-workspace）启动链式连接流程。返回的 URL 会打开第一个工具包的授权页面；每次完成后都会通过 302 直接跳转到下一个工具包的流程，最终返回 ph-ai-agent 小程序页面。已有已连接账户的成员会被跳过，因此在链中途失败后重试时，会从缺少的应用继续，而不会创建重复账户。当所有成员都已连接时，会再次运行完整的链，这就是明确的“添加另一个账户”流程。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。请求正文
端点
POST /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/connect-suite请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/connect-suite \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
断开代理的一个已连接账户
删除单个已连接账户（多账户：同一应用的其他账户仍保持连接）。删除前会验证该账户是否属于此代理；如果它是该应用的最后一个账户，则会从代理的已连接集合中移除该工具包（会话会延迟重建，以更新代理的工具列表）。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。请求正文
端点
POST /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/disconnect请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/disconnect \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
重命名（重新设置别名）代理的某个已连接账户
设置单个已连接账户的显示别名。别名通常在 OAuth 后自动设置（取自登录身份）；此端点用于应用详情对话框中的手动重命名。空别名会清除标签。在上游更新前会验证该账户是否属于此代理。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。请求正文
端点
POST /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/rename-account请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/rename-account \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
为代理开启或关闭 Performance Hub 内置服务
为此代理开启或关闭一项常开的内置服务（Smart Search、Weather 等）。内置服务无需连接或 OAuth，每个代理都包含这些服务且默认开启；此开关会保存针对该代理的覆盖设置，并立即重建代理的上游会话以更新工具集。请注意，单独的“External apps”开关（/enable 路由）是针对整个应用 MCP 服务器的硬性关闭开关；关闭时，无论各内置服务的单独开关如何，内置服务也都不可用。
参数
facilityId `string` （必填） deviceId `string` （必填） 代理设备的 balena UUID。 slug `string` （必填） 内置服务的 slug。请求正文
端点
PATCH /api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/built-in/{slug}请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/connected-apps/{facilityId}/{deviceId}/built-in/{slug} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
将人工智能代理设备关联到设施
以元数据优先的方式关联。在实时设备元数据中按序列号查找设备，要求设备在线，然后延迟创建注册记录，分配 Chisel 中继区域 + 隧道端口 + 密钥，在中继上注册该槽位，并通过 Balena 将设施和隧道配置推送到设备。新设备还会预置一个默认的 MCP 服务账户（已启用，范围限于此设施，具备所有功能）；重新配对会保留现有的 MCP 授权。可选的高级设置会在配对时覆盖预设的默认值（备份配置、MCP 开/关、访问限制），而 `restoreFrom` 会使用另一台设施设备的云备份初始化新设备（源设备可以是在用或已停用的；会将跨仓库恢复加入队列，并以 `restoreRequest` 返回以便轮询进度）。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/associate/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/associate/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
列出设施的人工智能代理设备
返回设施的人工智能代理设备及其实时在线和隧道状态（供小程序的设备切换器使用）。
参数
club `string` （必填）端点
GET /api/devices/ph-ai-agent/list/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/list/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
人工智能代理更新和在线状态
返回设备是否在线、是否有可用/待处理的更新，以及提供的发布版本（设备群固定版本时为固定版本；设备群跟踪最新版本时为最高的成功版本）。
参数
club `string` （必填） uuid `string` （必填）端点
GET /api/devices/ph-ai-agent/update-status/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/update-status/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
人工智能代理实时设备状态和指标
返回供小程序指标栏和管理抽屉使用的精选快照：标识和注册字段、存活和连接状态、软件版本，以及最新的心跳指标（CPU、温度、内存、各挂载点存储、运行时间、网络）。将设备元数据信标和 Balena 更新状态合并为扁平结构；临时中断时，任一部分都可能缺失。
参数
club `string` （必填） uuid `string` （必填）端点
GET /api/devices/ph-ai-agent/device-status/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/device-status/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
设备健康报告的 AI 说明
返回面向操作人员的简短说明，解释当前推导出的健康问题。事实和处理步骤始终位于 device-status 中；这段额外说明为尽力而为，可能为 null。
参数
club `string` （必填） uuid `string` （必填）端点
POST /api/devices/ph-ai-agent/health/{club}/{uuid}/explain请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/health/{club}/{uuid}/explain \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为人工智能代理生成直连中继的访问令牌
返回短期有效的签名 URL，浏览器使用它直接连接到设备所在区域的中继网关（省去经由全球 PH/悉尼的中转），另附 HS256 令牌。PH 仍是授权方（在此执行 Google SSO 及模块/设施检查）；中继网关负责验证令牌。/ai-agent-ui 代理仍作为后备方式。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/access/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/access/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
向人工智能代理会话发送聊天消息（通知内联回复）
供 Web 推送通知的内联回复操作使用的服务器端中继：service worker 向此处发送 POST 请求（同源，使用 SSO cookie），因此即使没有打开 Performance Hub 标签页也能回复。PH 解析设备的中继目标（与 /ai-agent-ui 代理的查找方式相同），添加 x-ph-user 以标记轮次归属（随后的完成推送会发回给此用户），并附带会话 ID 转发到设备的 /api/chat/start。
请求正文
端点
POST /api/devices/ph-ai-agent/reply请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/reply \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
读取人工智能代理的访问控制设置（所有者）
返回设备的访问设置（模式、允许列表、可见性、PH Support 开关）以及所有待处理的访问请求。设备所有者可读取；其他用户会收到 403。
参数
club `string` （必填） uuid `string` （必填）端点
GET /api/devices/ph-ai-agent/access-settings/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/access-settings/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新人工智能代理的访问控制设置（所有者）
写入模式（org/restricted）、受限允许列表、列表可见性（all/admins）以及“允许 Performance Hub Support 访问”开关。设备所有者可执行此操作。所有者本身只能通过 reallocate-owner 更改。已批准的访问请求是持久的：仍处于批准状态的请求者会被合并回已保存的允许列表；从提交的列表中移除某人会撤销其批准（请求变为 denied；对方可以再次申请）。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/access-settings/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/access-settings/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
重新分配人工智能代理的所有者
将设备所有权重新分配给另一位 Performance Hub 用户。仅限账户所有者（拥有 SaaS 计费模块访问权限）；这是受限代理的所有者离开时的应急手段。原所有者和新所有者都会收到通知（应用内 + 推送 + 电子邮件）。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/reallocate-owner/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/reallocate-owner/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
供人工智能代理允许列表/所有者选择器使用的设施用户列表
返回其角色可访问此设施的每位用户的电子邮件地址 + 姓名（+ isOrgAdmin 标志）。仅限设备所有者和重新分配者（账户所有者）使用，使普通用户无法枚举用户群。
参数
club `string` （必填） uuid `string` （必填）端点
GET /api/devices/ph-ai-agent/org-users/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/org-users/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
申请访问受限的人工智能代理
为受限设备创建（或重新打开）请求者的访问请求，按用户+设备保持幂等。所有者会通过应用内通知、Web 推送和电子邮件收到通知，并附带指向代理模块的深层链接。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/access-request/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/access-request/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
批准或拒绝人工智能代理访问请求（所有者）
由设备所有者处理待处理的请求。批准会将请求者添加到设备的允许列表；无论结果如何都会通知请求者（应用内 + 推送 + 电子邮件）。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/access-request-resolve/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/access-request-resolve/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
允许并应用人工智能代理更新
将设备固定到提供的发布版本（设备群固定版本，或在设备群跟踪最新版本时为最高的成功版本），并解除更新锁，使 balena supervisor 应用更新。设备数据卷上的状态在更新后会保留。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/update/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/update/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
安排稍后进行人工智能代理更新
在设备的注册记录中保存计划安装时间。计划时间过后，后端定期任务（每 5 分钟一次）会应用更新（固定版本 + 解锁）。新的安排会替换该设备现有的任何安排。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/update-schedule/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/update-schedule/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
取消已安排的人工智能代理更新
清除设备待执行的计划安装（如果没有任何安排，则不执行任何操作）。
参数
club `string` （必填） uuid `string` （必填）端点
DELETE /api/devices/ph-ai-agent/update-schedule/{club}/{uuid}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/update-schedule/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在人工智能代理设备上运行远程命令
向人工智能代理上运行的 device-controller 发布允许列表中的 MQTT 命令（重启、重启容器、锁定/解锁更新、Wi-Fi 管理）。设备必须已关联到该设施。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/command/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/command/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
更新人工智能代理面向设施的配置
保存关联人工智能代理中可由操作员编辑的设置：设备名称、设备的物理位置以及定时重启频率。重启计划还会作为 REBOOT_DEVICE Balena 环境变量（当地时间凌晨 2 点）推送到设备，与 Display Screens 设备的行为一致。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/config/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/config/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
此设施中的人工智能代理可移至的设施
返回已登录用户可访问的同一组织内的设施（不含当前设施），供“移至其他设施”选择器使用。实际移动由 POST /api/devices/move/:club 执行，该端点在服务器端执行相同的同组织及目标访问规则。
参数
club `string` （必填）端点
GET /api/devices/ph-ai-agent/move-targets/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/move-targets/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
请求者可为设施的人工智能代理授予的 MCP 访问范围
返回已登录用户在此设施所属组织中可授予人工智能代理 MCP 服务账户的内容：其自身访问范围内的设施/区域、是否可授予组织级范围、其持有的模块集合，以及完整的 MCP 工具目录（用于高级的逐工具掩码）。界面据此确保用户只能看到其自身权限范围内的选项；mcp-access POST 端点在服务器端执行相同的权限收窄。
参数
club `string` （必填）端点
GET /api/devices/ph-ai-agent/mcp-grantable/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/mcp-grantable/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取人工智能代理的 MCP 服务账户配置
返回设备的 MCP 访问配置（范围、模块、工具掩码、审计字段）。
参数
club `string` （必填） uuid `string` （必填）端点
GET /api/devices/ph-ai-agent/mcp-access/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/mcp-access/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
配置人工智能代理的 MCP 服务账户
保存设备的 MCP 访问配置，并在授予时收窄权限。请求者只能授予其自身访问范围内的设施/区域；只有持有组织级角色时才能授予组织范围；只能授予其本人在该设施所属组织中持有的模块。启用标志还会作为 PH_MCP_ENABLED Balena 环境变量推送到设备。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/mcp-access/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/mcp-access/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
获取人工智能代理的 VPN 配置（已脱敏）
返回设备的 VPN 支持标志和连接列表。从不返回配置文件正文和凭据值，只返回导入时的元数据（远程地址、路由、DNS）以及是否有凭据的标志。每个连接的实时状态来自设备状态端点（beacon metadata.vpn）。
参数
club `string` （必填） uuid `string` （必填）端点
GET /api/devices/ph-ai-agent/vpn-config/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/vpn-config/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
切换人工智能代理的 VPN 支持
开启或关闭设备的 VPN 功能。推送 PH_VPN_ENABLED balena 设备变量并通知设备（MQTT vpnConfigChanged）；关闭时保留连接（隧道停止，配置保留以便重新启用）。
参数
club `string` （必填） uuid `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/vpn-config/{club}/{uuid}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/vpn-config/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
将 OpenVPN 配置文件导入人工智能代理
接受 base64 编码的上传内容：单个 .ovpn/.conf 文件、拆分文件包（配置 + 证书/密钥）以及归档文件（.zip、.tar/.tgz Pritunl 导出、.tblk Tunnelblick、.visc/.visz Viscosity）。配置文件会被规范化为标准的内联格式；每个配置文件成为一个连接（导入时为未连接状态，输入凭据后再连接）。对无法使用的上传返回可操作的 400 错误。
参数
club `string` （必填） uuid `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/vpn-import/{club}/{uuid}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/vpn-import/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
更新人工智能代理的 VPN 连接（名称/凭据/分离 DNS）
更新已存储的连接。凭据字段为只写（省略 = 保留已存储的值；空字符串 = 清除）。凭据或分离 DNS 的更改会递增连接修订版本，使实时隧道使用新值重新启动。
参数
club `string` （必填） uuid `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/vpn-connection/{club}/{uuid}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/vpn-connection/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
删除人工智能代理的 VPN 连接
从注册记录中移除该连接并通知设备，设备随即拆除隧道并清除其缓存的配置文件/凭据。
参数
club `string` （必填） uuid `string` （必填） connectionId `string` （必填）端点
DELETE /api/devices/ph-ai-agent/vpn-connection/{club}/{uuid}/{connectionId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/vpn-connection/{club}/{uuid}/{connectionId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
连接或断开人工智能代理的 VPN 连接
期望状态模型：在注册记录上设置连接的启用标志并通知设备（无负载的 MQTT vpnConfigChanged）；设备通过其经 JWT 认证的 universal-api 调用拉取权威状态并协调其隧道。错过的通知会在定期同步时收敛。
参数
club `string` （必填） uuid `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/vpn-command/{club}/{uuid}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/vpn-command/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
获取人工智能代理的云备份配置及状态
返回设备的备份设置（启用、保留期、存储区域）、滚动备份状态（上次备份、大小、错误）、解析后的自动区域，以及选择器可用的存储区域。从不返回 restic 存储库密码。
参数
club `string` （必填） uuid `string` （必填）端点
GET /api/devices/ph-ai-agent/backup-config/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-config/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新人工智能代理的云备份配置
保存启用/保留期/区域设置。在设备下一次每小时备份周期时生效（设备每次运行前都会向 PH 请求运行上下文），因此无需重启设备。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/backup-config/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-config/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
列出用于配对新人工智能代理的备份恢复来源
添加代理对话框中“从备份恢复”选项的设施级视图：列出该设施中所有仍有可解密备份存储库且至少有一个可用恢复点的注册记录（包括活动的以及已停用/已替换的），并附带其最新快照。还会返回备份配置选项列表（allowedRetentionDays、availableRegions），因此对话框无需设备 UUID 即可填充其下拉列表。
参数
club `string` （必填）端点
GET /api/devices/ph-ai-agent/backup-sources/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-sources/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出人工智能代理的备份恢复点
从 DynamoDB 返回设备的快照索引（最新的在前），无需与设备或存储库往返通信，同时返回当前手动备份/恢复请求的状态，供抽屉面板轮询。过期的请求（从未被接收或没有进度心跳）会显示为失败，以便界面始终可以提交新请求。
参数
club `string` （必填） uuid `string` （必填）端点
GET /api/devices/ph-ai-agent/backup-snapshots/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-snapshots/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
立即为人工智能代理请求手动备份
将手动运行请求（附带用户备注）写入注册记录行，并通过 MQTT 通知设备。设备通过其经 JWT 认证的 universal-api 运行上下文调用获取经过验证的请求；即使没有 MQTT，也会在下一个调度周期被接收。如果另一个备份或恢复正在进行，则拒绝请求。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/backup-run/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-run/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
固定或取消固定人工智能代理的恢复点
已固定的恢复点不会被保留期清理删除：设备的夜间维护通过其运行上下文调用接收已固定的快照 ID，并将其排除在 restic forget 之外，而且其索引行永不因 TTL 过期。取消固定会恢复正常的保留行为。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/backup-pin/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-pin/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
从备份恢复点恢复人工智能代理
将恢复请求写入注册记录行并通知设备。完整恢复会覆盖 /data 和 /home/hermeswebui（设备会先自动创建一个恢复前的安全快照，并在恢复期间停止代理），并且需要输入设备名称进行确认。传入 `paths` 则改为仅对这些路径执行不中断服务的文件级恢复。可选择在数据恢复完成后将设备固定回该快照的软件版本（参见 backup-restore-release）。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/backup-restore/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-restore/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
应用已完成恢复中记录的软件版本
请求恢复快照软件版本的恢复流程的最后一步：设备报告数据恢复完成后，此操作将设备固定到已存储的版本并解锁更新（机制与更新端点相同）。由抽屉面板的轮询驱动；具有幂等性，应用后会清除已存储的固定信息。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/backup-restore-release/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-restore-release/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
浏览备份恢复点中的文件
列出 restic 快照中的一级目录，完全在服务器端从 Wasabi 存储库提供（设备离线时也可使用）。只读取目录树元数据，列出时不会下载任何文件数据。
参数
club `string` （必填） uuid `string` （必填） takenAt `number` （必填） path `string` （可选）端点
GET /api/devices/ph-ai-agent/backup-files/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-files/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在备份恢复点中搜索文件名
从某个目录向下进行不区分大小写的文件名搜索，在服务器端基于 restic 目录树元数据提供（不读取文件数据；设备离线时也可使用）。以流式方式返回列表，并在找到前 200 个匹配项时停止。
参数
club `string` （必填） uuid `string` （必填） takenAt `number` （必填） q `string` （必填） path `string` （可选）端点
GET /api/devices/ph-ai-agent/backup-search/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-search/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
两个备份恢复点之间的变化
在服务器端对设备的两个快照运行 restic diff（仅目录树元数据），返回新增/删除/修改的文件列表（上限 500 处更改）以及汇总统计信息。结果会被缓存，因为快照不可变。
参数
club `string` （必填） uuid `string` （必填） fromTakenAt `number` （必填） toTakenAt `number` （必填）端点
GET /api/devices/ph-ai-agent/backup-diff/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-diff/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
某个文件在所有恢复点中的版本历史
在服务器端对设备存储库中的每个快照执行一次 restic find，合并为不同的版本（连续相同的大小 + mtime 命中会被合并），并与快照索引行关联以获取日期/类型/备注。
参数
club `string` （必填） uuid `string` （必填） path `string` （必填）端点
GET /api/devices/ph-ai-agent/backup-file-versions/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-file-versions/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按文件名搜索设备备份的每个恢复点
已删除文件的恢复途径：在服务器端对存储库中的所有快照执行一次 restic find（不区分大小写，支持子字符串或通配符），按路径分组，并列出每个文件所在的恢复点。只要任何恢复点仍包含某个从设备中删除的文件，就仍可在此找到它。
参数
club `string` （必填） uuid `string` （必填） q `string` （必填）端点
GET /api/devices/ph-ai-agent/backup-find/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-find/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从备份恢复点下载单个文件
将单个文件直接从 restic 存储库以流式方式传输到浏览器（作为附件）。目录以 tar 归档形式流式传输。有大小上限；在服务器端提供，因此设备离线时也可使用。
参数
club `string` （必填） uuid `string` （必填） takenAt `number` （必填） path `string` （必填）端点
GET /api/devices/ph-ai-agent/backup-file-download/{club}/{uuid}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/backup-file-download/{club}/{uuid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从设施停用人工智能代理
参数
club `string` （必填）端点
POST /api/devices/ph-ai-agent/decommission/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/decommission/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从设施移除人工智能代理并将硬件恢复出厂设置
完全解除设备关联，使其可在任意设施中配对，并擦除 NUC 上的所有数据。擦除操作在云端拆除之前通过 PH_FACTORY_RESET balena 设备变量（一次性随机数）预先设定，因此即使移除时设备处于离线状态，该操作也会保留，并在设备下次连接时执行。MQTT factoryReset 通知可使在线设备立即执行。随后云端拆除会撤销所有凭据和授权，清除 Balena 设施绑定（设备变量 + club 标签）和元数据 clubID，并删除访问请求和 LAN DNS 记录。云备份会被保留：快照索引和存储库密码保留在已软删除的注册记录上，可在添加替换设备时用作恢复来源。需要输入设备名称进行确认。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/reset/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/reset/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
用新的 NUC 替换故障的人工智能代理（灾难恢复）
一次性设备替换：关联替换用的 NUC（隧道槽位、密钥、balena 变量、备份种子），沿用旧设备的名称、位置、重启计划、备份设置、访问阻止和 MCP 授权，将旧快照索引重新关联到新设备（使其完整备份历史仍可浏览），停用旧注册记录（标记 replacedBy / replacedFrom），并且除非 `restore` 为 false，否则会将所选恢复点从旧设备的备份存储库完整恢复到新硬件的任务加入队列。旧设备故障或离线时也可使用；需要输入旧设备的名称进行确认。仅限同一设施。
参数
club `string` （必填）请求正文
端点
POST /api/devices/ph-ai-agent/replace/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/devices/ph-ai-agent/replace/{club} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
将 Performance Hub 设备二维码短链接解析为其指向的深层链接，以便添加设备扫描器检测设备类型。只跟随 performancehub.co 主机。
参数
url `string` （必填） 扫描到的短链接端点
GET /api/devices/resolve-qr请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/resolve-qr \
-H "x-api-key: YOUR_API_KEY"
响应
{}
测试与设施 Unifi 控制器的连接以及凭据是否正确。
参数
facilityID `string` （必填） 要测试 Unifi 连接的设施的内部 ID端点
GET /api/devices/testUnifiController/{facilityID}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/devices/testUnifiController/{facilityID} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新与某个设施关联的通用 IoT 设备。
参数
club `string` （必填） 要更新设备的设施的内部 ID。 body `string` （必填） 更新参数的 JSON 对象。端点
PUT /api/devices/updateGenericDevice/{club}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/devices/updateGenericDevice/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据用户及其关联的俱乐部，列出尚未处理且需要操作的协议数量
端点
GET /api/agreements/agreements-outstanding请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agreements/agreements-outstanding \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出俱乐部可用的所有协议
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 contracts-sort `string` （可选） 按生效日期（date-effective）或字母顺序（alphabetical）对协议排序。默认为 date-effective。 contracts-acknowledgement `string` （可选） 按 all、acknowledged 或 unacknowledged 筛选协议。默认为 all。 contracts-requirement `string` （可选） 按 all、signature、checkbox、popup 或 none 筛选协议。默认为 all。 contracts-status `string` （可选） 按 all、active 或 archived 筛选协议。默认为 all。端点
GET /api/agreements/list-agreements/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/agreements/list-agreements/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据协议 ID 签署协议。
参数
club `string` （必填） 签署协议的俱乐部的内部 ID。 agreementid `string` （必填） 正在签署的协议的 ID。 body `string` （必填） 包含要添加/上传到系统的协议及参数的 JSON 对象……端点
POST /api/agreements/sign/{club}/{agreementid}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/agreements/sign/{club}/{agreementid} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
设施的 Model Router 摘要（配置、余额、支出）。
参数
clubID `string` （必填） tz `string` （可选） 查看者的 IANA 时区，在设施没有时区数据时用作按日/按月支出窗口的后备值。端点
GET /api/clubs/{clubID}/ai-credits/overview请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/overview \
-H "x-api-key: YOUR_API_KEY"
响应
{}
可用模型目录，附带每个设施的启用状态（默认全部启用）。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/ai-credits/models请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/models \
-H "x-api-key: YOUR_API_KEY"
响应
{}
可用的防护规则和 PH 预设模板。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/ai-credits/guardrails请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/guardrails \
-H "x-api-key: YOUR_API_KEY"
响应
{}
已连接的 Model Router 服务。包括已配对的人工智能代理设备、明确指定类型的外部代理以及设施的 Workflow 服务。配置通过 PATCH /keys/{keyHash} 编辑。
参数
clubID `string` （必填） tz `string` （可选） 查看者的 IANA 时区，在设施没有时区数据时用作按日/按月支出窗口的后备值。端点
GET /api/clubs/{clubID}/ai-credits/agents请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/agents \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为设施启用 Model Router 并开通其推理访问权限。
参数
clubID `string` （必填）端点
POST /api/clubs/{clubID}/ai-credits/enable请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/enable \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新套餐、模型允许列表、防护规则、内容过滤器（PH 端正则表达式脱敏/拦截）、支出限额和自动充值配置。
参数
clubID `string` （必填）端点
PATCH /api/clubs/{clubID}/ai-credits/config请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/config \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将累计硬上限计数器重置为 0（以当前支出为新基准），并将已结束的周期记录到历史中。
参数
clubID `string` （必填）端点
POST /api/clubs/{clubID}/ai-credits/spend-limit/reset-total请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/spend-limit/reset-total \
-H "x-api-key: YOUR_API_KEY"
响应
{}
硬上限重置历史（最新的在前），包括每个已结束周期的上限、已支出金额和时间戳。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/ai-credits/spend-limit/history请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/spend-limit/history \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为设施创建新的 phk_ API 密钥（明文仅返回一次）。可选择设置支出上限、模型允许列表、防护规则、内容过滤器以及 rpmLimit/tpmLimit 速率限制。
参数
clubID `string` （必填）端点
POST /api/clubs/{clubID}/ai-credits/keys请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/keys \
-H "x-api-key: YOUR_API_KEY"
更新可编辑的密钥字段：标签、每个密钥的支出上限、模型允许列表、防护规则、内容过滤器以及 rpmLimit/tpmLimit 速率限制（同步到该密钥）。
参数
clubID `string` （必填） keyHash `string` （必填）端点
PATCH /api/clubs/{clubID}/ai-credits/keys/{keyHash}请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/keys/{keyHash} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
设施的逐请求推理日志（实时，仅元数据）。
参数
clubID `string` （必填） page `string` （可选） pageSize `string` （可选） status `string` （可选） model `string` （可选） provider `string` （可选） source `string` （可选） `key` 或 `agent` keyHash `string` （可选） 按 PH keyHash 筛选单个密钥/代理。 q `string` （可选） 在请求 ID、密钥/代理标签、模型、提供商和最终用户中进行自由文本搜索。 minutes `string` （可选） 不足一天的时间窗口（例如 Live=1440）；会覆盖 startDate/endDate。 startTs `string` （可选） 时间窗口开始时间，以 Unix 秒数表示（点击缩放）；会覆盖 minutes/dates。 endTs `string` （可选） 时间窗口结束时间，以 Unix 秒数表示（点击缩放）；会覆盖 minutes/dates。端点
GET /api/clubs/{clubID}/ai-credits/logs请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/logs \
-H "x-api-key: YOUR_API_KEY"
响应
{}
Logs 视图中按时间统计请求的直方图。筛选条件与列表路由相同，但在服务器端汇总为时间桶（成功/失败计数），因此无论日志量多大，响应都很小。时间桶大小根据时间跨度自动选择。
参数
clubID `string` （必填） status `string` （可选） model `string` （可选） provider `string` （可选） source `string` （可选） keyHash `string` （可选） q `string` （可选） minutes `string` （可选） startDate `string` （可选） endDate `string` （可选） startTs `string` （可选） endTs `string` （可选）端点
GET /api/clubs/{clubID}/ai-credits/logs/histogram请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/logs/histogram \
-H "x-api-key: YOUR_API_KEY"
响应
{}
指定范围内的用量分析时间桶 + 各模型合计（实时）。
参数
clubID `string` （必填） range `string` （可选） 24h | 7 | 30 | 90 | year | all（如果提供了 startDate/endDate，则忽略此项） startDate `string` （可选） endDate `string` （可选） groupBy `string` （可选） model（默认）| key | source | provider | status：用于时间桶和分组的维度 subgroupBy `string` （可选） 可选的第二维度，嵌套在每个分组下（Explore） keyHash `string` （可选） 深入分析筛选条件：限定为单个密钥/代理 model `string` （可选） 深入分析筛选条件：限定为单个模型 provider `string` （可选） source `string` （可选） compare `string` （可选） 设为 "prev" 可同时返回 groupsPrev（紧邻的前一个等长周期）端点
GET /api/clubs/{clubID}/ai-credits/stats请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/stats \
-H "x-api-key: YOUR_API_KEY"
响应
{}
过去一年滚动周期的每日活动日历（GitHub 风格，约 53 周）。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/ai-credits/activity请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/activity \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从已保存的 SaaS 计费银行卡扣款，以充值 Model Router 预付额度。
参数
clubID `string` （必填） body `object` （可选）端点
POST /api/clubs/{clubID}/ai-credits/topup请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/topup \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在小程序完成 3DS 验证后完成充值。
参数
clubID `string` （必填）端点
POST /api/clubs/{clubID}/ai-credits/topup/confirm请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/topup/confirm \
-H "x-api-key: YOUR_API_KEY"
响应
{}
充值/自动充值将扣款的已保存 SaaS 计费银行卡摘要。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/ai-credits/payment-method请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/payment-method \
-H "x-api-key: YOUR_API_KEY"
响应
{}
设施的账本交易（最新的在前）。可按类型筛选（例如使用 `types=topup,adjustment` 查看资金变动历史，或使用 `types=charge-reconcile` 配合 `from`/`to` 查看某个月的用量扣费）。
参数
clubID `string` （必填） limit `integer` （可选） 最大行数（默认 50，最多 200） types `string` （可选） 以逗号分隔的交易类型（topup、charge-reconcile、refund、adjustment、trueup-shortfall） from `integer` （可选） 仅限 createdAt >= from 的交易（Unix 秒数） to `integer` （可选） 仅限 createdAt <= to 的交易（Unix 秒数）端点
GET /api/clubs/{clubID}/ai-credits/transactions请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/transactions \
-H "x-api-key: YOUR_API_KEY"
响应
{}
至少包含一笔所请求类型交易的不同 `YYYY-MM` 月份（UTC，最新的在前）。用于数据驱动的年/月筛选下拉列表，使界面仅提供确实有数据的周期。
参数
clubID `string` （必填） types `string` （可选） 以逗号分隔的交易类型（topup、charge-reconcile、refund、adjustment、trueup-shortfall）端点
GET /api/clubs/{clubID}/ai-credits/transactions/available-periods请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/transactions/available-periods \
-H "x-api-key: YOUR_API_KEY"
响应
{}
单笔 Model Router 交易的品牌 PDF 付款收据。
参数
clubID `string` （必填） txId `string` （必填）端点
GET /api/clubs/{clubID}/ai-credits/transactions/{txId}/receipt.pdf请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/transactions/{txId}/receipt.pdf \
-H "x-api-key: YOUR_API_KEY"
响应
{}
所选充值交易的品牌 PDF 付款收据合集，以 ZIP 格式提供。每个 ID 都必须是属于该设施的充值交易；用量扣费和管理员调整没有收据，会被拒绝。
参数
clubID `string` （必填） ids `string` （必填） 以逗号分隔的交易 ID（最多 50 个）端点
GET /api/clubs/{clubID}/ai-credits/transactions/receipts.zip请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/transactions/receipts.zip \
-H "x-api-key: YOUR_API_KEY"
响应
{}
设施用量扣费的按自然月（UTC）汇总，最新的在前。始终包含当月，并标记为 `isCurrentMonth`（月初至今）。
参数
clubID `string` （必填） months `integer` （可选） 回溯窗口月数（默认 12，最多 24；设置 `year` 时忽略） year `integer` （可选） 将汇总范围限定为一个 UTC 自然年（例如 2026）端点
GET /api/clubs/{clubID}/ai-credits/usage-statements请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/usage-statements \
-H "x-api-key: YOUR_API_KEY"
响应
{}
品牌月度用量对账单 PDF，汇总当月的用量扣费（每日小计 + 合计）。明确说明这不是发票或收据；用量扣费不会收取任何付款。
参数
clubID `string` （必填） month `string` （必填） UTC 自然月，`YYYY-MM`端点
GET /api/clubs/{clubID}/ai-credits/usage-statements/{month}/statement.pdf请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/usage-statements/{month}/statement.pdf \
-H "x-api-key: YOUR_API_KEY"
响应
{}
以 CSV 格式提供某个月的原始用量扣费明细（交易 ID、UTC 时间戳、金额、扣费后余额、累计支出快照），即与当月对账单合计相符的明细导出。
参数
clubID `string` （必填） month `string` （必填） UTC 自然月，`YYYY-MM`端点
GET /api/clubs/{clubID}/ai-credits/usage-statements/{month}/detail.csv请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/usage-statements/{month}/detail.csv \
-H "x-api-key: YOUR_API_KEY"
响应
{}
设施的用量/支出摘要（实时数据加已对账的账本）。
参数
clubID `string` （必填） tz `string` （可选） 查看者的 IANA 时区，在设施没有时区数据时用作按日/按月支出窗口的后备值。端点
GET /api/clubs/{clubID}/ai-credits/usage请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/ai-credits/usage \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将 AI Edge Processor 设备关联到俱乐部或更新关联
参数
body `string` （必填） 用于更新 AI Edge Processor 设备注册的 JSON 对象。端点
POST /api/ai-edge-processor/devices请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ai-edge-processor/devices \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将 AI Edge Processor 设备关联到俱乐部。优先根据元数据解析设备（以实时心跳为准），如果设备从未自行注册则补建注册记录，并清理重新配置硬件后遗留的过时注册记录。
参数
body `string` （必填） 用于更新 AI Edge Processor 设备注册的 JSON 对象。端点
POST /api/ai-edge-processor/devices/associate请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ai-edge-processor/devices/associate \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部中的 bbox 上传记录列表
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/bbox-timeline/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/bbox-timeline/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
摄像机数据库搜索索引
代理公开文档中的 camera-db 搜索索引（制造商、系列、型号、别名），添加网络摄像机时 Find my camera 对话框会使用它。在服务器端缓存 12 小时。
端点
GET /api/cctv/camera-db/search-index请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/camera-db/search-index \
-H "x-api-key: YOUR_API_KEY"
响应
{}
摄像机数据库制造商模板
代理公开文档摄像机数据库中单个制造商的 RTSP URL 模板和默认值。会验证 slug 以防止路径遍历。在服务器端缓存 12 小时。
参数
slug `string` （必填） 制造商 slug（例如 hikvision）端点
GET /api/cctv/camera-db/manufacturers/{slug}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/camera-db/manufacturers/{slug} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施的签到数据列表
参数
club `string` （必填） 要访问的俱乐部/设施的内部 ID。 startDate `string` （可选） 开始日期，格式为 YYYY-MM-DD endDate `string` （可选） 结束日期，格式为 YYYY-MM-DD timezone `string` （可选） 用于解析日期的时区（默认为 Australia/Brisbane） nextToken `string` （可选） 用于获取下一页的分页令牌端点
GET /api/cctv/check-ins/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/check-ins/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
检索 CCTV 前端或界面的配置
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/config/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/config/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取 CCTV 内容分发配置
返回 CCTV 客户端用于解析媒体资源的内容域名。该域名由 CONTENT_DOMAIN 环境变量决定，如未设置则回退为按阶段区分的默认值（生产环境使用 /cctv，其他阶段使用 /cctv-stg）。
端点
GET /api/cctv/content-config请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/content-config \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更改 CCTV 前端或界面的配置
参数
body `object` （必填） 要添加到系统中的新配置块的 JSON 对象。端点
PUT /api/cctv/config/:club/:section请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/cctv/config/:club/:section \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回 CCTV 存储提供商配置中可用存储桶地区的列表
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/bucket-region/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/bucket-region/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
重置未识别人脸集合
通过删除所有对象来重置设施的未识别 CompreFace 集合。DynamoDB 人员记录、人脸检测和 OpenSearch 时间线块不受影响。仅清除底层人脸识别数据。系统处理新的摄像机检测时，会自动创建新的影子档案。
参数
facilityId `string` （必填）端点
DELETE /api/cctv/config/{facilityId}/unidentified-collection请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/cctv/config/{facilityId}/unidentified-collection \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取未识别集合信息
返回设施未识别 CompreFace 集合中当前的对象数量。
参数
facilityId `string` （必填）端点
GET /api/cctv/config/{facilityId}/unidentified-collection-info请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/config/{facilityId}/unidentified-collection-info \
-H "x-api-key: YOUR_API_KEY"
响应
{}
通过流 URL（RTSP、HTTP、HTTPS）添加网络摄像机（OEM/IP 摄像机）
参数
body `string` （必填） 用于添加网络摄像机的 JSON 对象。端点
POST /api/cctv/devices/add-network-camera请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/devices/add-network-camera \
-H "x-api-key: YOUR_API_KEY"
响应
{}
向 Edge Processor 批量添加网络摄像机
将多个 RTSP/HTTP 网络摄像机注册到一台 Edge Processor，然后只推送一次 FEED_CONFIG，使设备只重新加载一次配置。
参数
body `object` （必填）端点
POST /api/cctv/devices/add-network-cameras请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/devices/add-network-cameras \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将设备关联到俱乐部或更新关联
参数
body `string` （必填） 用于更新 CCTV 设备注册的 JSON 对象。端点
POST /api/cctv/devices请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/devices \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将设备关联到俱乐部
参数
body `string` （必填） 用于更新 CCTV 设备注册的 JSON 对象。端点
POST /api/cctv/devices/associate请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/devices/associate \
-H "x-api-key: YOUR_API_KEY"
响应
{}
向特定设备 UUID 发送 MQTT 请求，并期望（通过 websocket）收到包含摄像机可用功能的响应。
参数
club `string` （必填） 拥有所查询设备的俱乐部的内部 ID。 body `string` （必填） 更新参数的 JSON 对象。端点
POST /api/cctv/devices/list-camera-capabilities/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/devices/list-camera-capabilities/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设备注册
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/devices/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/devices/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将网络摄像机标记为已删除并从 Edge Processor 的 FEED_CONFIG 中移除，从而移除该摄像机
参数
club `string` （必填） 拥有该设备的俱乐部的内部 ID。 balenaUUID `string` （必填） 要移除的网络摄像机的 UUID。端点
DELETE /api/cctv/devices/remove-network-camera/{club}/{balenaUUID}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/cctv/devices/remove-network-camera/{club}/{balenaUUID} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
保存已配置的任意/全部摄像机功能，并（通过 balena）将其作为环境变量应用到设备
参数
club `string` （必填） 拥有所查询设备的俱乐部的内部 ID。 body `string` （必填） 更新参数的 JSON 对象。端点
POST /api/cctv/devices/save-camera-capabilities/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/devices/save-camera-capabilities/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
保存摄像机的运动遮罩（如已配置），并（通过 balena）将其作为环境变量应用到设备
参数
club `string` （必填） 拥有所查询设备的俱乐部的内部 ID。 body `string` （必填） 摄像机遮罩的 JSON 对象。端点
POST /api/cctv/devices/save-camera-mask/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/devices/save-camera-mask/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
向物理设备发送特定的 v4l2 命令（例如亮度或对比度）
参数
club `string` （必填） 拥有所查询设备的俱乐部的内部 ID。 body `string` （必填） 更新参数的 JSON 对象。端点
POST /api/cctv/devices/set-camera-capability/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/devices/set-camera-capability/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
测试网络摄像机流 URL
向 Edge Processor 发送测试命令，使用 ffprobe 验证摄像机流 URL
请求正文
端点
POST /api/cctv/devices/test-stream请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/devices/test-stream \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
从数据库中永久删除单条人脸检测记录。用于从某人的活动日志中移除匹配错误或不正确的轨迹条目。
参数
club `string` （必填） fdID `string` （必填）端点
DELETE /api/cctv/face-detections/:club/:fdID请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/cctv/face-detections/:club/:fdID \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回某人的人脸检测数据列表
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 personID `string` （必填） 人脸识别系统中的人员 ID端点
GET /api/cctv/face-detections/:club/:personID请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/face-detections/:club/:personID \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回引用指定人员裁剪图像的人脸检测，通过 personCropImage GSI 查询。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 personCropImage `string` （必填） 存储在人脸检测记录中的人员裁剪图像 URL。 limit `string` （可选） 要返回的最大检测数量。 nextToken `string` （可选） 来自上一个响应的分页令牌。端点
GET /api/cctv/face-detections-by-person-crop-image/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/face-detections-by-person-crop-image/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部的人脸检测数据列表，按相对于当前时间的范围分组
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/face-detections/:club/timeline请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/face-detections/:club/timeline \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部的人脸检测数据列表
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/face-detections/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/face-detections/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
使用 OpenSearch 搜索设施中的人脸检测时间线块
参数
facilityId `string` （必填） 要搜索的设施的内部 ID timezone `string` （必填） 用于日期转换的 IANA 时区（例如 Pacific/Auckland） startDate `string` （可选） 开始日期筛选条件（YYYY-MM-DD），根据时区转换为 startUnix endDate `string` （可选） 结束日期筛选条件（YYYY-MM-DD），根据时区转换为 endUnix personId `string` （可选） 按特定人员 ID 筛选 query `string` （可选） 自由文本搜索（例如人员姓名） limit `string` （可选） 每页结果数（默认 20，最多 100） filters `string` （可选） JSON 编码的筛选条件对象（例如 {"matchType":"identified"}） sortBy `string` （可选） 排序字段（startUnix、endUnix、created）。默认为 endUnix。 page `string` （可选） 分页页码（默认 1） sortOrder `string` （可选） 排序方向（asc 或 desc）。默认为 desc。端点
GET /api/cctv/search/face-detections/timeline-blocks/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/search/face-detections/timeline-blocks/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回关于俱乐部设施的报告列表
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/facility/:club/reports请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/facility/:club/reports \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按需触发热力图生成。调用与计划定时任务相同的 Starter 逻辑， 但允许指定特定设施、 日期/时间和一组周期。 不带正文调用时，行为与定时任务完全相同：扫描所有 符合条件的设施，并将每台设备加入队列。
请求正文
端点
POST /api/cctv/heatmaps/generate请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/heatmaps/generate \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
解析单台设备合成的滚动窗口热力图 PNG 的位置。仅返回 JSON 元数据；PNG 字节 存放在内容域名上，前端按以下格式构造 URL： `${contentDomain}/cctv/${storageService}/${region}/${filePath}?s=${token}` 解析顺序： 1. 命中 DynamoDB `composed#…` 索引 → 立即返回（约 10 ms）。 2. 对确定性缓存键执行 Wasabi HEAD。命中时写入一条 补建索引记录并返回。 3. 过时回退：此（设备、范围、小时）组合存在任何 合成记录，即使来自不同日期。 立即返回并附带 `cache: 'HIT-STALE'`，使前端 能先显示内容。同时异步触发新的合成。 4. 冷路径：完全不存在记录。通过 `InvocationType: 'Event'` 将合成 Lambda 加入队列，端点 返回 `202 { cache: 'PENDING' }`。前端轮询，直到 记录生成（通常需要 3-5 秒）。 当天处理：当 `endDate` 为设施当地的“今天”时， 端点改为提供昨天的 PNG，因为今天的切片 仍在由 Starter 定时任务写入，此时新的 合成将不完整。响应会回显 请求的 `endDate`，并包含 `endDateUsed`（= 昨天）。 `cache` 枚举： - `HIT`：从 DDB 索引提供所请求日期的数据。 - `HIT-FALLBACK`：请求的是今天；提供昨天的索引记录。 - `HIT-BACKFILL`：DDB 未命中但 Wasabi 中有该 PNG；记录 刚刚写入。 - `HIT-FALLBACK-BACKFILL`：在昨天回退时进行了补建。 - `HIT-STALE`：所请求日期没有记录，但此组合存在 其他日期的记录；立即提供该记录， 同时在后台将新的合成加入队列。 - `PENDING`：完全没有记录；合成已加入队列。前端 应轮询。响应为 `202 Accepted`，不含 `filePath`。
参数
facilityId `string` （必填） deviceUUID `string` （必填） 要合成的设备。合成按设备进行。 hour `integer` （必填） 在回溯窗口内要合成的一天中的小时（0–23）。 endDate `string` （可选） 窗口中的最后日期（YYYY-MM-DD）。默认为今天（设施时区）。 range `string` （可选） 回溯窗口。必须是允许列表中的范围之一。 nocache `integer` （可选） 设为 `1` 可绕过 DDB + HEAD 缓存层并强制重新合成。端点
GET /api/cctv/heatmaps/hourly/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/heatmaps/hourly/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
查找某台设备在滚动回溯窗口内，一天中哪些小时有 `1h` 切片记录。前端在调用合成端点 （`/api/cctv/heatmaps/hourly/...`）之前，使用它来填充小时选择器， 与日期 + 范围选择器配合使用。 示例： `GET /api/cctv/heatmaps/query-hourly/Birkdale?deviceUUID=abc123&endDate=2026-04-16&range=30d` 内部实现：对 `cctvheatmaps` 执行一次 DynamoDB 范围查询 （`sk BETWEEN 1h#{start}-00 AND 1h#{end}-23`），按小时分组。 每个至少有一个切片的小时返回一个条目，其中包括 一张有代表性的参考 JPEG（取自窗口中最近的一天， 参考图按设备按天共享）。
参数
facilityId `string` （必填） deviceUUID `string` （必填） 要查询的设备。每小时切片按设备区分。 endDate `string` （可选） 窗口中的最后日期（YYYY-MM-DD）。默认为今天（设施时区）。 range `string` （可选） 回溯窗口。必须是允许列表中的范围之一。端点
GET /api/cctv/heatmaps/query-hourly/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/heatmaps/query-hourly/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
查询设施预先生成的热力图记录。 **某种周期类型的所有记录：** - `/api/cctv/heatmaps/Birkdale?periodType=1y` - `/api/cctv/heatmaps/Birkdale?deviceUUID=abc123&periodType=1d` **日期范围（单一周期类型）：** - `/api/cctv/heatmaps/Birkdale?periodType=1d&from=2026-03-01&to=2026-03-31` - `/api/cctv/heatmaps/Birkdale?periodType=6h&from=2026-03-31&to=2026-03-31` **日期范围（所有适用的周期类型，省略 periodType）：** - `/api/cctv/heatmaps/Birkdale?from=2026-03-01&to=2026-03-31` 返回与指定范围重叠的年度、半年度、季度等记录， 直至 6h 记录。 **时间点（一台设备的全部 9 种周期类型）：** - `/api/cctv/heatmaps/Birkdale?deviceUUID=abc123&date=2026-03-15T14:30` 最多返回 9 条记录（1y、6m、3m、2m、1m、1w、1d、12h、6h）。
参数
facilityId `string` （必填） 设施标识符。 deviceUUID `string` （可选） 查询特定设备。省略时查询所有设备（GSI）。 periodType `string` （可选） 筛选为单一周期类型。如果与 from/to 一起使用时省略，则查询所有类型。 from `string` （可选） 开始日期（yyyy-mm-dd）。必须与 `to` 一起使用。 to `string` （可选） 结束日期（yyyy-mm-dd）。必须与 `from` 一起使用。 date `string` （可选） 时间点查询（yyyy-mm-dd 或 yyyy-mm-ddTHH:mm）。需要 deviceUUID。每种周期类型返回一条记录。端点
GET /api/cctv/heatmaps/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/heatmaps/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取设备直播缩略图
参数
club `string` （必填） 俱乐部的内部 ID。 deviceId `string` （必填） CCTV 设备的内部 ID。端点
GET /api/cctv/livestream/:club/thumbnail/:deviceId请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/livestream/:club/thumbnail/:deviceId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
通知 CCTV 系统您将观看直播
参数
club `string` （必填） 俱乐部的内部 ID。 deviceId `string` （必填） CCTV 设备的内部 ID。端点
POST /api/cctv/livestream/:club/iswatching/:deviceId请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/livestream/:club/iswatching/:deviceId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
批准交叉匹配
将匹配状态设为 confirmed 并记录审核者。
参数
club `string` （必填） matchId `string` （必填）端点
POST /api/cctv/matching/{club}/detail/{matchId}/approve请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/matching/{club}/detail/{matchId}/approve \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取单个交叉匹配及到访详情
返回匹配记录及其每次到访的时间明细。
参数
club `string` （必填） matchId `string` （必填）端点
GET /api/cctv/matching/{club}/detail/{matchId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/matching/{club}/detail/{matchId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
手动将未匹配的人员关联到会员
将 CCTV personId 与特定会员关联，并将匹配设为 confirmed。
参数
club `string` （必填） matchId `string` （必填）请求正文
端点
POST /api/cctv/matching/{club}/detail/{matchId}/link请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/matching/{club}/detail/{matchId}/link \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
列出设施的交叉匹配
返回按状态筛选的分页匹配结果。
参数
club `string` （必填） status `string` （可选） limit `integer` （可选） nextToken `string` （可选）端点
GET /api/cctv/matching/{club}/list请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/matching/{club}/list \
-H "x-api-key: YOUR_API_KEY"
响应
{}
拒绝交叉匹配
将匹配状态设为 rejected 并记录审核者。
参数
club `string` （必填） matchId `string` （必填）端点
POST /api/cctv/matching/{club}/detail/{matchId}/reject请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/matching/{club}/detail/{matchId}/reject \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取交叉匹配汇总计数
返回设施按状态分组的匹配计数。
参数
club `string` （必填） 设施 ID端点
GET /api/cctv/matching/{club}/summary请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/matching/{club}/summary \
-H "x-api-key: YOUR_API_KEY"
响应
{}
取消关联自动学习的档案匹配
将已关联的匹配恢复为 rejected 状态，并清除会员记录上的 autoLearnedFrom。
参数
club `string` （必填） matchId `string` （必填）请求正文
端点
POST /api/cctv/matching/{club}/detail/{matchId}/unlink请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/matching/{club}/detail/{matchId}/unlink \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
读取进行中的“插入或更新已识别人员”操作（涵盖创建和编辑）的状态。直接从 cctv-rekognition-api 所属的 `people-ops` 表读取记录，无需经过 Lambda。CCTV 前端在调用 POST /api/cctv/people/{facility}/identified 后使用它轮询进度。 该路径与 `/cctv/people/...` 同级（而非嵌套在其下），因此 express 路由器不会将 `operationId` 误匹配为 `/cctv/people/:club/:personID` 中的 `:personID`。请参阅 createAPIRouter 的 glob 顺序。 在 upsertIdentifiedPerson Lambda 尚未写入第一个阶段条目时（冷启动期间），返回 `pending` 占位符。前端轮询钩子对占位符和 pending 的处理相同，因此可为调用方保持稳定的约定。
参数
operationId `string` （必填）端点
GET /api/cctv/people-operations/{operationId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/people-operations/{operationId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将人脸图像（来自现有的轨迹检测）添加到该人员的 CompreFace 识别对象中，并在影子照片表中存储引用。不会将图像上传到 Wasabi，因为它已作为人脸检测截图存在于其中。
参数
club `string` （必填） personID `string` （必填） body `string` （必填）端点
POST /api/cctv/people/:club/:personID/add-face请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/people/:club/:personID/add-face \
-H "x-api-key: YOUR_API_KEY"
响应
{}
向人员记录添加影子照片
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 personID `string` （必填） 人员的记录 ID body `string` （必填） 要添加到系统中的新配置块的 JSON 对象。端点
POST /api/cctv/people/:club/shadow-photos/:personID请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/people/:club/shadow-photos/:personID \
-H "x-api-key: YOUR_API_KEY"
响应
{}
查询人员的影子照片
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 personID `string` （必填） 人员的记录 ID端点
GET /api/cctv/people/:club/shadow-photos/:personID请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/people/:club/shadow-photos/:personID \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从 CCTVShadowPhotosTable 中永久移除影子照片记录，并从 CompreFace 中移除相应的人脸（如果存储了 faceId）。
参数
club `string` （必填） personID `string` （必填） id `string` （必填） 影子照片记录 ID（主键）端点
DELETE /api/cctv/people/:club/shadow-photos/:personID/:id请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/cctv/people/:club/shadow-photos/:personID/:id \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按 personID 删除引用及关联的 rekognition 记录
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 personID `string` （必填） CCTV 人员的唯一 ID。端点
DELETE /api/cctv/people/:club/:personID请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/cctv/people/:club/:personID \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部的人员记录
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 personID `string` （必填） 人员的数据库 ID。端点
GET /api/cctv/people/:club/:personID请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/people/:club/:personID \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取与人员会员档案匹配的访问区域
解析该人员的会员类型、标签和会员计划，然后返回根据包含/排除规则匹配的实际访问区域（origin=membership-plan，未被吸收）。每个区域的 accessRestriction 仅保留与该人员匹配的规则。子区域的摄像机会合并到父区域。
参数
club `string` （必填） 设施的内部 ID personID `string` （必填） CCTV 人员表中的人员 ID端点
GET /api/cctv/people/{club}/{personID}/allowed-zones请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/people/{club}/{personID}/allowed-zones \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回合并任务的当前状态，包括每个来源的结果。状态为 IN_PROGRESS 时，请每 3-5 秒轮询一次此端点。
参数
club `string` （必填） mergeJobID `string` （必填）端点
GET /api/cctv/people/:club/merge-status/:mergeJobID请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/people/:club/merge-status/:mergeJobID \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在后台将多个未识别人员档案合并为一个保留档案。立即返回 202 及 mergeJobID。轮询 /merge-status/:mergeJobID 以获取进度。
参数
club `string` （必填） body `string` （必填）端点
POST /api/cctv/people/:club/merge-unidentified请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/people/:club/merge-unidentified \
-H "x-api-key: YOUR_API_KEY"
将人脸添加到设施的黑名单集合
参数
facilityId `string` （必填） 设施的内部 ID请求正文
端点
POST /api/cctv/people/{facilityId}/blacklist请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/people/{facilityId}/blacklist \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
在设施中插入或更新已识别人员：创建新记录或更新现有记录。代理到 upsertIdentifiedPerson Lambda，由其写入人员记录、将提供的照片上传到 Wasabi，并在 CompreFace 中重新索引人脸。 当 `isNewRecord` 为 true（默认）时，Lambda 运行创建分支（cctvPeople.save），如果未提供 `personID` 则会自动生成。当 `isNewRecord` 为 false 时，Lambda 运行更新分支（cctvPeople.update），此时 `personID` 为必填项，且必须对应现有记录。
参数
facilityId `string` （必填）请求正文
端点
POST /api/cctv/people/{facilityId}/identified请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/people/{facilityId}/identified \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
更新同步到设施 CCTV 人员表中的可选合作伙伴字段集。
参数
facilityId `string` （必填） 设施的内部 ID请求正文
端点
PUT /api/cctv/people/{facilityId}/sync-fields请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/cctv/people/{facilityId}/sync-fields \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
返回俱乐部的人员数据列表
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/people/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/people/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按人脸图像搜索设施中的人员。使用上传的 base64 图像和路径中的设施 ID 调用 cctv-rekognition-api 的 imageFaceSearch Lambda。返回排序后的匹配结果以及 DeepFace 属性摘要。
参数
club `string` （必填） 设施/俱乐部 ID body `string` （必填）端点
POST /api/cctv/people/{club}/search-by-face请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/people/{club}/search-by-face \
-H "x-api-key: YOUR_API_KEY"
响应
{}
使用 OpenSearch 搜索设施中的人员
参数
facilityId `string` （必填） 要搜索的设施的内部 ID query `string` （可选） 搜索词（例如姓名） page `string` （可选） 页码（默认 1） limit `string` （可选） 每页结果数（默认 20，最多 100） filters `string` （可选） JSON 编码的筛选条件对象（例如 {"membershipStatus":"active"}） sortBy `string` （可选） 排序字段（created、lastName、firstName、membershipUpdatedOn）。默认为 created。 sortOrder `string` （可选） 排序方向（asc 或 desc）。默认为 desc。端点
GET /api/cctv/search/people/:facilityId请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/search/people/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
使用新的 personID 更新人脸检测项，并关联 rekognition 记录
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 body `string` （必填） 要添加到系统中的新配置块的 JSON 对象。端点
POST /api/cctv/people/:club/validate请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/people/:club/validate \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回包含俱乐部 CCTV 录像数据所有可用筛选条件的对象
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/recordings/filters/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/recordings/filters/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
流式播放录像。
端点
GET /api/cctv/recordings/:club/:dir/:filename请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/recordings/:club/:dir/:filename \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新录像信息。
端点
PUT /api/cctv/recordings/:club/:dir/:filename请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/cctv/recordings/:club/:dir/:filename \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部 CCTV 录像数据的摘要
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/recordings/:club/summary请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/recordings/:club/summary \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据相对于当前时间的范围，返回俱乐部的 CCTV 录像数据列表
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/recordings/:club/timeline请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/recordings/:club/timeline \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部的 CCTV 录像数据列表
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/recordings/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/recordings/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
录像会在设定的期限后自动删除，使用此功能可保留录像
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
POST /api/cctv/recordings/:club/:action请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/recordings/:club/:action \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在日期范围内搜索设施的报告快照
参数
facilityId `string` （必填） 设施的内部 ID startDate `string` （必填） 开始日期筛选条件（YYYY-MM-DD） endDate `string` （必填） 结束日期筛选条件（YYYY-MM-DD） deviceIds `string` （可选） 用于筛选的摄像机/设备 ID 列表，以逗号分隔 view `string` （可选） 要计算的备选报告视图（转发给报告 Lambda）端点
GET /api/cctv/reports/search-report-snapshots/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/reports/search-report-snapshots/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
对设施已索引的 CCTV 媒体进行向量搜索。以 searchAnything Lambda 中继的 text/event-stream 作为响应，使客户端能在冷容器加载编码器期间显示进度。事件依次为 `status`，然后是 `result` 或 `error`。共有三种查询方式，其中两种使用此 HTTP 方法。发送 `query` 可按自由文本搜索。发送 `seedIndex` + `seedKey` 可按示例搜索（“更多类似结果”），即使用索引中已有记录的向量，这样可以找到更多与用户正在查看的结果相似的内容。如需按用户已有的图像搜索，请改为将字节 `POST` 到同一路径。同时发送文字和图片可以用一方缩小另一方的范围：**文本筛选，图像排序**。候选项来自种子，文字决定哪些候选项保留，视觉相似度决定顺序，因此结果仍与图片相似，而文字会剔除不匹配的结果。两者永远不会混合成一个向量，因此组合搜索的 `queryKind` 仍为 `similar`；结果中存在 `query` 即表示应用了文本筛选。组合搜索经常会没有结果，应将其视为一种单独的情况：`perIndex.
参数
facilityId `string` （必填） 要搜索的设施的内部 ID query `string` （可选） 要查找内容的自由文本描述。除非发送了 warm=1 或种子，否则为必填项。与种子一起使用时，它不再是排序对象，而是成为种子候选项的筛选条件，丢弃文本分数低于索引相关性阈值的候选项。 seedIndex `string` （可选） 按示例而非文本搜索：种子记录所在的索引（person-crops、recording-frames、timelapse-frames）。即用户点击的命中项的 `index`。必须与 seedKey 一起发送。 seedKey `string` （可选） 种子记录的 `key`，原样取自命中项。种子本身会从结果中排除；对于录像，这意味着排除整个片段，因为其他帧间隔 2 秒且几乎相同。 seedFrameId `string` （可选） 当 seedIndex 为 recording-frames 时必填：该索引为每个采样帧存储一条记录，且它们共享片段的键，因此仅凭键只能指定片段而非某个时刻。请发送命中项的 `frameId`。较旧的记录没有该值，请改为发送 seedOffsetMs。 seedOffsetMs `string` （可选） 适用于记录早于 `frame_id` 的 recording-frames 种子的后备帧标识符。请发送命中项的 `offsetMs`。提供 seedFrameId 时忽略此项。 warm `string` （可选） 在不运行搜索的情况下预热 Lambda 容器。请在页面加载时调用。 warmTarget `string` （可选） `warm` 加载哪个编码器：`text`（默认）、`image` 或 `both`。视觉塔为 355 MB，文本塔为 283 MB，因此预热视觉塔需要主动选择；仅在用户确实准备好图片后才请求 `image`，而不是在页面加载时。 index `string` （可选） 要搜索的数据集，以逗号分隔：person-crops、recording-frames、timelapse-frames。结果会合并为一个按分数排序的列表。默认搜索全部三个；传入明确的列表可缩小范围。timelapse-frames 涵盖不录像、每分钟仅生成一帧的摄像机，其相关性阈值尚未校准。 model `string` （可选） 用于查询的编码器。必须与索引该数据集时使用的编码器一致。 limit `string` （可选） 每个索引返回的结果数（默认 50，最多 100），并非总数，因此搜索全部三个索引最多可返回此数量的三倍。对于录像，计数的是片段而非匹配帧。 from `string` （可选） 仅匹配在此时间或之后拍摄的媒体，以 Unix 毫秒数表示。请注意这是拍摄时间，而非上传时间。 to `string` （可选） 仅匹配在此时间之前（不含）拍摄的媒体，以 Unix 毫秒数表示。 cameraId `string` （可选） 用于缩小范围的摄像机 balenaUUID，以逗号分隔，即 /api/cctv/recordings/filters/:club 返回的每个条目的 `balenaUUID` 字段。这是首选的摄像机筛选条件：所有索引都存储相同的值，因此一个筛选条件即可缩小所有索引的范围。请注意，只有人脸检测关联已解析的裁剪图才带有该值（目前约 1%），因此在裁剪图补建运行之前，按摄像机筛选裁剪图返回的结果很少或没有；录像数据完整，可精确筛选。 camera `string` （可选） 用于缩小范围的摄像机名称，以逗号分隔。实际上仅适用于录像：person-crops 在每条记录中存储的摄像机名称都为空，因此此处的任何值都会排除所有裁剪图。建议使用 cameraId。 cameraGroup `string` （可选） 用于缩小范围的摄像机组，以逗号分隔。所有录像都有该值，但只有约 1% 的裁剪图有，原因与 cameraId 相同。 minScore `string` （可选） 覆盖用于过滤噪声的各索引余弦阈值。生产环境中请省略；每个索引都有已校准的默认值（种子搜索另有一个未校准的默认值）。调试相关性时传入 0 可查看未经过滤的最近邻结果。端点
GET /api/cctv/search/anything/:facilityId请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/search/anything/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按用户已有的图像搜索，而非按文字或屏幕上已有的结果搜索。其他方面与 GET 完全相同（相同的查询参数、相同的事件流、相同的结果格式），因此这里只说明不同之处。将**原始文件字节**作为请求正文发送，并使用 `image/*` Content-Type。请勿先在浏览器中调整大小、裁剪或重新编码：服务器会严格匹配构建索引向量时使用的特定缩放方式（使用抗锯齿双线性内核压缩为 256x256），而 canvas 缩放使用的是另一种方式。经测量，这种替换会使结果与正确答案相差约 0.93 余弦距离，比两张确实不同的图像之间的差距还大，因此返回的结果排序看似合理但实际错误，且不会报错。大小限制为 4 MB，这是传输限制而非质量限制：字节通过 Lambda 调用负载传输，其上限为 6 MB，而 base64 会使其增大三分之一。结果按图像到图像评分，因此 `queryKind` 为 `image`，分数与种子搜索处于同样高得多的尺度，永远不能与文本分数比较。分数通常会略*低于*等效的种子搜索：种子的向量由设备自身写入，而上传的图像在此处由另一个引擎重新编码，结果会与设备生成的位置相差百分之几。经测量，尽管如此结果质量相同，只是结果集并不完全一致。添加 `query` 会按这些文字筛选结果，与种子搜索完全相同。同时发送种子*和*图像会被拒绝：两者都是排序对象，组合在一起没有意义。这是该端点处理的最耗费资源的请求。上传图像会加载视觉塔，添加文字还会加载文本塔，且都在冷容器上进行。用户准备好图片后调用一次 `warm=1&warmTarget=image`，即可将其移出关键路径。
参数
facilityId `string` （必填） 要搜索的设施的内部 ID body `string` （必填） 原始图像字节，未经修改，最大 4 MB query `string` （可选） 可选的文字，用于缩小图像结果范围，丢弃文本分数低于索引相关性阈值的匹配项。端点
POST /api/cctv/search/anything/:facilityId请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/search/anything/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部 CCTV 的存储详细信息及其他指标数据
端点
GET /api/cctv/storage-details/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/storage-details/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部的延时摄影上传记录列表
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/timelapse/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/timelapse/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出用户在 CCTV 前端或界面中对录像执行的操作
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/cctv/ui/actions/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/ui/actions/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
记录用户在 CCTV 前端或界面中对录像执行的操作
参数
body `string` （必填） 要添加到系统中的新配置块的 JSON 对象。端点
POST /api/cctv/ui/actions/:club请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/ui/actions/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取 CCTV 前端或界面的用户令牌
参数
club `string` （必填） 俱乐部 ID端点
GET /api/cctv/ui/token/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/ui/token/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
生成用于临时访问或访客访问的令牌
参数
club `string` （必填） 俱乐部的唯一标识符。 body `string` （必填） 要发放的令牌详细信息的 JSON 对象。端点
POST /api/cctv/token/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/cctv/token/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{
"accessID": "00000000-0000-0000-0000-000000000014"
}
返回临时访问或访客访问令牌的记录列表
参数
club `string` （必填） 俱乐部的唯一标识符。端点
GET /api/cctv/token/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/cctv/token/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
通过访问 ID 获取访问令牌
参数
accessID `string` （必填） 数据库中令牌记录的 ID。端点
POST /guest/cctv/token/:accessID请求示例
curl -X POST https://portal.hub.gymsystems.co/guest/cctv/token/:accessID \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除设施访问时段
参数
facilityId `string` （必填） body `object` （必填） 新访问时段的 JSON 对象。端点
DELETE /api/ai/computer-vision/access-hours/:facilityId请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/ai/computer-vision/access-hours/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施访问时段列表
参数
facilityId `string` （必填）端点
GET /api/ai/computer-vision/access-hours/:facilityId请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ai/computer-vision/access-hours/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新或创建设施访问时段
参数
facilityId `string` （必填） body `object` （必填） 新访问时段的 JSON 对象。端点
POST /api/ai/computer-vision/access-hours/:facilityId请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ai/computer-vision/access-hours/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除设施访问区域
参数
facilityId `string` （必填） body `object` （必填） 新访问区域的 JSON 对象。端点
DELETE /api/ai/computer-vision/access-zones/:facilityId请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/ai/computer-vision/access-zones/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施访问区域列表
参数
facilityId `string` （必填）端点
GET /api/ai/computer-vision/access-zones/:facilityId请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ai/computer-vision/access-zones/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新或创建设施访问区域
参数
facilityId `string` （必填） body `object` （必填） 新访问区域的 JSON 对象。端点
POST /api/ai/computer-vision/access-zones/:facilityId请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ai/computer-vision/access-zones/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回组织内所有品牌和设施的管理模块 ID 的并集，以模块对象形式填充。
参数
organisationId `string` （必填） 组织 ID端点
GET /api/organisations/{organisationId}/admin-modules请求示例
curl -X GET https://portal.hub.gymsystems.co/api/organisations/{organisationId}/admin-modules \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回所有组织的列表
参数
includeBrands `string` （可选） 包含与组织关联的品牌 includeFacilities `string` （可选） 包含与组织关联的设施 includeRegions `string` （可选） 包含与组织关联的区域端点
GET /api/organisations请求示例
curl -X GET https://portal.hub.gymsystems.co/api/organisations \
-H "x-api-key: YOUR_API_KEY"
响应
{}
一个简单的 AI 辅助工具，用于分析支持工单的内容，并根据可用主题以及建议的 Algolia 搜索主题生成建议……
参数
messageBody `string` （必填） 要发送的消息正文 topicData `string` （必填） osTicket（工单/支持系统）返回的 topicData 的 JSON 对象/数组 facilityId `string` （可选） 用于确定要搜索的正确 Algolia 索引的俱乐部内部 ID。端点
PUT /api/ai/helpers/analyse-support-ticket请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/ai/helpers/analyse-support-ticket \
-H "x-api-key: YOUR_API_KEY"
响应
{}
一个简单的图像生成 API
参数
type `string` （必填） 要生成的图像类型 name `string` （必填） 图像名称 maxSize `string` （可选） 可选的最大响应大小，例如 200KB、1MB 或纯字节数。图像会被缩小/压缩以符合该大小。端点
PUT /api/ai/images/:type/:name请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/ai/images/:type/:name \
-H "x-api-key: YOUR_API_KEY"
响应
{}
简单 LLM 查询
用于简单、无状态 LLM 查询的轻量级端点。 使用低成本的非推理模型（gpt-4o-mini），并严格限制 token 数。 没有对话历史、没有工具、没有流式传输，只是输入提示词、输出文本。
请求正文
端点
POST /api/ai/llm/query请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ai/llm/query \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
返回 Algolia 配置，包括索引名称、应用 ID 和 API 密钥。
参数
facilityId `string` （必填）端点
GET /api/facilities/{facilityId}/algolia/config请求示例
curl -X GET https://portal.hub.gymsystems.co/api/facilities/{facilityId}/algolia/config \
-H "x-api-key: YOUR_API_KEY"
响应
{}
初始化 Algolia 营销印刷品索引
参数
organisationId `string` （必填）端点
PUT /api/algolia/index请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/algolia/index \
-H "x-api-key: YOUR_API_KEY"
响应
{}
搜索营销印刷品
请求正文
端点
POST /algolia/search-marketing-print请求示例
curl -X POST https://portal.hub.gymsystems.co/algolia/search-marketing-print \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
搜索营销印刷品
参数
club `string` （可选） 俱乐部 ID searchTerms `string` （可选） 搜索词 algoliaArgs `object` （可选） 其他 Algolia 搜索参数端点
GET /algolia/search-marketing-print请求示例
curl -X GET https://portal.hub.gymsystems.co/algolia/search-marketing-print \
-H "x-api-key: YOUR_API_KEY"
响应
{}
批量更新特定俱乐部的营销印刷品对象
端点
POST /algolia/bulk-update-marketing-print请求示例
curl -X POST https://portal.hub.gymsystems.co/algolia/bulk-update-marketing-print \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从 Algolia 获取营销印刷品素材。
参数
organisationId `string` （必填） search `string` （可选） limit `string` （可选） brand `string` （可选） tag `string` （可选）端点
GET /api/algolia/marketing/assets请求示例
curl -X GET https://portal.hub.gymsystems.co/api/algolia/marketing/assets \
-H "x-api-key: YOUR_API_KEY"
响应
{}
使用设施的配置初始化 Algolia 营销印刷品索引。
参数
organisationId `string` （必填）端点
POST /api/algolia/marketing/assets请求示例
curl -X POST https://portal.hub.gymsystems.co/api/algolia/marketing/assets \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据搜索词、俱乐部和/或区域设置，在指定的 Algolia 索引中执行搜索。可使用其他 Algolia 参数进一步自定义搜索。
参数
searchTerms `string` （必填） 要在 Algolia 索引中搜索的词。 club `string` （可选） 发出请求的俱乐部的内部 ID。如果指定，搜索结果将按该俱乐部关联的地区进行筛选。 locale `string` （可选） 未指定俱乐部时用于确定地区的区域设置。取自 navigator.languages。 algoliaArgs `string` （可选） 要传递给 Algolia 搜索请求的其他/自定义参数。端点
POST /api/algolia/search-wiki请求示例
curl -X POST https://portal.hub.gymsystems.co/api/algolia/search-wiki \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出所有公告
端点
GET /api/announcements/list请求示例
curl -X GET https://portal.hub.gymsystems.co/api/announcements/list \
-H "x-api-key: YOUR_API_KEY"
响应
{}
（通过上传 API）将素材上传到公开的 S3 存储桶，随后会对文件进行后处理/优化、生成缩略图等。*请注意，素材将公开可用*
参数
file `string` （可选） 要上传的文件/素材的名称。端点
POST /api/asset-upload请求示例
curl -X POST https://portal.hub.gymsystems.co/api/asset-upload \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据上传记录的 UUID 返回上传状态
参数
uuid `string` （必填） 上传记录的 UUID端点
GET /api/asset-upload/:uuid请求示例
curl -X GET https://portal.hub.gymsystems.co/api/asset-upload/:uuid \
-H "x-api-key: YOUR_API_KEY"
响应
{}
向俱乐部的 Sonos 发送命令
参数
body `object` （必填） 要发送到 Sonos 的命令和输入的 JSON 对象。端点
PUT /api/audio-control/command/:club请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/audio-control/command/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
检索音频控制前端的配置
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/audio-control/config/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/audio-control/config/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更改音频控制前端的配置
参数
body `object` （必填） 要添加到系统中的新配置块的 JSON 对象。端点
PUT /api/audio-control/config/:club/:section请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/audio-control/config/:club/:section \
-H "x-api-key: YOUR_API_KEY"
响应
{}
检索特定地区的品牌设置
参数
brandId `string` （可选） 品牌的 ID regionCode `string` （可选） 要检索其设置的地区的 ISO 代码端点
GET /api/brands/{brandId}/regions/{regionCode}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/brands/{brandId}/regions/{regionCode} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新特定地区的多项品牌设置
参数
brandId `string` （可选） 要更新的品牌的 ID regionCode `string` （可选） 要更新其设置的地区的 ISO 代码 acceptFreeTrialBookingsVisibility `string` （可选） customTrackingCodeVisibility `string` （可选） displayDataSources `string` （可选） displayDefaultDataSource `string` （可选） displayDefaultUI `string` （可选） displayUIOptions `string` （可选） defaultAboutBusiness `string` （可选） defaultAboutBusinessFacebook `string` （可选） facilityCoverImage `string` （可选） digitalProfileSettingsVisibility `string` （可选） facilityHoursVisibility `string` （可选） facilityLocationVisibility `string` （可选） facilityPaymentMethods `string` （可选） facilityPrimaryLogo `string` （可选） facilityStatusVisibility `string` （可选） landingPagesVisibility `string` （可选） lineChatIntegrationVisibility `string` （可选） whatsAppIntegrationVisibility `string` （可选） defaultWhatsAppMessage `string` （可选） socialUrlsVisibility `string` （可选） yextApiKey `string` （可选） 此品牌地区的 Yext 集成使用的 API 密钥。仅在 `directorySyncMode` 为 `yext` 时使用。 directorySyncMode `string` （可选） 此品牌地区下的设施应运行的同步后端。缺失时默认为 `yext`，以向后兼容在 Directory Publishers 推出之前创建的品牌。 websiteUrl `string` （可选） androidAppUrl `string` （可选） iosAppUrl `string` （可选） featuredMessageDescription `string` （可选） yextCategoryIds `string` （可选） 旧版存储键，实际上是 Google Business Profile 类别 ID（例如 gcid:gym）。"yext" 前缀早于 Yext 弃用；保留它是为了向后兼容现有数据库记录。 customInputFields `string` （可选） customInputFieldsToRemove `string` （可选）端点
PUT /api/brands/{brandId}/regions/{regionCode}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/brands/{brandId}/regions/{regionCode} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
检索特定设施的品牌设置
参数
facilityId `string` （可选） 要检索其品牌设置的设施的 ID端点
GET /api/facilities/{facilityId}/brand-settings请求示例
curl -X GET https://portal.hub.gymsystems.co/api/facilities/{facilityId}/brand-settings \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建新品牌
参数
name `string` （必填） 品牌名称 organisationId `string` （必填） 品牌所属组织的 ID redirectDashboard `string` （可选） 登录后重定向到的 URL，代替默认仪表板端点
POST /api/brands请求示例
curl -X POST https://portal.hub.gymsystems.co/api/brands \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回所有品牌的列表
端点
GET /api/brands请求示例
curl -X GET https://portal.hub.gymsystems.co/api/brands \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回品牌对象
参数
brandId `string` （必填） 要检索的品牌的 ID includeOrganisation `boolean` （可选） 是否在响应中包含组织数据端点
GET /api/brands/{brandId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/brands/{brandId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按 ID 更新品牌
参数
brandId `string` （可选） 要更新的品牌的 ID name `string` （必填） 品牌名称 brandOrganisationId `string` （可选） 品牌所属组织的 ID redirectDashboard `string` （可选） 登录后重定向到的 URL，代替默认仪表板 yextApiKey `string` （可选） 此品牌用于访问 Yext API 的 API 密钥 customMenuLayout `object` （可选） 每个品牌的侧边菜单布局树（部分/分组/菜单项，引用 系统模块或自定义 URL）。只能由此品牌所属组织的 组织管理员设置。端点
PUT /api/brands/{brandId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/brands/{brandId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出品牌的设施
返回属于该品牌的设施的精简列表（id、名称、地区 ISO 代码）。 用于填充品牌配置中的设施定向选择器。
参数
brandId `string` （必填） 要列出其设施的品牌的 ID端点
GET /api/brands/{brandId}/facilities请求示例
curl -X GET https://portal.hub.gymsystems.co/api/brands/{brandId}/facilities \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回与该俱乐部所属组织关联的所有品牌的列表。
端点
GET /api/clubs/{club}/brands请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club}/brands \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回所有日历类型的列表
端点
GET /api/programs/calendars/calendar-types请求示例
curl -X GET https://portal.hub.gymsystems.co/api/programs/calendars/calendar-types \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部的 KYC 资料。
参数
clubId `string` （必填） 俱乐部的 ID。 key `string` （必填） KYC 资料的键。端点
GET /api/clubs/{clubId}/kyc-assets/{key}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubId}/kyc-assets/{key} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部的 KYC 信息。
端点
GET /api/clubs/{clubId}/kyc请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubId}/kyc \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新俱乐部的 KYC 信息。
参数
clubId `string` （必填） 要更新的俱乐部的 ID。 body `object` （必填）端点
PUT /api/clubs/{clubId}/kyc请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{clubId}/kyc \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为俱乐部上传 KYC 资料。
参数
clubId `string` （必填） 俱乐部的 ID。 file `string` （必填） 要上传的文件。端点
POST /api/clubs/{clubId}/kyc-assets请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{clubId}/kyc-assets \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部的偏好设置。
端点
GET /api/club/preferences/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/club/preferences/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建或更新俱乐部偏好设置条目。
请求正文
端点
POST /api/club/preferences/:club请求示例
curl -X POST https://portal.hub.gymsystems.co/api/club/preferences/:club \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
返回已签署协议的会员列表。
端点
GET /api/clubpass/user/email/exist/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubpass/user/email/exist/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回已签署协议的会员列表。
端点
GET /api/clubpass/user/phone/exist/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubpass/user/phone/exist/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回属于指定俱乐部的用户列表
参数
club `string` （必填） 要访问的俱乐部的内部 ID端点
GET /api/clubs/{club}/members请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club}/members \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部在指定日期是否营业。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 date `string` （必填） 要检查的日期，采用 Unix 格式端点
GET /api/club-busy-hours/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/club-busy-hours/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回在 Example Club 网站上显示的俱乐部的所有元数据。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/clubs/clubpage/clubdata/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/clubpage/clubdata/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
使用前端提供的新数据更新俱乐部的元数据。 请求正文中缺失的字段会保留（不执行 SET，也不执行 REMOVE）。 以 `null` 或空字符串发送的字段会被清除。传入 `updateAll: false` 可使用专用的部分合并路径；无论哪种方式，调用方都无需 发送不属于自己的字段。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 body `string` （必填） 要更新的俱乐部数据的 JSON 对象。端点
POST /api/clubs/clubpage/updateclub/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/clubpage/updateclub/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
添加新的自定义跟踪记录
参数
club `string` （必填） 俱乐部的 ID body `string` （必填） 自定义跟踪项数组。端点
POST /api/clubs/{club}/customtracking请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{club}/customtracking \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回特定俱乐部的自定义跟踪
端点
GET /api/clubs/customtracking/:clubID请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/customtracking/:clubID \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新自定义跟踪条目
参数
club `string` （必填） 俱乐部的 ID body `string` （必填） 要更新的俱乐部数据的 JSON 对象。端点
POST /api/clubs/{club}/customtracking/update请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{club}/customtracking/update \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部的默认店面图片。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/clubs/{club}/default-shop-front请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club}/default-shop-front \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设施中可用的门
参数
body `object` （必填） 要更新的俱乐部数据的 JSON 对象。端点
POST /api/clubs/integrations/doors/:facilityId请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/integrations/doors/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
解锁设施中的特定门
参数
body `object` （必填） 要更新的俱乐部数据的 JSON 对象。端点
POST /api/clubs/integrations/doors/unlock请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/integrations/doors/unlock \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回指定俱乐部的所有集成及其配置详细信息。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/clubs/integrations/list/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/integrations/list/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
使用前端提供的新数据更新俱乐部的元数据。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 body `object` （必填） 要更新的俱乐部数据的 JSON 对象。端点
POST /api/clubs/integrations/update/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/integrations/update/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回布尔值，表示俱乐部是否位于欧洲国家
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 date `string` （必填） 要检查的日期，采用 Unix 格式端点
GET /api/clubs/is-eu/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/is-eu/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回数据库中所有俱乐部的概要列表。
端点
GET /api/clubs/listclubs请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/listclubs \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回俱乐部在指定日期是否营业。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 date `string` （必填） 要检查的日期，采用 Unix 格式端点
GET /api/clubs/{club}/open-on/{date}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club}/open-on/{date} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从 DynamoDB 获取俱乐部评价。
参数
club `string` （必填） 俱乐部 ID端点
GET /api/clubs/{club}/reviews请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club}/reviews \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从 DynamoDB 获取俱乐部评价设置。
参数
facilityId `string` （必填） 设施 ID端点
GET /api/clubs/{club}/reviews-settings请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club}/reviews-settings \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在 DynamoDB 中更新俱乐部评价设置。
参数
club `string` （必填） 俱乐部 ID端点
PUT /api/clubs/{club}/reviews-settings请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{club}/reviews-settings \
-H "x-api-key: YOUR_API_KEY"
响应
{}
重新启用评价设置的自动发布。
参数
club `string` （必填） 俱乐部 ID端点
PUT /api/clubs/{club}/reviews/publish-recent-reviews请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{club}/reviews/publish-recent-reviews \
-H "x-api-key: YOUR_API_KEY"
响应
{}
发布评价
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 review `string` （必填） 要发布的评价的内部 ID。端点
PUT /api/clubs/{club}/reviews/{review}/publish请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{club}/reviews/{review}/publish \
-H "x-api-key: YOUR_API_KEY"
响应
{}
重新启用评价设置的自动发布。
参数
club `string` （必填） 俱乐部 ID端点
PUT /api/clubs/{club}/reviews-settings/re-enable-auto-publish请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{club}/reviews-settings/re-enable-auto-publish \
-H "x-api-key: YOUR_API_KEY"
响应
{}
通过评价的原始发布平台（Google 等）发布对该评价的回复。
参数
club `string` （必填） 设施 ID reviewId `string` （必填） PH 评价 ID（在 club-social-reviews 表中查找） body `string` （必填）端点
POST /api/clubs/{club}/reviews/{reviewId}/respond请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{club}/reviews/{reviewId}/respond \
-H "x-api-key: YOUR_API_KEY"
响应
{}
取消发布评价
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 review `string` （必填） 要取消发布的评价的内部 ID。端点
PUT /api/clubs/{club}/reviews/{review}/un-publish请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{club}/reviews/{review}/un-publish \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从 PH 数据库返回属于指定俱乐部的所有者列表
参数
clubID `string` （必填） 要访问的俱乐部的内部 ID端点
GET /api/clubs/{clubID}/owners请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/owners \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施的所有会员计划。
参数
facilityId `string` （必填） 设施的内部 ID端点
GET /api/facilities/membership-plans/:facilityId请求示例
curl -X GET https://portal.hub.gymsystems.co/api/facilities/membership-plans/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新会员计划记录。
参数
facilityId `string` （必填） 设施的内部 ID body `object` （必填） 要更新的会员计划数据的 JSON 对象。端点
PUT /api/facilities/membership-plans/:facilityId请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/facilities/membership-plans/:facilityId \
-H "x-api-key: YOUR_API_KEY"
响应
{}
重新启用评价设置的自动发布。
参数
club `string` （必填） 俱乐部 ID端点
PUT /api/clubs/{club}/reviews/publish-recent-reviews请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{club}/reviews/publish-recent-reviews \
-H "x-api-key: YOUR_API_KEY"
响应
{}
重新启用评价设置的自动发布。
参数
club `string` （必填） 俱乐部 ID端点
PUT /api/clubs/{club}/reviews-settings/re-enable-auto-publish请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{club}/reviews-settings/re-enable-auto-publish \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回所有可用货币的列表
端点
GET /api/currencies请求示例
curl -X GET https://portal.hub.gymsystems.co/api/currencies \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据 IP 地址返回地理位置。
参数
ip `string` （必填） 要查询的 IP 地址端点
GET /api/geo/ip-location/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/geo/ip-location/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据当前用户的 IP 返回其地理位置。
端点
GET /api/geo/ip-current请求示例
curl -X GET https://portal.hub.gymsystems.co/api/geo/ip-current \
-H "x-api-key: YOUR_API_KEY"
响应
{}
仅返回请求客户端的公共 IP 地址（不进行地理位置查询，也不调用第三方 API）。人工智能代理小程序用它将浏览器的公共 IP 与设备上报的 WAN IP 进行比较，以检测是否处于同一网络。
端点
GET /api/geo/client-ip请求示例
curl -X GET https://portal.hub.gymsystems.co/api/geo/client-ip \
-H "x-api-key: YOUR_API_KEY"
响应
{}
电话号码解析器。
参数
body `string` （必填） 要解析的号码的 JSON 对象。端点
POST /api/phone/parser请求示例
curl -X POST https://portal.hub.gymsystems.co/api/phone/parser \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回主时钟设备
参数
club_id `string` （必填） 要在其下添加设备的俱乐部的内部 ID。端点
GET /api/clubs/{club_id}/smart-club/health-check/master-clock请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club_id}/smart-club/health-check/master-clock \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回主 Sonos 设备
参数
club_id `string` （必填） 要在其下添加设备的俱乐部的内部 ID。端点
GET /api/clubs/{club_id}/smart-club/health-check/sonos-mqtt请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club_id}/smart-club/health-check/sonos-mqtt \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取指定俱乐部的 Duress 低电量通知。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/clubs/{club}/smart-club/health-check/low-battery-duress请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club}/smart-club/health-check/low-battery-duress \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回网络分析数据
参数
club_id `string` （必填） 要在其下添加设备的俱乐部的内部 ID。端点
GET /api/clubs/{club_id}/smart-club/health-check/network-analysis请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club_id}/smart-club/health-check/network-analysis \
-H "x-api-key: YOUR_API_KEY"
响应
{}
发送指定俱乐部的 Duress 低电量通知。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/clubs/{club}/smart-club/health-check/send-low-battery-duress-notifs请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club}/smart-club/health-check/send-low-battery-duress-notifs \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回每种设备类型的设备测速数据
参数
club_id `string` （必填） 要在其下添加设备的俱乐部的内部 ID。端点
GET /api/clubs/{club_id}/smart-club/health-check/speed-test请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{club_id}/smart-club/health-check/speed-test \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取设施的商家信息洞察。默认返回所有发布平台汇总的每日总计；如果提供了 `publisherId`，则返回单个发布平台的数据。
参数
facilityId `string` （必填） publisherId `string` （可选） startDate `string` （必填） endDate `string` （必填）端点
GET /api/facilities/{facilityId}/directory-insights请求示例
curl -X GET https://portal.hub.gymsystems.co/api/facilities/{facilityId}/directory-insights \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取品牌在所有发布平台上的汇总商家信息洞察。
参数
brandId `string` （必填） startDate `string` （必填） endDate `string` （必填）端点
GET /api/brands/{brandId}/directory-insights请求示例
curl -X GET https://portal.hub.gymsystems.co/api/brands/{brandId}/directory-insights \
-H "x-api-key: YOUR_API_KEY"
响应
{}
设施的热门搜索关键词（区分品牌词与非品牌词），目前来源于 Google Business Profile。
参数
facilityId `string` （必填） publisherId `string` （可选） 默认为 "google"，目前仅支持 Google。 startDate `string` （必填） endDate `string` （必填） limit `string` （可选）端点
GET /api/facilities/{facilityId}/directory-search-keywords请求示例
curl -X GET https://portal.hub.gymsystems.co/api/facilities/{facilityId}/directory-search-keywords \
-H "x-api-key: YOUR_API_KEY"
响应
{}
品牌的热门搜索关键词，汇总所有设施的数据。
参数
brandId `string` （必填） startDate `string` （必填） endDate `string` （必填） limit `string` （可选）端点
GET /api/brands/{brandId}/directory-search-keywords请求示例
curl -X GET https://portal.hub.gymsystems.co/api/brands/{brandId}/directory-search-keywords \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设施的问答。
参数
facilityId `string` （必填）端点
GET /api/facilities/{facilityId}/qna请求示例
curl -X GET https://portal.hub.gymsystems.co/api/facilities/{facilityId}/qna \
-H "x-api-key: YOUR_API_KEY"
响应
{}
回答问题。
端点
POST /api/facilities/{facilityId}/qna/{questionId}/answer请求示例
curl -X POST https://portal.hub.gymsystems.co/api/facilities/{facilityId}/qna/{questionId}/answer \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除回答。
端点
DELETE /api/facilities/{facilityId}/qna/{questionId}/answer/{answerId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/facilities/{facilityId}/qna/{questionId}/answer/{answerId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回为该设施所属组织启用的发布平台及其连接状态。
参数
facilityId `string` （必填） organisationId `string` （必填）端点
GET /api/facilities/{facilityId}/directory-publishers/resolved请求示例
curl -X GET https://portal.hub.gymsystems.co/api/facilities/{facilityId}/directory-publishers/resolved \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取设施的 Access Policies
首次读取时，现有访问配置会自动转换为等效的强制执行策略。
参数
facilityId `string` （必填）端点
GET /api/door-access/policies/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/policies/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
使用乐观修订检查替换 Access Policies
参数
facilityId `string` （必填）请求正文
端点
PUT /api/door-access/policies/{facilityId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/door-access/policies/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
创建 Access Policy
参数
facilityId `string` （必填）端点
POST /api/door-access/policies/{facilityId}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/policies/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新一个 Access Policy
参数
facilityId `string` （必填） policyId `string` （必填）端点
PATCH /api/door-access/policies/{facilityId}/{policyId}请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/door-access/policies/{facilityId}/{policyId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除一个 Access Policy
参数
facilityId `string` （必填） policyId `string` （必填） revision `integer` （必填）端点
DELETE /api/door-access/policies/{facilityId}/{policyId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/door-access/policies/{facilityId}/{policyId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
复制 Access Policy 并分配新的稳定 ID
参数
facilityId `string` （必填） policyId `string` （必填）端点
POST /api/door-access/policies/{facilityId}/{policyId}/duplicate请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/policies/{facilityId}/{policyId}/duplicate \
-H "x-api-key: YOUR_API_KEY"
响应
{}
统计所有 Access Policies 影响的用户和门数量
参数
facilityId `string` （必填）端点
GET /api/door-access/policies/{facilityId}/impacts请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/policies/{facilityId}/impacts \
-H "x-api-key: YOUR_API_KEY"
响应
{}
统计某个 Access Policy 影响的用户和门数量
参数
facilityId `string` （必填） policyId `string` （必填）端点
GET /api/door-access/policies/{facilityId}/{policyId}/impact请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/policies/{facilityId}/{policyId}/impact \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设施中的门控制器及其生效的 Door/Gate Access 规则
参数
facilityId `string` （必填）端点
GET /api/door-access/doors/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/doors/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
保存每扇门的覆盖设置、图标和设备端配置
DGA 管理小程序在门上编辑的所有内容的统一写入接口： - `accessRulesOverride` / `geofenceOverride`：传入 `null` 可清除并回退到设施默认值。 - `icon`：稳定的传输键（参见 services/door-access/door-icons.js）；未知值返回 400。 - `holdTimeSeconds`（1–30）、`maintenanceMode`（`off` / `force-open` / `force-closed`）、`doorLocation`（自由文本，≤64 个字符）、`playNotificationSoundOnRelayToggle`（布尔值）、`autoUnlockSchedule`（每周时段网格）。这些字段以前只能在设备管理中编辑，但现在小程序可以直接写入，管理员无需离开门的抽屉面板即可完成日常配置更改。 当任何设备端字段被修改时，该路由还会推送对应的 Balena 环境变量（`RELAY_NOTIFICATION_SOUND`、`DOOR_MAINTENANCE_MODE`、`DOOR_AUTO_UNLOCK_SCHEDULE`），并发送 `unlockUpdates` MQTT 命令，使设备无需等待下一次 Balena 环境刷新即可获取新配置。尽力而为：即使 Balena 暂时无法访问，响应也会返回 200。
参数
facilityId `string` （必填） doorId `string` （必填）请求正文
端点
PUT /api/door-access/doors/{facilityId}/{doorId}/override请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/door-access/doors/{facilityId}/{doorId}/override \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
门抽屉面板重新加载提示所用的轻量级 Balena 状态探测
管理员打开门时，DGA 小程序的抽屉面板会延迟获取此信息，以显示正确的“保存将重新加载控制器”文案：默认的“几秒钟”版本，或者在同时有版本更新待处理时显示更明确的“几分钟”版本。 返回从 `balena.models.device.get()` 派生的扁平快照。失败时软降级为 `data: null`（而不是返回 5xx），因此 Balena 中断只会降低提示文案的准确性，而不会阻止抽屉面板打开。
参数
facilityId `string` （必填） doorId `string` （必填）端点
GET /api/door-access/doors/{facilityId}/{doorId}/device-status请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/doors/{facilityId}/{doorId}/device-status \
-H "x-api-key: YOUR_API_KEY"
响应
{}
管理员覆盖：从小程序解锁门
使用门当前的 `holdTimeSeconds` 短暂切换继电器，并将一条 `admin-override` 审计记录写入 ph-door-app-access-events，以便在访问日志中追溯该操作。无论 `maintenanceMode === 'force-closed'` 与否都会成功，这是管理员的紧急通道。 MQTT 发布一经发出即返回 200；此处不会等待 confirmed / failed / timed_out 状态（旧版 /api/devices/door-controllers + /api/ics/devices/command 流程同样是发出即不管）。
参数
facilityId `string` （必填） doorId `string` （必填）端点
POST /api/door-access/doors/{facilityId}/{doorId}/unlock请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/doors/{facilityId}/{doorId}/unlock \
-H "x-api-key: YOUR_API_KEY"
响应
{}
让门控制器播放定位蜂鸣音
发布 `beep` MQTT 命令，使控制器发出三声中等长度的蜂鸣（每声约 500 毫秒，间隔约 350 毫秒，共约 2 秒）。管理员用它在现场实际定位门控制器。旧版设备管理按钮使用约 30 秒的连续短促蜂鸣，但固件蜂鸣器驱动只能可靠地发出第一声，因此小程序改为发送更短、更可靠的模式。不写审计记录，因为这是没有访问控制副作用的诊断操作。
参数
facilityId `string` （必填） doorId `string` （必填）端点
POST /api/door-access/doors/{facilityId}/{doorId}/identify请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/doors/{facilityId}/{doorId}/identify \
-H "x-api-key: YOUR_API_KEY"
响应
{}
远程重启门控制器
发布与旧版设备管理“Remotely Reboot Device”按钮相同的发出即不管的 `rebootDevice` MQTT 命令，但由 `door-gate-access` 模块控制，因此 DGA 管理员无需单独的 `device-management` 授权即可从门抽屉面板的高级部分重启控制器。发布一经发出即返回 200；重启期间设备会离线。
参数
facilityId `string` （必填） doorId `string` （必填）端点
POST /api/door-access/doors/{facilityId}/{doorId}/reboot请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/doors/{facilityId}/{doorId}/reboot \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设施中的 User Access 行
返回设施中所有未删除的 User Access 行。支持客户端筛选（source、search、accessEnabled、hasGrants）。第 4 阶段的 `hideExcluded` 服务器端计算将在混合授权评估器上线后添加；目前接受该参数，但返回完整结果集。
参数
facilityId `string` （必填） search `string` （可选） source `string` （可选） accessEnabled `string` （可选） hasGrants `string` （可选） hideExcluded `boolean` （可选） 为 true 时，隐藏在此设施中任何时间都无法通过任何门的同步用户（source != manual）。响应包含 `hidden: { count, sample }` 封装。端点
GET /api/door-access/users/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/users/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在设施中手动创建 User Access 行
创建一个 `source: 'manual'` 的新行。如果提供的电话或电子邮件已对应此设施中的某一行，则返回 409 及 `existingUserId`。
参数
facilityId `string` （必填）请求正文
端点
POST /api/door-access/users/{facilityId}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/users/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
获取单个 User Access 行
参数
facilityId `string` （必填） userId `string` （必填）端点
GET /api/door-access/users/{facilityId}/{userId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/{userId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
部分更新 User Access 行
编辑身份/授权字段的任意子集。传入 `null` 可清除可选字段。如果新的电话或电子邮件与同一设施中的另一行冲突，则返回 409。 `appMessage` 接受与 PUT /api/door-access/rules/{facilityId} 上设施级消息相同的结构：正文、严重程度、可选链接、可选的开始/结束时间计划。移动应用只会在目标用户的仪表板上显示此消息。
参数
facilityId `string` （必填） userId `string` （必填）请求正文
端点
PATCH /api/door-access/users/{facilityId}/{userId}请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/{userId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
软删除 User Access 行
将该行标记为 `deleted: true` 并禁用访问。与 userId 关联的审计日志会保留；管理员可以手动重新启用。
参数
facilityId `string` （必填） userId `string` （必填）端点
DELETE /api/door-access/users/{facilityId}/{userId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/{userId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
用户的逐门访问归因
针对每扇门，返回当前确定性的授权结果（`allowedNow`、`allowedVia`、`deniedReason`），以及 Access Policies、永久授权、策略时间计划、管理员时间窗口授权和最新映射的合作伙伴来源时间窗口的已配置路径。还会返回当前/下一个可用时段以及来源的新鲜度。门的 blockAllAccess 和维护状态会在所有允许路径之前评估。
参数
facilityId `string` （必填） userId `string` （必填）端点
GET /api/door-access/users/{facilityId}/{userId}/effective-access请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/{userId}/effective-access \
-H "x-api-key: YOUR_API_KEY"
响应
{}
通过 CSV 导入批量创建 User Access 行
在一个请求中创建多个 `source: 'manual'` 行，复用与单个创建相同的验证、电话/电子邮件规范化、按设施的冲突检查、自动消息和（可选）邀请逻辑。各行按顺序处理，因此后面的行如果与前面已创建的行冲突，会被报告为重复。授权以已解析的门/组 ID 提供（由客户端将名称解析为 ID）。批量导入时会有意拒绝时间窗口授权，必须在导入后通过按用户替换的端点添加。不会因单行出错而抛出异常；每行的结果会单独报告。
参数
facilityId `string` （必填）请求正文
端点
POST /api/door-access/users/{facilityId}/bulk请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/bulk \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
替换 User Access 行上的附加 Access Time Window 授权
仅替换 `timeWindowGrants`；永久 `grants` 和集成 `sourceTimeWindows` 不受影响。每一项都需要一个范围（`facilityWide`、`doors` 或 `groups`）以及一个绝对或每周的 `window`。发送空数组会明确清除所有管理员时间窗口。
参数
facilityId `string` （必填） userId `string` （必填）请求正文
端点
PUT /api/door-access/users/{facilityId}/{userId}/time-window-grants请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/{userId}/time-window-grants \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
冻结 User Access 行，使其不受来源驱动的同步更新影响
设置 `decoupledFromSource: true`，清除所有由集成拥有的 `sourceTimeWindows`，并使同步（cron + 流）记录日志并跳过此行，直到管理员通过 /recouple 清除该标志。
参数
facilityId `string` （必填） userId `string` （必填）端点
POST /api/door-access/users/{facilityId}/{userId}/decouple请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/{userId}/decouple \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将 User Access 行重新连接到来源驱动的同步更新
参数
facilityId `string` （必填） userId `string` （必填）端点
POST /api/door-access/users/{facilityId}/{userId}/recouple请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/{userId}/recouple \
-H "x-api-key: YOUR_API_KEY"
响应
{}
撤销用户的所有 Door/Gate Access 应用刷新令牌
按用户存储的电话/电子邮件撤销（刷新令牌表以 `sha256(plaintext)` 为键；byMobilePhone / byEmail GSI 使我们可以从单个用户扇出删除）。在其他设施中共用相同电话/电子邮件的其他用户也会被注销。
参数
facilityId `string` （必填） userId `string` （必填）端点
POST /api/door-access/users/{facilityId}/{userId}/logout请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/{userId}/logout \
-H "x-api-key: YOUR_API_KEY"
响应
{}
向用户（重新）发送 Door/Gate Access 应用邀请电子邮件
强制向用户存储的电子邮件地址发送应用下载邀请电子邮件（仅电子邮件，不发送短信）。忽略自动同步流程使用的资格检查和已发送检查，因为这是管理员的明确操作。如果用户没有登记电子邮件，则返回 400。
参数
facilityId `string` （必填） userId `string` （必填）端点
POST /api/door-access/users/{facilityId}/{userId}/resend-invite请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/{userId}/resend-invite \
-H "x-api-key: YOUR_API_KEY"
响应
{}
预览批量发送应用邀请的收件人
计算将收到应用邀请电子邮件的用户集合。基础范围是所有未删除、有电子邮件且从未使用过应用（`appLastSeenAt` 为空）的用户。默认情况下，该范围会缩小为当前有访问权限（规则匹配或授权）且从未被邀请过的用户；`includeAlreadyInvited` 和 `includeNoAccess` 可扩大范围。不会发送任何电子邮件，只返回数量、一小部分样本以及供执行端点使用的候选 userId。
参数
facilityId `string` （必填）请求正文
端点
POST /api/door-access/users/{facilityId}/bulk-invite/preview请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/bulk-invite/preview \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
向一批用户发送应用邀请电子邮件
向提供的每个 userId 发送应用下载邀请电子邮件（每个请求最多 50 个；客户端会将预览返回的完整候选列表分批发送）。每个用户在发送时都会重新验证：已不存在、没有电子邮件或自预览以来已使用过应用的行会被跳过，而不是标记为失败。每个用户的结果会单独报告，以便客户端汇总已发送/失败/已跳过的数量。
参数
facilityId `string` （必填）请求正文
端点
POST /api/door-access/users/{facilityId}/bulk-invite请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/users/{facilityId}/bulk-invite \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
列出设施中的门组
参数
facilityId `string` （必填）端点
GET /api/door-access/door-groups/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/door-groups/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建门组
参数
facilityId `string` （必填）请求正文
端点
POST /api/door-access/door-groups/{facilityId}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/door-groups/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
获取单个门组
参数
facilityId `string` （必填） groupId `string` （必填）端点
GET /api/door-access/door-groups/{facilityId}/{groupId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/door-groups/{facilityId}/{groupId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新门组
参数
facilityId `string` （必填） groupId `string` （必填）请求正文
端点
PATCH /api/door-access/door-groups/{facilityId}/{groupId}请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/door-access/door-groups/{facilityId}/{groupId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
软删除门组
参数
facilityId `string` （必填） groupId `string` （必填）端点
DELETE /api/door-access/door-groups/{facilityId}/{groupId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/door-access/door-groups/{facilityId}/{groupId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设施中配置的合作伙伴集成
通过将 ph-facility-partner-config 与 ph-partners 目录关联，返回设施的合作伙伴集成（ID、名称、徽标、是否启用）。权限范围为 Door-gate-access（因此没有外部集成访问权限的管理员仍可显示合作伙伴徽章和按合作伙伴的同步列表）。
参数
facilityId `string` （必填）端点
GET /api/door-access/partners/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/partners/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
读取设施的 User Access 同步配置
参数
facilityId `string` （必填）端点
GET /api/door-access/sync-config/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/sync-config/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新设施的 User Access 同步配置
只接受由管理员控制的字段（`enabled`、`requireIdentifier` 以及合作伙伴 `partners` 映射）；`lastRunAt` 和 `lastRunCounts` 由同步引擎自行写入。 `partner.partners` 是以 partnerId 为键的按合作伙伴启用映射（选择退出模式）：当总开关 `partner.enabled` 开启时，除非此处有明确的 `{ enabled: false }` 条目，否则合作伙伴会同步。
参数
facilityId `string` （必填）请求正文
端点
PUT /api/door-access/sync-config/{facilityId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/door-access/sync-config/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
读取设施的按用户自动消息配置
参数
facilityId `string` （必填）端点
GET /api/door-access/auto-messages/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/auto-messages/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新设施的按用户自动消息配置
保存规则，然后立即重新评估设施中的每个 User Access 行，使现有用户立即获得或失去其自动消息。手动消息和已解耦的行不受影响。
参数
facilityId `string` （必填）请求正文
端点
PUT /api/door-access/auto-messages/{facilityId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/door-access/auto-messages/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
后台自动消息重新评估任务的状态
参数
facilityId `string` （必填）端点
GET /api/door-access/auto-messages/{facilityId}/sweep-status请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/auto-messages/{facilityId}/sweep-status \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为设施运行按需 User Access 同步
同步遍历设施中每个已启用的来源（合作伙伴/CCTV），并通过去重瀑布流程收敛 ph-door-access-users 行。返回每个来源的计数。已禁用的来源显示为 `skippedSyncDisabled: 1` 而不是缺失，以便界面一致地显示两行。
参数
facilityId `string` （必填）端点
POST /api/door-access/sync/{facilityId}/run请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/sync/{facilityId}/run \
-H "x-api-key: YOUR_API_KEY"
响应
{}
合作伙伴同步批量删除的试运行预览
返回将被软删除的 user-access 行的数量和样本，以及一个必须回传给执行端点的 confirmToken。不会修改任何数据。访问日志永远不受影响。
参数
facilityId `string` （必填）请求正文
端点
POST /api/door-access/sync/{facilityId}/bulk-delete/preview请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/sync/{facilityId}/bulk-delete/preview \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
执行合作伙伴同步批量删除（软删除）
软删除范围内所有合作伙伴同步的 user-access 行。需要预览返回的 confirmToken；如果自预览以来实时数据集已发生变化，令牌将不匹配，请求会被拒绝（409），以便管理员重新审核。访问日志会保留。
参数
facilityId `string` （必填）请求正文
端点
POST /api/door-access/sync/{facilityId}/bulk-delete请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/sync/{facilityId}/bulk-delete \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
最近的 User Access 同步活动（故障排除日志）
返回设施最近的同步结果（已创建/已跳过/已禁用）及原因，以便管理员了解某位会员为何已同步或未同步。最新的在前。
参数
facilityId `string` （必填） limit `integer` （可选）端点
GET /api/door-access/sync/{facilityId}/log请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/sync/{facilityId}/log \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设施的 Door/Gate Access 事件
在一个按时间倒序排列的信息流中返回移动端、管理员覆盖和外部 Partner API 解锁事件。
参数
facilityId `string` （必填） from `integer` （可选） to `integer` （可选） limit `integer` （可选）端点
GET /api/door-access/events/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/events/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为管理员测试模式定位点试运行地理围栏评估
请求正文
端点
POST /api/door-access/geofence/test请求示例
curl -X POST https://portal.hub.gymsystems.co/api/door-access/geofence/test \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
获取设施的入门/激活状态
驱动小程序的“Get Started”着陆页和设置进度横幅。返回实时的门和用户数量、两个派生的核心步骤（存在用户、存在门）、已保存的可选“已审核”标志，以及设施是否已激活（两个核心步骤均已完成）。设施首次激活时会记录 activatedAt 时间戳。
参数
facilityId `string` （必填）端点
GET /api/door-access/onboarding/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/door-access/onboarding/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新设施的可选入门“已审核”标志
保存管理员勾选的可选设置清单标志（访问规则、同步设置、地理围栏）。核心步骤和激活状态根据数据计数实时派生，无法在此设置。返回刷新后的完整入门状态。
参数
facilityId `string` （必填）请求正文
端点
PUT /api/door-access/onboarding/{facilityId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/door-access/onboarding/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
以 JSON 响应返回设施分析数据。
参数
clubId `string` （可选） 要检索分析数据的设施的 ID。 fromDate `string` （可选） 要检索的分析数据的开始日期。 toDate `string` （可选） 要检索的分析数据的结束日期。端点
GET /clubs/{clubId}/lead-events请求示例
curl -X GET https://portal.hub.gymsystems.co/clubs/{clubId}/lead-events \
-H "x-api-key: YOUR_API_KEY"
响应
{}
以 JSON 响应返回设施分析数据。
参数
clubId `string` （可选） 要检索分析数据的设施的 ID。 fromDate `string` （可选） 要检索的分析数据的开始日期。 toDate `string` （可选） 要检索的分析数据的结束日期。端点
GET /clubs/{clubId}/analytics/page-views请求示例
curl -X GET https://portal.hub.gymsystems.co/clubs/{clubId}/analytics/page-views \
-H "x-api-key: YOUR_API_KEY"
响应
{}
以 JSON 响应返回设施分析数据。
参数
clubId `string` （可选） 要检索分析数据的设施的 ID。 fromDate `string` （可选） 要检索的分析数据的开始日期。 toDate `string` （可选） 要检索的分析数据的结束日期。端点
GET /clubs/{clubId}/analytics/referrers请求示例
curl -X GET https://portal.hub.gymsystems.co/clubs/{clubId}/analytics/referrers \
-H "x-api-key: YOUR_API_KEY"
响应
{}
以 JSON 响应返回设施分析数据。
参数
clubId `string` （可选） 要检索分析数据的设施的 ID。 fromDate `string` （可选） 要检索的分析数据的开始日期。 toDate `string` （可选） 要检索的分析数据的结束日期。端点
GET /clubs/{clubId}/analytics/socials请求示例
curl -X GET https://portal.hub.gymsystems.co/clubs/{clubId}/analytics/socials \
-H "x-api-key: YOUR_API_KEY"
响应
{}
以 JSON 响应返回设施分析数据。
参数
clubId `string` （可选） 要检索分析数据的设施的 ID。 fromDate `string` （可选） 要检索的分析数据的开始日期。 toDate `string` （可选） 要检索的分析数据的结束日期。端点
GET /clubs/{clubId}/analytics/top-cities请求示例
curl -X GET https://portal.hub.gymsystems.co/clubs/{clubId}/analytics/top-cities \
-H "x-api-key: YOUR_API_KEY"
响应
{}
以 JSON 响应返回设施分析数据。
参数
clubId `string` （可选） 要检索分析数据的设施的 ID。 fromDate `string` （可选） 要检索的分析数据的开始日期。 toDate `string` （可选） 要检索的分析数据的结束日期。端点
GET /clubs/{clubId}/analytics/total-page-views请求示例
curl -X GET https://portal.hub.gymsystems.co/clubs/{clubId}/analytics/total-page-views \
-H "x-api-key: YOUR_API_KEY"
响应
{}
以 JSON 响应返回设施分析数据。
参数
clubId `string` （可选） 要检索分析数据的设施的 ID。 fromDate `string` （可选） 要检索的分析数据的开始日期。 toDate `string` （可选） 要检索的分析数据的结束日期。端点
GET /clubs/{clubId}/analytics/traffic请求示例
curl -X GET https://portal.hub.gymsystems.co/clubs/{clubId}/analytics/traffic \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为前端“analytics”页面中的 Google Analytics 可嵌入图表生成临时前端 JWT（JSON Web Token）。
端点
GET /api/ga/onetimetoken请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ga/onetimetoken \
-H "x-api-key: YOUR_API_KEY"
响应
{}
如果设施有任何活跃会员，则返回来自“The Training Camp”的仪表板小组件。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/reporting/apps/widgets/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/reporting/apps/widgets/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回所有未审核的设施假期。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/reporting/club/{club}/unreviewed-holidays请求示例
curl -X GET https://portal.hub.gymsystems.co/api/reporting/club/{club}/unreviewed-holidays \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将所有未审核的设施假期设为已审核。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
PUT /api/reporting/club/{club}/review-holidays请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/reporting/club/{club}/review-holidays \
-H "x-api-key: YOUR_API_KEY"
响应
{}
以 CSV 格式返回 KPI 报告，按过去 12 个月逐月细分。*注意*：此操作会为系统中的所有设施创建一份报告，请勿并行多次运行，否则会使 GymMaster 过载！
参数
months `string` （可选） 要获取的月数（从当前日期起算，默认为 12）端点
GET /api/reporting/gymmaster/all-clubs-kpi-report请求示例
curl -X GET https://portal.hub.gymsystems.co/api/reporting/gymmaster/all-clubs-kpi-report \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回指定设施的 MMS 收入图表。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 range `string` （可选） 要获取的范围天数（从当前日期向前倒数）端点
GET /api/reporting/gymmaster/revenuegraph/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/reporting/gymmaster/revenuegraph/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回指定设施的仪表板 MMS（会员管理系统）数据/分析。数据包括 GymMaster/Perfect Gym 统计信息以及我们系统收集的其他内部指标。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 range `string` （可选） 要获取的范围天数（从当前日期向前倒数）端点
GET /api/reporting/gymmaster/widgets/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/reporting/gymmaster/widgets/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回指定设施的仪表板 Myzone 小组件数据。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/reporting/myzone/widgets/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/reporting/myzone/widgets/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回被一个或多个状态页面/监控端点（通过内部“Uptime Kuma”工具配置）判定为离线的服务对象。
端点
GET /api/reporting/statuspage/events请求示例
curl -X GET https://portal.hub.gymsystems.co/api/reporting/statuspage/events \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回未来 7 天内即将进行的训练预约。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/reporting/clubs/{club}/workout-bookings请求示例
curl -X GET https://portal.hub.gymsystems.co/api/reporting/clubs/{club}/workout-bookings \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施的历史假期列表。
参数
clubId `string` （可选） 俱乐部 ID fromDate `string` （可选） 要返回的假期范围开始日期的 Unix 时间戳。 toDate `string` （可选） 要返回的假期范围结束日期的 Unix 时间戳。端点
GET /api/clubs/{clubId}/historical-holidays请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubId}/historical-holidays \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回与设施关联的设备自动化。
参数
club `string` （必填） 要列出其设备的俱乐部的内部 ID。端点
GET /api/ics/automations/list/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ics/automations/list/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新现有显示屏/设备的设备配置。
参数
club `string` （必填） 要更新设备的设施的内部 ID。 body `string` （必填） 更新参数的 JSON 对象。端点
POST /api/ics/automations/update/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ics/automations/update/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将物理屏幕设备/计算机添加或关联到您的设施。
参数
club `string` （必填） 要在其下添加设备的俱乐部的内部 ID。 body `string` （必填） 要关联的新屏幕的 JSON 对象。端点
POST /api/ics/devices/add/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ics/devices/add/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
指示设备根据参数连接到新的 SSID。
参数
club `string` （必填） 要更新设备的设施的内部 ID。 body `string` （必填） 更新参数的 JSON 对象。端点
POST /api/ics/devices/changewifi/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ics/devices/changewifi/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新现有显示屏/设备的设备配置。
参数
club `string` （必填） 要更新设备的设施的内部 ID。 body `string` （必填） 更新参数的 JSON 对象。端点
POST /api/ics/devices/command/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ics/devices/command/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在特定设备屏幕上加载 URL/网页。
参数
club `string` （必填） 要更新设备的设施的内部 ID。 body `string` （必填） 更新参数的 JSON 对象。端点
POST /api/ics/devices/loadurl/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ics/devices/loadurl/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新现有显示屏/设备的设备配置。
参数
club `string` （必填） 要更新设备的设施的内部 ID。 body `string` （必填） 更新参数的 JSON 对象。端点
PUT /api/ics/devices/update/{club}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/ics/devices/update/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
重命名显示屏/设备。仅更改注册信息：与更新端点不同，此操作不会向设备推送任何内容，因此也适用于运行已停止支持的软件版本的屏幕。
参数
club `string` （必填） 设备所属设施的内部 ID。 body `string` （必填） 重命名参数的 JSON 对象。端点
PUT /api/ics/devices/rename/{club}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/ics/devices/rename/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据提供的日期获取设施的小组件及离线媒体链接。
参数
club `string` （必填） 要更改模板内容的设施的内部 ID。 date `string` （必填） 返回小组件 URL 的日期，使用 `YYYY-MM-DD` 格式。端点
GET /api/ics/external-resources/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ics/external-resources/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据提供的日期获取设施的小组件及离线媒体链接。
参数
club `string` （必填） 要更改模板内容的设施的内部 ID。端点
GET /api/ics/list-scheduled-workouts/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ics/list-scheduled-workouts/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更改指定设施的模板内容。
参数
club `string` （必填） 要更改模板内容的设施的内部 ID。 body `string` （必填） 要更改的新模板内容的 JSON 对象。端点
POST /api/ics/loadprogram/{club}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ics/loadprogram/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
检索现有显示屏/设备的节目配置。
参数
club `string` （必填） 要检索节目数据的设施的内部 ID。端点
GET /api/ics/programs/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ics/programs/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新现有显示屏/设备的节目配置。
参数
club `string` （必填） 要更新设备的设施的内部 ID。 body `string` （必填） 更新参数的 JSON 对象。端点
PUT /api/ics/programs/{club}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/ics/programs/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
检索节目配置选项。
端点
GET /api/ics/programs/options/{facilityID}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ics/programs/options/{facilityID} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
使用 RAG 上下文聊天。此功能无法访问工具，只有一个简单的 API 请求/响应工具，可让您直接从知识库中获取知识。
参数
organisationId `string` （可选） 组织 ID（如未提供将自动检测）请求正文
端点
POST /api/llm/chat请求示例
curl -X POST https://portal.hub.gymsystems.co/api/llm/chat \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
从向量存储中删除文章嵌入并更新嵌入跟踪状态
请求正文
端点
DELETE /api/llm/delete-article请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/llm/delete-article \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
按组织和状态列出嵌入跟踪记录
参数
organisationId `string` （可选） 组织 ID（省略时自动解析） status `string` （必填） 用于筛选的状态（必须是 in_queue、done、anomaly、fail、deleted 之一） Limit `string` （可选） 每页最大条目数 LastEvaluatedKey `string` （可选） 用于分页的 DynamoDB LastEvaluatedKey 的 JSON端点
GET /api/llm/embedding-track/by-org-and-status请求示例
curl -X GET https://portal.hub.gymsystems.co/api/llm/embedding-track/by-org-and-status \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按组织列出嵌入跟踪记录（可选按资源类型筛选）
参数
organisationId `string` （可选） 组织 ID（省略时自动解析） resourceType `string` （可选） 可选的资源类型（例如 "article"）。提供时，筛选 resourceTypeId 以 "{type}#" 开头的记录。 Limit `string` （可选） 每页最大条目数 LastEvaluatedKey `string` （可选） 用于分页的 DynamoDB LastEvaluatedKey 的 JSON端点
GET /api/llm/embedding-track/by-org请求示例
curl -X GET https://portal.hub.gymsystems.co/api/llm/embedding-track/by-org \
-H "x-api-key: YOUR_API_KEY"
响应
{}
初始化组织的向量数据库集合
参数
organisationId `string` （可选） 组织 ID（如未提供将自动检测）端点
POST /api/llm/init-org请求示例
curl -X POST https://portal.hub.gymsystems.co/api/llm/init-org \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在知识库中进行语义搜索
参数
organisationId `string` （可选） 组织 ID（如未提供将自动检测）请求正文
端点
POST /api/llm/semantic-search请求示例
curl -X POST https://portal.hub.gymsystems.co/api/llm/semantic-search \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
开始以流式方式处理队列中待嵌入的文章，并实时更新进度
参数
organisationId `string` （可选） 组织 ID（如未提供将自动检测）端点
POST /api/llm/start-embedding-stream请求示例
curl -X POST https://portal.hub.gymsystems.co/api/llm/start-embedding-stream \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将文章嵌入更新插入向量数据库
根据当前状态处理文章嵌入： - 如果文章未发布或为私有：删除嵌入 - 如果文章已发布且为公开：使用完整内容重新嵌入 始终需要完整的文章正文。
参数
organisationId `string` （可选） 组织 ID（如未提供将自动检测）请求正文
端点
POST /api/llm/upsert-embeddings请求示例
curl -X POST https://portal.hub.gymsystems.co/api/llm/upsert-embeddings \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
按组织及可选状态批量删除文章嵌入的测试端点
参数
organisationId `string` （可选） 组织 ID（省略时根据用户上下文自动解析） status `string` （可选） 用于筛选的状态（可选；如果省略，将删除该组织的所有文章，无论其状态如何） hardDelete `string` （可选） 是硬删除嵌入跟踪记录（true），还是通过更新状态进行软删除（false）端点
DELETE /api/llm/test/batch-delete-by-status请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/llm/test/batch-delete-by-status \
-H "x-api-key: YOUR_API_KEY"
响应
{}
转换文本并分块，提供详细统计信息
此测试端点会转换文本并将其分块，然后提供有关分块分布的详细统计信息，包括字符数、百分比和质量指标，以帮助评估分块效果。
请求正文
端点
POST /api/llm/test/transform-chunk请求示例
curl -X POST https://portal.hub.gymsystems.co/api/llm/test/transform-chunk \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
获取组织向量索引中的向量总数
统计当前用户所属组织向量索引中所有向量的测试端点
参数
organisationId `string` （可选） 组织 ID（如未提供将自动检测）端点
GET /api/llm/test/vector-count请求示例
curl -X GET https://portal.hub.gymsystems.co/api/llm/test/vector-count \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从向量索引中删除特定 articleId 的所有向量
从当前用户所属组织的向量索引中删除与特定 articleId 关联的所有向量的测试端点。
参数
organisationId `string` （可选） 组织 ID（如未提供将自动检测） articleId `string` （必填） 要删除向量的 articleId dryRun `string` （可选） 如果为 true，只显示将被删除的内容，而不实际删除端点
DELETE /api/llm/test/vector-delete-article请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/llm/test/vector-delete-article \
-H "x-api-key: YOUR_API_KEY"
响应
{}
通过列出所有索引测试 Vector SDK
验证 Vector SDK 连接并列出向量存储桶中所有索引的测试端点
端点
GET /api/llm/test/vector-indices请求示例
curl -X GET https://portal.hub.gymsystems.co/api/llm/test/vector-indices \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为组织初始化向量索引
为当前用户所属组织创建向量存储桶和索引
参数
organisationId `string` （可选） 组织 ID（如未提供将自动检测）端点
POST /api/llm/test/vector-init-index请求示例
curl -X POST https://portal.hub.gymsystems.co/api/llm/test/vector-init-index \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取特定 articleId 的所有向量元数据
从向量索引中检索特定 articleId 的所有向量分块及其元数据的测试端点。可用于检查文章的分块和存储方式。筛选由向量存储服务处理。
参数
organisationId `string` （可选） 组织 ID（如未提供将自动检测） articleId `string` （必填） 要检索向量元数据的文章 ID端点
GET /api/llm/test/vector-metadata-by-article请求示例
curl -X GET https://portal.hub.gymsystems.co/api/llm/test/vector-metadata-by-article \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从向量索引中获取最近的向量及其元数据
从当前用户所属组织的向量索引中检索最近 10 个向量及其元数据（不含向量数据）的测试端点。可用于检查元数据结构。
参数
organisationId `string` （可选） 组织 ID（如未提供将自动检测） limit `string` （可选） 要返回的最近向量数量（最多 100）端点
GET /api/llm/test/vector-recent请求示例
curl -X GET https://portal.hub.gymsystems.co/api/llm/test/vector-recent \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将营销经理/设计器使用的素材上传到 S3 存储。
参数
file `string` （可选） 要上传的文件/素材的名称。端点
POST /api/marketing/design/static/download请求示例
curl -X POST https://portal.hub.gymsystems.co/api/marketing/design/static/download \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回单个素材的 JSON 格式，以加载到素材管理器中。
参数
id `string` （必填） 要获取的素材的 ID。 organisationId `string` （必填） 素材所属设施的组织 ID。端点
GET /api/marketing/assets/get/{id}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/assets/get/{id} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回所有设计素材。
参数
body `string` （必填） 要保存的设施数据的 JSON 对象。 organisationId `string` （必填） 素材所属设施的组织 ID。 useCache `string` （可选） search `string` （可选） 按名称或标签筛选素材的搜索查询。 brand `string` （可选） 用于筛选素材的品牌。 tag `string` （可选） 用于筛选素材的标签。端点
GET /api/marketing/assets/get请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/assets/get \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回组织的营销印刷素材的单页结果。使用 Algolia 进行相关性搜索和基于页码的分页（含总数），当 Algolia 不可用时回退到 DynamoDB。
参数
organisationId `string` （必填） 素材所属设施的组织 ID。 search `string` （可选） 按名称或标签筛选素材的搜索查询。 brand `string` （可选） 用于筛选素材的品牌。 tag `string` （可选） 用于筛选素材的标签。 page `string` （可选） 要获取的页码（从零开始）。 limit `string` （可选） 每页素材数量（最多 300）。 useCache `string` （可选） 为 false 时，绕过 Algolia 直接查询 DynamoDB。端点
GET /api/marketing/assets请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/assets \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回通过素材管理器上传的可用素材列表。
参数
organisationId `string` （必填）端点
GET /api/marketing/assets/list请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/assets/list \
-H "x-api-key: YOUR_API_KEY"
响应
{}
添加/保存素材。
参数
body `string` （必填） 要保存的设施数据的 JSON 对象。 organisationId `string` （必填） 素材所属设施的组织 ID。端点
PUT /api/marketing/assets/save请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/marketing/assets/save \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将营销经理/设计器使用的素材上传到 S3 存储。
参数
file `string` （可选） 要上传的文件/素材的名称。 organisationId `string` （可选） 素材所属组织的 ID。端点
POST /api/marketing/assets/upload请求示例
curl -X POST https://portal.hub.gymsystems.co/api/marketing/assets/upload \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回组织的所有自定义页面列表。
参数
organisationId `string` （必填） 要返回自定义页面的组织的内部 ID。端点
GET /api/marketing/custom-pages请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/custom-pages \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为组织更新插入自定义页面。
参数
organisationId `string` （必填） 要返回自定义页面的组织的内部 ID。 body `object` （必填） 要更新插入的自定义页面数据。端点
PUT /api/marketing/custom-pages请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/marketing/custom-pages \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施的所有自定义页面列表。
参数
facilityId `string` （必填） 要返回自定义页面的设施的内部 ID。端点
GET /api/facilities/{facilityId}/marketing/custom-pages请求示例
curl -X GET https://portal.hub.gymsystems.co/api/facilities/{facilityId}/marketing/custom-pages \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回特定设施 ID 的所有已导出/已渲染设计。
参数
club `string` （必填） 发出请求的设施的内部 ID。 sort `string` （可选） 设计的排序方式，支持 'oldest'、'newest' 或 'design'。端点
GET /api/marketing/designs/{club}/exports请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/designs/{club}/exports \
-H "x-api-key: YOUR_API_KEY"
响应
{}
以 JSON 格式返回设计的单个 HTML 内容，以加载到编辑器中。
参数
id `string` （必填） 要获取的设计的 ID。端点
GET /api/marketing/designs/get/{id}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/designs/get/{id} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回营销和印刷设计及设计模板中的输入映射列表
参数
clubId `string` （必填） 发出请求的设施的内部 ID。 availableFeatures `string` （可选） 返回具有特定功能的所有条目 brand `string` （可选） 按品牌筛选设计 features `string` （可选） 根据功能筛选结果端点
GET /api/marketing/designs/input-mapping/{clubId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/designs/input-mapping/{clubId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回指定设施的可用设计列表，这些设计可用于在 Hub 的营销/印刷编辑器中创建的设计（印刷设计）。
参数
club `string` （必填） 发出请求的设施的内部 ID。 designAdmin `string` （可选） 返回所有设计数据（管理员视图，要求用户为管理员）。 brand `string` （可选） 按品牌筛选设计端点
GET /api/marketing/designs/{club}/list请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/designs/{club}/list \
-H "x-api-key: YOUR_API_KEY"
响应
{}
强制系统渲染或重新渲染所有设计缩略图和预览（主要在我们更改 S3 等中的“上游”素材时使用）。**注意**：每 X 分钟只能调用一次此函数（如果渲染已在运行，则无法调用此函数）。这是为了确保渲染所有设计时不会给服务器带来过大负载。
端点
GET /api/marketing/designs/render-all-thumbnails请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/designs/render-all-thumbnails \
-H "x-api-key: YOUR_API_KEY"
响应
{}
启动动态设计的渲染
参数
body `string` （必填） 要发送到设计渲染处理器的设施数据的 JSON 对象。端点
POST /api/marketing/designs/dynamic/render-design请求示例
curl -X POST https://portal.hub.gymsystems.co/api/marketing/designs/dynamic/render-design \
-H "x-api-key: YOUR_API_KEY"
响应
{}
添加/保存/更新设计。
参数
body `string` （必填） 要保存的设施数据的 JSON 对象。端点
PUT /api/marketing/designs/{club}/save请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/marketing/designs/{club}/save \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回要加载的单个静态设计 JSON 格式
参数
id `string` （必填） 要获取的静态设计的 ID。端点
GET /api/marketing/designs/static/get/{id}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/designs/static/get/{id} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
添加/保存/更新静态设计模板。
参数
body `string` （必填） 要保存的设施数据的 JSON 对象。端点
PUT /api/marketing/designs/static/{club}/save请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/marketing/designs/static/{club}/save \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从系统中移除用户设置的变量。
参数
club `string` （必填） 发出请求的设施的内部 ID。 body `string` （必填） 包含要移除的变量 ID 的 JSON。端点
DELETE /api/marketing/variables/{club}/delete请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/marketing/variables/{club}/delete \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回指定设施的可用变量列表，这些变量可用于在 Hub 的营销/印刷编辑器中创建的设计（印刷设计）。
参数
club `string` （必填） 发出请求的设施的内部 ID。端点
GET /api/marketing/variables/{club}/list请求示例
curl -X GET https://portal.hub.gymsystems.co/api/marketing/variables/{club}/list \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为指定设施创建一个新的用户“变量”。
参数
club `string` （必填） 发出请求的设施的内部 ID。 body `string` （必填） 新变量的 JSON 对象。端点
POST /api/marketing/variables/{club}/new请求示例
curl -X POST https://portal.hub.gymsystems.co/api/marketing/variables/{club}/new \
-H "x-api-key: YOUR_API_KEY"
响应
{}
通过对象数组在系统中添加/保存/更新一个或多个设计变量。
参数
club `string` （必填） 发出请求的设施的内部 ID。 body `string` （必填） 要添加/更新的一个或多个 JSON 对象的数组（允许在一个 API 请求中保存多个条目/对象）。端点
PUT /api/marketing/variables/{club}/save请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/marketing/variables/{club}/save \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回已登录用户的 MCP 文档清单
为应用内的 `/mcp-docs` 页面提供数据。返回 MCP 服务器 URL、支持的认证标头、调用者的身份/管理员标志，以及经过筛选的工具列表（筛选方式与 `/mcp/tools/list` 完全相同，因此文档页面永远不会显示调用者实际无法使用的工具）。
端点
GET /api/mcp/docs-manifest请求示例
curl -X GET https://portal.hub.gymsystems.co/api/mcp/docs-manifest \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建用户协议。
参数
body `object` （必填） 要保存的设施数据的 JSON 对象。端点
POST /api/member-agreements/contracts-tna/:club请求示例
curl -X POST https://portal.hub.gymsystems.co/api/member-agreements/contracts-tna/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回协议列表。
端点
GET /api/member-agreements/contracts-tna/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/member-agreements/contracts-tna/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除用户协议。
端点
DELETE /api/member-agreements/contracts-tna/:club/:id请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/member-agreements/contracts-tna/:club/:id \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回特定协议。
端点
GET /api/member-agreements/contracts-tna/:club/:id请求示例
curl -X GET https://portal.hub.gymsystems.co/api/member-agreements/contracts-tna/:club/:id \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新用户协议。
参数
body `object` （必填） 要保存的设施数据的 JSON 对象。端点
PATCH /api/member-agreements/contracts-tna/:club/:id请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/member-agreements/contracts-tna/:club/:id \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取设施的默认协议。
参数
body `object` （必填） 要保存的设施数据的 JSON 对象。端点
GET /api/member-agreements/default-tna/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/member-agreements/default-tna/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
设置设施的默认协议。
参数
body `object` （必填） 要保存的设施数据的 JSON 对象。端点
POST /api/member-agreements/default-tna/:club请求示例
curl -X POST https://portal.hub.gymsystems.co/api/member-agreements/default-tna/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回全局或区域协议列表。
端点
GET /api/member-agreements/global-tna/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/member-agreements/global-tna/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回已签署协议的会员列表。
端点
GET /api/member-agreements/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/member-agreements/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按赛季返回训练营应用的设施会员列表。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 season `string` （可选） 要筛选的训练营赛季。 userIds `string` （可选） 要筛选的用户 ID 数组。 useCache `string` （可选） 是否使用缓存。 isUserMemberInfo `string` （可选） 如果启用，将根据 userIds 筛选数据（建议只使用一个用户 ID），并包含排行榜和用户偏好等必要数据。端点
GET /api/members-leads/trainingcamp/club/season-members/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/members-leads/trainingcamp/club/season-members/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除多个训练预约潜在客户。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 body `string` （必填）端点
DELETE /api/members-leads/workout-booking/club/leads/{club}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/members-leads/workout-booking/club/leads/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施的训练预约潜在客户列表。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 all `string` （可选） 显示所有潜在客户还是仅显示即将到来的潜在客户。端点
GET /api/members-leads/workout-booking/club/leads/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/members-leads/workout-booking/club/leads/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新训练预约潜在客户。
参数
club `string` （必填） 要访问的俱乐部的内部 ID。 body `string` （必填）端点
PUT /api/members-leads/workout-booking/club/leads/{club}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/members-leads/workout-booking/club/leads/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
切换训练预约潜在客户的标记状态。
参数
club `string` （必填） 俱乐部的内部 ID。 body `string` （必填）端点
PATCH /api/members-leads/workout-booking/club/leads/{club}/flag请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/members-leads/workout-booking/club/leads/{club}/flag \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取设施的有效模块
通过解析层级（设施偏好 → 品牌模块 → 组织模块）返回设施可用的所有模块。为提高性能，结果缓存在 Redis 中。
参数
facilityId `string` （必填） 要解析模块的设施 ID端点
GET /api/facilities/{facilityId}/modules请求示例
curl -X GET https://portal.hub.gymsystems.co/api/facilities/{facilityId}/modules \
-H "x-api-key: YOUR_API_KEY"
响应
[]
返回模块目录以及侧边菜单渲染配置。返回完整的模块列表，以便前端渲染器按用户决定可见性；ACL 仍通过 `auth.checkModuleAccess()` 在服务器端执行。
端点
GET /api/modules请求示例
curl -X GET https://portal.hub.gymsystems.co/api/modules \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取通知类别。
端点
GET /api/notification/categories请求示例
curl -X GET https://portal.hub.gymsystems.co/api/notification/categories \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除已读通知。
端点
DELETE /api/club/notification/consumed/:club请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/club/notification/consumed/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建通知消息。
端点
POST /api/club/notification/consumed/:club请求示例
curl -X POST https://portal.hub.gymsystems.co/api/club/notification/consumed/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回已读通知数组。
端点
GET /api/club/notification/consumed/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/club/notification/consumed/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除通知消息。
端点
DELETE /api/club/notification/messages/:club请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/club/notification/messages/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回通知消息数组。
端点
GET /api/club/notification/messages/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/club/notification/messages/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新通知消息。
端点
PATCH /api/club/notification/messages/:club请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/club/notification/messages/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建通知消息。
参数
body `string` （必填）端点
POST /api/club/notification/messages/:club请求示例
curl -X POST https://portal.hub.gymsystems.co/api/club/notification/messages/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按设施获取通知的查看者。
端点
POST /api/club/notification/viewers/:club请求示例
curl -X POST https://portal.hub.gymsystems.co/api/club/notification/viewers/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按用户获取通知类别。
端点
GET /api/club/notification/user-categories/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/club/notification/user-categories/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建通知消息。
端点
POST /api/notification/webhook请求示例
curl -X POST https://portal.hub.gymsystems.co/api/notification/webhook \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取用于 HTML5 推送的 VAPID 公钥
返回用于创建浏览器推送订阅的 VAPID 公钥。
端点
GET /html5-push/vapid-public-key请求示例
curl -X GET https://portal.hub.gymsystems.co/html5-push/vapid-public-key \
-H "x-api-key: YOUR_API_KEY"
响应
{}
保存或更新 HTML5 推送订阅
为当前用户保存浏览器推送订阅。
请求正文
端点
POST /html5-push/subscribe请求示例
curl -X POST https://portal.hub.gymsystems.co/html5-push/subscribe \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
删除 HTML5 推送订阅
为当前用户移除浏览器推送订阅。
请求正文
端点
POST /html5-push/unsubscribe请求示例
curl -X POST https://portal.hub.gymsystems.co/html5-push/unsubscribe \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
获取调用用户的地点入门状态
返回设施入门的两个部分：设置（详细信息 + 产品选择，存储在设施偏好中）和付款（根据 SaaS 计费付款设置记录实时派生），以及一个供应用外壳判断是否拦截的、按调用者个性化的 `required` 标志。仅适用于技术套件地点；业务套件地点始终返回 required=false。
参数
facilityId `string` （必填）端点
GET /api/onboarding/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/onboarding/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
保存设施入门向导的进行中进度
保存部分向导状态（产品选择、“Other”自由文本、已审核的业务详细信息、当前步骤），以便刷新或中途离开后可从用户上次停下的位置继续。从不标记完成，请参见完成端点。
参数
facilityId `string` （必填）请求正文
端点
PUT /api/onboarding/{facilityId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/onboarding/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
为入门向导生成 AI 预填建议
利用现有的设施/品牌/组织上下文，建议设施详细信息（简介文案、整理后的联系方式字段）、建议的产品选择以及简短的个性化提示。结果在 Redis 中缓存 7 天。建议仅供参考，客户端会将其渲染到可编辑的审核表单中。始终返回 200；当 AI 不可用时 `suggestions` 为 null，使向导可以平稳降级。
参数
facilityId `string` （必填）端点
POST /api/onboarding/{facilityId}/ai-prefill请求示例
curl -X POST https://portal.hub.gymsystems.co/api/onboarding/{facilityId}/ai-prefill \
-H "x-api-key: YOUR_API_KEY"
响应
{}
完成地点入门的设置部分
验证已确认的选择/详细信息，将业务详细信息保存到设施记录，根据产品选择初始化设施技术菜单布局（除非已存在自定义布局），并标记设置完成。付款部分有意无法在此完成：它根据 SaaS 计费付款设置记录实时派生，因此无法通过调用此端点绕过必须绑定银行卡的要求。返回刷新后的状态。
参数
facilityId `string` （必填）请求正文
端点
POST /api/onboarding/{facilityId}/complete请求示例
curl -X POST https://portal.hub.gymsystems.co/api/onboarding/{facilityId}/complete \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
为设施触发已声明的合作伙伴集成操作
运行在合作伙伴记录（ph-partners.actions[]）中声明的“Run integration”操作，范围限定于某个设施。Redis 单飞锁可防止同一操作 + 设施的手动运行并发执行。
参数
partnerId `string` （必填） actionId `string` （必填）请求正文
端点
POST /api/partners/{partnerId}/actions/{actionId}/run请求示例
curl -X POST https://portal.hub.gymsystems.co/api/partners/{partnerId}/actions/{actionId}/run \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
读取合作伙伴集成操作的运行状态
返回当前是否有手动运行正在进行（持有单飞锁）以及最近一次请求的运行，供设置按钮轮询。
参数
partnerId `string` （必填） actionId `string` （必填） facilityId `string` （必填）端点
GET /api/partners/{partnerId}/actions/{actionId}/status请求示例
curl -X GET https://portal.hub.gymsystems.co/api/partners/{partnerId}/actions/{actionId}/status \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取品牌的所有合作伙伴配置
参数
brandId `string` （必填） 品牌 ID端点
GET /api/partners/brand-config/{brandId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/partners/brand-config/{brandId} \
-H "x-api-key: YOUR_API_KEY"
响应
[]
创建或更新品牌合作伙伴配置
参数
body `object` （必填）端点
PUT /api/partners/brand-config请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/partners/brand-config \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将 GymMaster 集成数据迁移到 facility-partner-config
查询所有带有 gymMasterAPI 和 gymMasterDomain 字段的设施，并创建或更新对应的 facility-partner-config 记录。这是一个一次性迁移端点。
参数
partnerId `string` （必填） 所有迁移记录使用的 GymMaster 合作伙伴 ID dryRun `boolean` （可选） 如果为 true，只报告将要迁移的内容，而不写入数据库端点
GET /api/partners/migrate-gymmaster请求示例
curl -X GET https://portal.hub.gymsystems.co/api/partners/migrate-gymmaster \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为组织启用合作伙伴。
参数
partnerId `string` （必填） 合作伙伴的 ID端点
POST /api/partners/organisation/enable请求示例
curl -X POST https://portal.hub.gymsystems.co/api/partners/organisation/enable \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出组织合作伙伴。组织管理员只能看到其所在组织的合作伙伴。
端点
GET /api/partners/organisation请求示例
curl -X GET https://portal.hub.gymsystems.co/api/partners/organisation \
-H "x-api-key: YOUR_API_KEY"
响应
{}
移除组织合作伙伴。
参数
keyId `string` （必填） 组织合作伙伴的键 ID organisationId `string` （必填） 合作伙伴的组织 ID端点
DELETE /api/partners/organisation/{keyId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/partners/organisation/{keyId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新组织合作伙伴的访问模式和模块。
参数
keyId `string` （必填） 组织合作伙伴的键 ID organisationId `string` （必填） 合作伙伴的组织 ID partnerId `string` （必填） 合作伙伴 ID accessMode `string` （必填） 合作伙伴的访问模式 modules `string` （可选） LIMITED 访问模式下的模块列表端点
PUT /api/partners/organisation/update-access请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/partners/organisation/update-access \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为设施创建签到记录
接受签到对象数组，并将其转发给 Partner API 处理。 每个请求最多 25 条签到记录。
请求正文
端点
POST /api/partners/check-ins请求示例
curl -X POST https://portal.hub.gymsystems.co/api/partners/check-ins \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
删除设施的合作伙伴配置
移除设施中某个合作伙伴集成的配置
参数
facilityId `string` （必填） 设施 ID（club ID） partnerId `string` （必填） 合作伙伴 ID端点
DELETE /api/partners/facility-config/{facilityId}/{partnerId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/partners/facility-config/{facilityId}/{partnerId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设施的所有合作伙伴配置
返回为指定设施配置的所有合作伙伴集成
参数
facilityId `string` （必填） 设施 ID（club ID）端点
GET /api/partners/facility-config/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/partners/facility-config/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建或更新设施的合作伙伴配置
更新插入设施中某个合作伙伴集成的配置
请求正文
端点
POST /api/partners/facility-config请求示例
curl -X POST https://portal.hub.gymsystems.co/api/partners/facility-config \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
按 memberId 删除会员
使用 memberId 删除现有会员记录。
参数
memberId `string` （必填） 会员的唯一标识符端点
DELETE /api/partners/members/{memberId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/partners/members/{memberId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按 memberId 更新会员
使用 memberId 更新现有会员记录。
参数
memberId `string` （必填） 会员的唯一标识符请求正文
端点
PUT /api/partners/members/{memberId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/partners/members/{memberId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
获取会员同步操作的状态
返回通过 POST /api/partners/members 或 DELETE /api/partners/members/{memberId} 启动的异步会员创建/删除操作的当前状态。前端轮询此端点，以替代旧版的列表轮询 + 名称匹配流程。 注意：多租户隔离规则要求按行限定 partnerId/facilityId 范围，但此项已推迟到第 3a.1 阶段的加固 PR 中实施。operationId 是 128 位 UUID，并且该路由已受 `external-integrations` 模块访问权限控制。任何持有有效 operationId 和管理模块访问权限的人都可以查询其状态。
参数
operationId `string` （必填） POST/DELETE 返回的 UUID端点
GET /api/partners/members/operations/{operationId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/partners/members/operations/{operationId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为设施创建或更新会员
接受会员对象数组，并将其转发给 Partner API 处理。 每个请求最多 25 名会员。
请求正文
端点
POST /api/partners/members请求示例
curl -X POST https://portal.hub.gymsystems.co/api/partners/members \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
为设施创建或更新会籍计划
接受会籍计划对象数组，并将其转发给 Partner API 处理。 每个请求最多 25 个会籍计划。
请求正文
端点
POST /api/partners/membership-plans请求示例
curl -X POST https://portal.hub.gymsystems.co/api/partners/membership-plans \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
创建新角色
参数
body `string` （必填） 角色对象端点
POST /api/roles请求示例
curl -X POST https://portal.hub.gymsystems.co/api/roles \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回所有角色的列表
端点
GET /api/roles请求示例
curl -X GET https://portal.hub.gymsystems.co/api/roles \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按 ID 删除角色
端点
DELETE /api/roles/{roleId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/roles/{roleId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按 ID 更新角色
参数
body `string` （必填） 角色对象端点
PUT /api/roles/{roleId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/roles/{roleId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为 SaaS 计费发票创建新的附加项目
参数
organisationId `string` （可选） 要为其创建附加项目的组织 ID body `string` （可选） 请求正文端点
POST /api/saas-billing/additional-line-items请求示例
curl -X POST https://portal.hub.gymsystems.co/api/saas-billing/additional-line-items \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回 SaaS 计费发票的附加项目列表
参数
organisationId `string` （必填） 组织 ID端点
GET /api/saas-billing/additional-line-items请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/additional-line-items \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施 SaaS 计费发票的附加项目列表
端点
GET /api/clubs/{clubId}/saas-billing/additional-line-items请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubId}/saas-billing/additional-line-items \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新 SaaS 计费发票的附加项目
参数
itemId `string` （必填） 要更新的附加项目的 ID body `string` （必填） 请求正文端点
PUT /api/saas-billing/additional-line-items/{itemId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/saas-billing/additional-line-items/{itemId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
Your Rates 中的 Cloud Agent 合并小时费率
返回所提供的 Cloud Agent 规格，每种规格只有一个合并的小时价格（托管 + 软件），不包含拆分明细。usedPlans 是此设施在过去 30 天内运行过的 SKU。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/saas-billing/cloud-agent-rates请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/cloud-agent-rates \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除已导入的月度报告
参数
club `string` （可选） 俱乐部 ID reportId `string` （可选） 报告 ID端点
DELETE /api/saas-billing/extended-access/monthly-usage-report/{reportId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/saas-billing/extended-access/monthly-usage-report/{reportId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取设施最新的 CCTV 存储报告
从已存储的计费日志（最多过去 31 天）中返回设施最新的每日 CCTV 存储快照。包括 totalStorage、日期以及与存储相关的费用。
参数
club `string` （必填） 俱乐部 ID端点
GET /api/saas-billing/extended-access/latest-cctv-storage-report/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/extended-access/latest-cctv-storage-report/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施指定期间的 PDF 发票。
参数
club `string` （可选） 俱乐部 ID month `string` （可选） 报告月份的数字格式。1 = 一月，2 = 二月，依此类推。 year `string` （可选） 报告年份的数字格式，例如 2021端点
GET /api/saas-billing/extended-access/monthly-usage-report/:club/invoice请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/extended-access/monthly-usage-report/:club/invoice \
-H "x-api-key: YOUR_API_KEY"
响应
{}
所选使用月份的平台发票 PDF 合集（ZIP 格式）。这是单个 .../invoice 端点的批量版本，为 Billing & Cost Management 小程序 Invoices & Receipts 选项卡中的多选下载提供支持。
参数
club `string` （可选） 俱乐部 ID months `string` （可选） 以逗号分隔的使用/报告月份，格式为 YYYY-MM（最多 24 个）端点
GET /api/saas-billing/extended-access/monthly-usage-report/{club}/invoices.zip请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/extended-access/monthly-usage-report/{club}/invoices.zip \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在一次调用中返回多个使用月份的月度使用报告。为 Billing & Cost Management 小程序中的 Cost History 图表和逐月变化提供支持。尚无使用量的月份返回 report: null（与单月端点的 404 → $0 界面行为一致）。
参数
club `string` （可选） 俱乐部 ID months `string` （可选） 以逗号分隔的使用月份，格式为 YYYY-MM（最多 12 个）端点
GET /api/saas-billing/extended-access/monthly-usage-report/{club}/batch请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/extended-access/monthly-usage-report/{club}/batch \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为设施导入月度报告。
参数
club `string` （可选） 俱乐部 ID端点
PUT /api/saas-billing/extended-access/usage-report/:club请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/saas-billing/extended-access/usage-report/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回所有设施过去 30 天 CCTV 使用情况的 CSV 报告。
端点
GET /api/saas-billing/extended-access/usage-report/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/extended-access/usage-report/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设施当月的所有每日报告。
参数
club `string` （可选） 俱乐部 ID month `string` （可选） 报告月份的数字格式。1 = 一月，2 = 二月，依此类推。 year `string` （可选） 报告年份的数字格式，例如 2021端点
GET /api/saas-billing/extended-access/monthly-usage-report/{club}/daily-reports请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/extended-access/monthly-usage-report/{club}/daily-reports \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为管理员返回已导入的月度报告列表
参数
organisationId `string` （必填） 组织 ID端点
GET /api/saas-billing/extended-access/usage-report/imported请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/extended-access/usage-report/imported \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回所有设施过去 30 天 CCTV 使用情况的 CSV 报告。
参数
club `string` （可选） 俱乐部 ID month `string` （可选） 报告月份的数字格式。1 = 一月，2 = 二月，依此类推。 year `string` （可选） 报告年份的数字格式，例如 2021端点
GET /api/saas-billing/extended-access/monthly-usage-report/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/extended-access/monthly-usage-report/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施的定期使用报告。
参数
club `string` （可选） 俱乐部 ID periodStart `string` （可选） 期间的开始日期，格式为 YYYY-MM-DD periodEnd `string` （可选） 期间的结束日期，格式为 YYYY-MM-DD端点
GET /api/saas-billing/extended-access/periodical-usage-report/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/extended-access/periodical-usage-report/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将多种类型的计费文档 PDF 打包为一个 ZIP：平台发票（按使用月份）、SaaS 钱包充值收据以及 Model Router 充值收据。这是按类型的 invoices.zip / receipts.zip 端点的批量版本，供合并后的 Invoices & Receipts 选项卡使用。请求的每个月份/ID 都必须对应该设施拥有的文档，任何无效值都会导致整个打包失败。
参数
clubID `string` （必填） invoiceMonths `string` （可选） 以逗号分隔的使用月份，格式为 YYYY-MM walletIds `string` （可选） 以逗号分隔的 SaaS 钱包充值交易 ID aiIds `string` （可选） 以逗号分隔的 Model Router 充值交易 ID端点
GET /api/clubs/{clubID}/saas-billing/documents.zip请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/documents.zip \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为月度记录添加备注
参数
recordID `string` （可选） 要获取的记录的 ID note `string` （可选） 要添加到记录的备注端点
POST /api/saas-billing/monthly-records/{recordID}/notes请求示例
curl -X POST https://portal.hub.gymsystems.co/api/saas-billing/monthly-records/{recordID}/notes \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回 SaaS 计费月度记录列表
参数
club `string` （可选） 要获取的设施的 ID month `string` （可选） 计费月份，格式为 YYYY-MM端点
GET /api/saas-billing/monthly-records/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/monthly-records/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回失败或需要 3D Secure 验证的 SaaS 计费月度记录列表
参数
clubID `string` （可选） 要获取失败月度记录的设施的 ID端点
GET /api/clubs/:clubID/saas-billing/flagged请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/:clubID/saas-billing/flagged \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施的所有 SaaS 计费月度记录（发票账簿），最新的计费月份在前。这是仅限管理员的 paginate-monthly-records 端点的设施级版本，为 Billing & Cost Management 小程序中面向客户的“Invoices & Receipts”选项卡提供支持。
参数
clubID `string` （可选） 要列出月度记录的设施的 ID端点
GET /api/clubs/{clubID}/saas-billing/monthly-records请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/monthly-records \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回 SaaS 计费月度记录列表
参数
organisationId `string` （可选） 组织 ID month `string` （可选） 月份，格式为 MM。 year `string` （可选） 年份，格式为 YYYY。 filters `string` （可选） 数据表生成的查询字符串筛选条件。 order `string` （可选） 数据表生成的查询字符串。端点
GET /api/saas-billing/monthly-records请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/monthly-records \
-H "x-api-key: YOUR_API_KEY"
响应
{}
重试设施的失败付款
参数
clubID `string` （可选） 要获取失败月度记录的设施的 ID端点
PUT /api/clubs/:clubID/saas-billing/retry-failed-payments请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/:clubID/saas-billing/retry-failed-payments \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新月度记录
参数
recordID `string` （可选） 要获取的记录的 ID status `string` （可选） 要将记录更新为的状态端点
PUT /api/saas-billing/monthly-records/{recordID}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/saas-billing/monthly-records/{recordID} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
检查付款是否成功并更新记录的状态
参数
clubID `string` （可选） recordID `string` （可选） 要获取的记录的 ID端点
PUT /api/clubs/{clubID}/saas-billing/monthly-records/{recordID}/validate请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/monthly-records/{recordID}/validate \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为设施添加付款方式。
参数
clubID `string` （可选）端点
POST /api/clubs/{clubID}/saas-billing/payment-settings/payment-methods请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/payment-settings/payment-methods \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将设施的付款方式与 Stripe 同步。
参数
clubID `string` （可选）端点
PUT /api/clubs/{clubID}/saas-billing/payment-settings/payment-methods请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/payment-settings/payment-methods \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施的支出预算以及计算得出的月初至今支出/预测。
参数
clubID `string` （可选）端点
GET /api/clubs/{clubID}/saas-billing/budget请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/budget \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建/更新/清除设施支出预算。
参数
clubID `string` （可选） body `object` （可选）端点
PUT /api/clubs/{clubID}/saas-billing/budget请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/budget \
-H "x-api-key: YOUR_API_KEY"
从设施的付款设置中删除付款方式。
参数
clubID `string` （可选） paymentMethodID `string` （可选）端点
DELETE /api/clubs/{clubID}/saas-billing/payment-settings/payment-methods/{paymentMethodID}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/payment-settings/payment-methods/{paymentMethodID} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取设施的付款设置。
参数
clubID `string` （可选）端点
GET /api/clubs/{clubID}/saas-billing/payment-settings请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/payment-settings \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新设施的付款设置。
参数
clubID `string` （可选） lockedOut `boolean` （可选） 是否将设施锁定在系统之外。 pauseBilling `boolean` （可选） 是否暂停设施的自动计费。 customerID `string` （可选） 添加此项将更新设施的 Stripe 客户 ID。 deleteSourceID `string` （可选） 是否从 Stripe 中删除源客户。端点
PUT /api/clubs/{clubID}/saas-billing/payment-settings请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/payment-settings \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取所有设施最早的计费月份。
参数
clubID `string` （可选）端点
GET /api/saas-billing/payment-settings/earliest-billed-month请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/payment-settings/earliest-billed-month \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出可以解除设施计费锁定的账户，按优先级分层：首先是持有计费模块的用户，只有在没有这样的用户时才回退到组织管理员。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/saas-billing/lockout-contacts请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/lockout-contacts \
-H "x-api-key: YOUR_API_KEY"
响应
{}
对系统中的所有设施进行分页，并返回每个设施的客户 ID。
参数
clubID `string` （可选） organisationId `string` （可选） 组织 ID端点
GET /api/saas-billing/payment-settings/customer-ids请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/payment-settings/customer-ids \
-H "x-api-key: YOUR_API_KEY"
响应
{}
设置设施的主要付款方式。
参数
clubID `string` （可选）端点
PUT /api/clubs/{clubID}/saas-billing/payment-settings/payment-methods/{paymentMethodID}/primary请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/payment-settings/payment-methods/{paymentMethodID}/primary \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新设施的计费资料。
参数
clubID `string` （可选） invoiceEntity `string` （可选） billingContacts `string` （可选） KYC 联系人的 UUID 列表 ccEmails `string` （可选） 发票抄送的电子邮件列表端点
PUT /api/clubs/{clubID}/saas-billing/payment-settings/billing-profile请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/payment-settings/billing-profile \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新设施的付款方式。
参数
clubID `string` （可选） cardID `string` （可选）端点
PUT /api/clubs/{clubID}/saas-billing/payment-settings/payment-methods/{cardID}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/payment-settings/payment-methods/{cardID} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回按设施细分的所有适用产品费用和附加项目，用于 CSV 导出。为用户有权访问的每个设施解析全局/区域/设施覆盖层级。
参数
organisationId `string` （必填） 用于 ACL 的组织 ID端点
GET /api/saas-billing/charges-config/export请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/charges-config/export \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回特定目标的费用配置
参数
clubId `string` （可选） 要获取费用配置的设施的 ID端点
GET /api/saas-billing/charges-config/{clubId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/saas-billing/charges-config/{clubId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
此设施所属组织的计费摘要：生效的付款方范围、任何已计划的合并计费变更，以及调用者是否可以管理合并计费开关。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/saas-billing/org/summary请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/org/summary \
-H "x-api-key: YOUR_API_KEY"
响应
{}
组织的合并月度记录（对账单）及按设施细分的明细，最新的在前。在组织的第一个合并计费月份结算之前为空。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/saas-billing/org/monthly-records请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/org/monthly-records \
-H "x-api-key: YOUR_API_KEY"
响应
{}
预付钱包摘要：余额、月初至今的使用扣款、自动充值配置、计费方式。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/saas-billing/wallet请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/wallet \
-H "x-api-key: YOUR_API_KEY"
响应
{}
钱包账簿，最新的在前。组织级钱包包含所有设施的记录（每条记录都带有其来源 clubID）。
参数
clubID `string` （必填） limit `string` （可选） types `string` （可选） 以逗号分隔的交易类型 from `string` （可选） to `string` （可选） cursor `string` （可选） 上一页返回的 nextCursor端点
GET /api/clubs/{clubID}/saas-billing/wallet/transactions请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/wallet/transactions \
-H "x-api-key: YOUR_API_KEY"
响应
{}
单笔钱包交易（充值和赠送额度）的品牌化 PDF 收据。
参数
clubID `string` （必填） txId `string` （必填）端点
GET /api/clubs/{clubID}/saas-billing/wallet/transactions/{txId}/receipt.pdf请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/wallet/transactions/{txId}/receipt.pdf \
-H "x-api-key: YOUR_API_KEY"
响应
{}
所选钱包充值交易的品牌化 PDF 收据合集（ZIP 格式）。每个 ID 都必须是属于此设施钱包的充值（银行卡或发票），使用扣款和调整没有收据，会被拒绝。
参数
clubID `string` （必填） ids `string` （必填） 以逗号分隔的交易 ID（最多 50 个）端点
GET /api/clubs/{clubID}/saas-billing/wallet/transactions/receipts.zip请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/wallet/transactions/receipts.zip \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从已存储的 SaaS 计费银行卡扣款以增加预付余额。需要 3DS 验证时返回 requires_action + clientSecret。
参数
clubID `string` （必填） body `object` （可选）端点
POST /api/clubs/{clubID}/saas-billing/wallet/topup请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/wallet/topup \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在小程序完成 3DS 认证后完成钱包充值。具有幂等性。
参数
clubID `string` （必填）端点
POST /api/clubs/{clubID}/saas-billing/wallet/topup/confirm请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/wallet/topup/confirm \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新设施的自动充值规则（存储在其计费资料覆盖行中）。
参数
clubID `string` （必填） body `object` （可选）端点
PATCH /api/clubs/{clubID}/saas-billing/wallet/auto-topup请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/wallet/auto-topup \
-H "x-api-key: YOUR_API_KEY"
响应
{}
此设施钱包的充值发票（发票付款方式），最新的在前。
参数
clubID `string` （必填）端点
GET /api/clubs/{clubID}/saas-billing/wallet/invoices请求示例
curl -X GET https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/wallet/invoices \
-H "x-api-key: YOUR_API_KEY"
响应
{}
申请凭参考号付款的充值发票（仅限发票付款方式）。每个钱包最多只能有一张待处理发票，再次请求会返回现有发票，并带有 alreadyPending=true。
参数
clubID `string` （必填） body `string` （可选） { amountCents: number }端点
POST /api/clubs/{clubID}/saas-billing/wallet/topup-invoice请求示例
curl -X POST https://portal.hub.gymsystems.co/api/clubs/{clubID}/saas-billing/wallet/topup-invoice \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施的订单列表。
参数
facilityID `string` （可选）端点
GET /api/store/facilities/:facilityID/orders请求示例
curl -X GET https://portal.hub.gymsystems.co/api/store/facilities/:facilityID/orders \
-H "x-api-key: YOUR_API_KEY"
响应
{}
返回设施可用的产品列表。
参数
clubID `string` （必填） search `string` （可选） limit `string` （可选） page `string` （可选） 用于分页的页码（从 1 开始）。端点
GET /api/store/clubs/{clubID}/products请求示例
curl -X GET https://portal.hub.gymsystems.co/api/store/clubs/{clubID}/products \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设施的 Stripe 记录。
参数
club `string` （必填） fromDate `string` （可选） Unix 时间戳 toDate `string` （可选） Unix 时间戳 socketID `string` （必填） 套接字请求的唯一标识符端点
GET /api/club/{club}/stripe/records请求示例
curl -X GET https://portal.hub.gymsystems.co/api/club/{club}/stripe/records \
-H "x-api-key: YOUR_API_KEY"
响应
{}
取消付款意向
参数
club `string` （必填） paymentIntent `string` （可选）端点
GET /api/club/{club}/stripe/payment-intent/:paymentIntent/cancel请求示例
curl -X GET https://portal.hub.gymsystems.co/api/club/{club}/stripe/payment-intent/:paymentIntent/cancel \
-H "x-api-key: YOUR_API_KEY"
响应
{}
为嵌入式组件创建 Stripe Account Session
为关联账户创建 Stripe Account Session。返回一个 client_secret，用于初始化 Connect 嵌入式组件（争议、付款、账户管理、文档）。
请求正文
端点
POST /api/stripe/account-session请求示例
curl -X POST https://portal.hub.gymsystems.co/api/stripe/account-session \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
为关联账户生成 Stripe KYC 页面的一次性链接。
参数
club `string` （必填）端点
GET /api/club/{club}/stripe/generate-kyc-token请求示例
curl -X GET https://portal.hub.gymsystems.co/api/club/{club}/stripe/generate-kyc-token \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在 KYC 流程中获取 Stripe 关联账户的账户详细信息。
参数
club `string` （必填）端点
GET /api/club/{club}/stripe/connect-account-details请求示例
curl -X GET https://portal.hub.gymsystems.co/api/club/{club}/stripe/connect-account-details \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据设施 ID 返回所有工单历史
参数
club `string` （必填） 要访问的俱乐部的内部 ID。端点
GET /api/ticketing/clubtickets/{club}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ticketing/clubtickets/{club} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取部门
端点
GET /api/ticketing/departments请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ticketing/departments \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取单个工单的详细信息
参数
user `string` （必填） 用户的电子邮件。 ticketNumber `string` （必填） 要访问的工单的 6 位 ID。 club `string` （必填） 所选设施的 ID。端点
GET /api/ticketing/ticket-details/:ticketNumber/:club请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ticketing/ticket-details/:ticketNumber/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取主题
端点
GET /api/ticketing/topics请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ticketing/topics \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取当前登录用户创建的所有工单。注意：该用户由我们的 Google SSO 服务提供的标头确定。
参数
user `string` （必填） 当前登录用户的电子邮件端点
GET /api/ticketing/usertickets请求示例
curl -X GET https://portal.hub.gymsystems.co/api/ticketing/usertickets \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建新工单
参数
club `string` （必填） 所选设施的 ID。端点
POST /api/ticketing/clubticket/:club请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ticketing/clubticket/:club \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建新工单
参数
subject `string` （必填） 工单主题。 message `string` （必填） 工单的完整消息。端点
POST /api/ticketing/userticket请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ticketing/userticket \
-H "x-api-key: YOUR_API_KEY"
响应
{}
回复现有工单
参数
subject `string` （必填） 工单主题。 message `string` （必填） 工单的完整消息。端点
POST /api/ticketing/user-reply请求示例
curl -X POST https://portal.hub.gymsystems.co/api/ticketing/user-reply \
-H "x-api-key: YOUR_API_KEY"
响应
{}
检索用户偏好
端点
GET /api/user-preferences请求示例
curl -X GET https://portal.hub.gymsystems.co/api/user-preferences \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新用户偏好
参数
body `string` （必填）端点
PUT /api/user-preferences请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/user-preferences \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更改用户密码
更改用户密码。如果用户有电话号码，则需要 OTP 验证；如果没有电话号码，则需要先添加电话号码。
请求正文
端点
POST /api/user/change-password请求示例
curl -X POST https://portal.hub.gymsystems.co/api/user/change-password \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
检查用户的双重验证状态
返回用户是否已启用双重验证，以及其任何角色是否强制要求双重验证
端点
GET /api/user/check-2fa-status请求示例
curl -X GET https://portal.hub.gymsystems.co/api/user/check-2fa-status \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出用户在特定模块中有权访问的组织、设施和区域。
参数
moduleId `string` （必填）端点
POST /api/user/me/modules/{moduleId}/org-access请求示例
curl -X POST https://portal.hub.gymsystems.co/api/user/me/modules/{moduleId}/org-access \
-H "x-api-key: YOUR_API_KEY"
响应
{}
由最终用户创建“关联请求”，申请“加入”某个设施。
参数
body `string` （必填） 要添加到系统中的新俱乐部的 JSON 对象。端点
POST /api/user/linkclub请求示例
curl -X POST https://portal.hub.gymsystems.co/api/user/linkclub \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出用户获得授权的所有设施。
端点
GET /api/user/listauthorised请求示例
curl -X GET https://portal.hub.gymsystems.co/api/user/listauthorised \
-H "x-api-key: YOUR_API_KEY"
响应
{}
发送双渠道 OTP（电子邮件 + 短信）
同时向用户的电子邮件地址和指定的电话号码发送 OTP 验证码。 用于首次验证电话号码等高安全性操作。 此端点只发送 OTP，不会修改任何用户数据。
请求正文
端点
POST /api/user/send-dual-otp请求示例
curl -X POST https://portal.hub.gymsystems.co/api/user/send-dual-otp \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
向电话号码或电子邮件发送 OTP
向用户的电话号码（短信）或电子邮件地址发送 OTP 验证码以进行验证
请求正文
端点
POST /api/user/send-otp请求示例
curl -X POST https://portal.hub.gymsystems.co/api/user/send-otp \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
检查用户是否拥有有效的敏感页面访问权限
返回用户是否拥有经过 OTP 验证的有效会话，可访问敏感页面
端点
GET /api/user/sensitive-page-access请求示例
curl -X GET https://portal.hub.gymsystems.co/api/user/sensitive-page-access \
-H "x-api-key: YOUR_API_KEY"
响应
{}
验证 OTP 并授予敏感页面访问权限
验证 OTP 验证码，如果有效则授予 1 小时的敏感页面访问权限
请求正文
端点
POST /api/user/sensitive-page-access/verify请求示例
curl -X POST https://portal.hub.gymsystems.co/api/user/sensitive-page-access/verify \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
撤销敏感页面访问权限（从敏感页面注销）
撤销用户当前的敏感页面访问会话
端点
POST /api/user/sensitive-page-access/revoke请求示例
curl -X POST https://portal.hub.gymsystems.co/api/user/sensitive-page-access/revoke \
-H "x-api-key: YOUR_API_KEY"
响应
{}
启用或禁用双重验证
为用户启用或禁用双重验证。需要电话号码和 OTP 验证。
请求正文
端点
POST /api/user/toggle-2fa请求示例
curl -X POST https://portal.hub.gymsystems.co/api/user/toggle-2fa \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
更新用户自己的个人资料
允许用户更新自己的个人资料信息（名字、姓氏、电话号码）。 首次添加电话号码时，需要进行双渠道 OTP 验证（电子邮件和短信验证码）。更改现有电话号码时，只需要电子邮件 OTP。
请求正文
端点
PATCH /api/user/update-profile请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/user/update-profile \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
根据 URL 检索图标。
端点
GET /api/website-icon请求示例
curl -X GET https://portal.hub.gymsystems.co/api/website-icon \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出密码保险库条目模板
参数
organisationId `string` （可选） 用于模块访问检查的组织上下文端点
GET /api/vault/templates请求示例
curl -X GET https://portal.hub.gymsystems.co/api/vault/templates \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出可见的密码保险库条目
参数
organisationId `string` （必填） scope `string` （可选）端点
GET /api/vault/entries请求示例
curl -X GET https://portal.hub.gymsystems.co/api/vault/entries \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建密码保险库条目
端点
POST /api/vault/entries请求示例
curl -X POST https://portal.hub.gymsystems.co/api/vault/entries \
-H "x-api-key: YOUR_API_KEY"
获取密码保险库条目（不显示密钥值）
参数
entryId `string` （必填） organisationId `string` （必填）端点
GET /api/vault/entries/{entryId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/vault/entries/{entryId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
更新密码保险库条目
端点
PUT /api/vault/entries/{entryId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/vault/entries/{entryId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除密码保险库条目
端点
DELETE /api/vault/entries/{entryId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/vault/entries/{entryId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
显示所选的隐藏字段或密钥字段
端点
POST /api/vault/entries/{entryId}/reveal请求示例
curl -X POST https://portal.hub.gymsystems.co/api/vault/entries/{entryId}/reveal \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出密码保险库文件夹摘要
端点
GET /api/vault/folders请求示例
curl -X GET https://portal.hub.gymsystems.co/api/vault/folders \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出带有身份验证器代码的条目
端点
GET /api/vault/authenticator请求示例
curl -X GET https://portal.hub.gymsystems.co/api/vault/authenticator \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出已注册的工作流节点类型
端点
GET /api/workflow-engine/node-types请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/node-types \
-H "x-api-key: YOUR_API_KEY"
响应
{}
获取工作流块使用的设施开放时间投影
参数
facilityId `string` （必填）端点
GET /api/workflow-engine/facility-hours/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/facility-hours/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
预览带有设施品牌的工作流电子邮件发件人
参数
facilityId `string` （必填）端点
GET /api/workflow-engine/email-branding/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/email-branding/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出用于触发器配置的设施资源
参数
facilityId `string` （必填） resourceType `string` （必填）端点
GET /api/workflow-engine/resources/{facilityId}/{resourceType}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/resources/{facilityId}/{resourceType} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出设施的工作流
参数
facilityId `string` （必填）端点
GET /api/workflow-engine/workflows/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
从非空图创建草稿工作流
编辑器会将新工作流保存在本地，直到它至少包含一个块，因此首次保存会在一次调用中连同其图一起创建工作流。没有 `nodes` 的请求正文会被拒绝，而不会被存储。
参数
facilityId `string` （必填）请求正文
端点
POST /api/workflow-engine/workflows/{facilityId}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
列出设施的工作流可以使用的凭据
返回设施自身的凭据以及在其品牌或组织级别共享的凭据。从不返回密钥；`hasValue` 仅表示已存储密钥。
参数
facilityId `string` （必填）端点
GET /api/workflow-engine/credentials/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/credentials/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建工作流凭据
范围级别来自 `scopeType`；品牌和组织 ID 根据设施解析，而不接受调用者提供的值。
参数
facilityId `string` （必填）请求正文
端点
POST /api/workflow-engine/credentials/{facilityId}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/credentials/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
设施级工作流设置（失败通知收件人）
参数
facilityId `string` （必填）端点
GET /api/workflow-engine/facility-settings/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/facility-settings/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
保存设施级失败通知收件人
参数
facilityId `string` （必填）请求正文
端点
PUT /api/workflow-engine/facility-settings/{facilityId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/workflow-engine/facility-settings/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
替换工作流凭据
`secret` 为空时保留已存储的密钥，因此无需重新输入即可重命名凭据。无法读回密钥。
参数
facilityId `string` （必填） credentialId `string` （必填）端点
PUT /api/workflow-engine/credentials/{facilityId}/{credentialId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/workflow-engine/credentials/{facilityId}/{credentialId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
删除工作流凭据
引用该凭据的节点会在下一次调用时以失败关闭方式处理，包括已发布的工作流，因为快照只存储引用。
参数
facilityId `string` （必填） credentialId `string` （必填）端点
DELETE /api/workflow-engine/credentials/{facilityId}/{credentialId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/workflow-engine/credentials/{facilityId}/{credentialId} \
-H "x-api-key: YOUR_API_KEY"
获取工作流触发器的 Webhook URL
参数
facilityId `string` （必填） workflowId `string` （必填） nodeId `string` （必填）端点
GET /api/workflow-engine/workflows/{facilityId}/{workflowId}/nodes/{nodeId}/webhook请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/nodes/{nodeId}/webhook \
-H "x-api-key: YOUR_API_KEY"
响应
{}
轮换工作流触发器的 Webhook URL
立即使之前的 URL 失效。
参数
facilityId `string` （必填） workflowId `string` （必填） nodeId `string` （必填）端点
POST /api/workflow-engine/workflows/{facilityId}/{workflowId}/nodes/{nodeId}/webhook/rotate请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/nodes/{nodeId}/webhook/rotate \
-H "x-api-key: YOUR_API_KEY"
响应
{}
按 ID 获取工作流
参数
facilityId `string` （必填） workflowId `string` （必填）端点
GET /api/workflow-engine/workflows/{facilityId}/{workflowId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建或更新草稿工作流
参数
facilityId `string` （必填） workflowId `string` （必填）请求正文
端点
PUT /api/workflow-engine/workflows/{facilityId}/{workflowId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
更新工作流名称和/或描述
参数
facilityId `string` （必填） workflowId `string` （必填）请求正文
端点
PATCH /api/workflow-engine/workflows/{facilityId}/{workflowId}请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
删除工作流及其版本
参数
facilityId `string` （必填） workflowId `string` （必填）端点
DELETE /api/workflow-engine/workflows/{facilityId}/{workflowId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将工作流复制为新的未启用草稿
参数
facilityId `string` （必填） workflowId `string` （必填）端点
POST /api/workflow-engine/workflows/{facilityId}/{workflowId}/duplicate请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/duplicate \
-H "x-api-key: YOUR_API_KEY"
响应
{}
发布当前草稿（不可变的版本快照）
参数
facilityId `string` （必填） workflowId `string` （必填）请求正文
端点
POST /api/workflow-engine/workflows/{facilityId}/{workflowId}/publish请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/publish \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
将草稿重置为上次发布的版本
参数
facilityId `string` （必填） workflowId `string` （必填）端点
POST /api/workflow-engine/workflows/{facilityId}/{workflowId}/discard请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/discard \
-H "x-api-key: YOUR_API_KEY"
响应
{}
启用或禁用工作流
参数
facilityId `string` （必填） workflowId `string` （必填）请求正文
端点
PATCH /api/workflow-engine/workflows/{facilityId}/{workflowId}/active请求示例
curl -X PATCH https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/active \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
使用 AI 生成或修改工作流图
参数
facilityId `string` （必填）请求正文
端点
POST /api/workflow-engine/generate/{facilityId}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/generate/{facilityId} \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
列出此设施中 Agent 节点可运行的模型
参数
facilityId `string` （必填）端点
GET /api/workflow-engine/agent-models/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/agent-models/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出此设施中 Agent 节点可附加的 MCP 工具
参数
facilityId `string` （必填）端点
GET /api/workflow-engine/agent-tools/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/agent-tools/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
搜索此设施已保存的 Agent 对话（Conversation key 绑定）
参数
facilityId `string` （必填） deviceId `string` （可选） 仅限某个 Agent 设备的对话（节点配置的 deviceId） q `string` （可选） 对 Conversation key、会话 ID 或设备名称进行不区分大小写的子字符串匹配 limit `integer` （可选） offset `integer` （可选）端点
GET /api/workflow-engine/agent-conversations/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/agent-conversations/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
搜索设施 Agent 设备本身保存的对话
列出设备自身的会话（Agent 界面侧边栏中的对话），以便工作流可以沿用上下文继续现有对话。历史记录归设备所有；当设施有多台设备时，`deviceId` 用于选择其中一台（节点配置的设备）。设备无法访问 → 502。
参数
facilityId `string` （必填） deviceId `string` （可选） 节点配置的 Agent 设备；省略则解析为设施的唯一设备 q `string` （可选） 对会话标题或 ID 进行不区分大小写的子字符串匹配 limit `integer` （可选） offset `integer` （可选）端点
GET /api/workflow-engine/agent-device-sessions/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/agent-device-sessions/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
搜索设施 Agent 设备看板上的看板
为 Agent: Kanban 块的 Board ID 选择器提供数据。对看板名称或 slug 进行不区分大小写的子字符串匹配；`current` 是设备当前活动看板的 slug，以便任务选择器默认使用该范围。当设施有多台设备时，`deviceId` 用于选择其中一台。设备无法访问 → 502。
参数
facilityId `string` （必填） deviceId `string` （可选） 节点配置的 Agent 设备；省略则解析为设施的唯一设备 q `string` （可选） 对看板名称或 slug 进行不区分大小写的子字符串匹配 limit `integer` （可选） offset `integer` （可选）端点
GET /api/workflow-engine/kanban-boards/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/kanban-boards/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
在设施 Agent 设备看板上搜索某个看板的任务
为 Agent: Kanban 块的 Task ID 选择器提供数据。对任务 ID、标题或正文进行不区分大小写的子字符串匹配；任务按看板存储（设备不支持跨看板搜索），因此由 `board` 限定获取范围，省略则使用设备当前活动的看板。设备无法访问 → 502。
参数
facilityId `string` （必填） deviceId `string` （可选） 节点配置的 Agent 设备；省略则解析为设施的唯一设备 board `string` （可选） 要列出的看板 slug；省略则使用设备当前活动的看板 q `string` （可选） 对任务 ID、标题或正文进行不区分大小写的子字符串匹配 limit `integer` （可选） offset `integer` （可选）端点
GET /api/workflow-engine/kanban-tasks/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/kanban-tasks/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出精选工作流模板（已按此设施筛选）
参数
facilityId `string` （必填）端点
GET /api/workflow-engine/templates/{facilityId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/templates/{facilityId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将模板实例化为当前打开草稿的图片段
参数
facilityId `string` （必填） templateId `string` （必填）端点
POST /api/workflow-engine/templates/{facilityId}/{templateId}请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/templates/{facilityId}/{templateId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
模板管理页面的范围选择器上下文（管理层级）
端点
GET /api/workflow-engine/template-admin/context请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/template-admin/context \
-H "x-api-key: YOUR_API_KEY"
响应
{}
列出调用者可以管理的模板及权限标志
端点
GET /api/workflow-engine/template-admin请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/template-admin \
-H "x-api-key: YOUR_API_KEY"
响应
{}
创建模板（管理层级）
请求正文
端点
POST /api/workflow-engine/template-admin请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/template-admin \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
模板详细信息（包括图），供管理编辑器使用
端点
GET /api/workflow-engine/template-admin/{templateId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/template-admin/{templateId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
替换模板（所属组织）
端点
PUT /api/workflow-engine/template-admin/{templateId}请求示例
curl -X PUT https://portal.hub.gymsystems.co/api/workflow-engine/template-admin/{templateId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
软删除模板（所属组织）
端点
DELETE /api/workflow-engine/template-admin/{templateId}请求示例
curl -X DELETE https://portal.hub.gymsystems.co/api/workflow-engine/template-admin/{templateId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
将可见模板复制到调用者可以使用的目标范围
请求正文
端点
POST /api/workflow-engine/template-admin/{templateId}/duplicate请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/template-admin/{templateId}/duplicate \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
通过手动触发器运行工作流的已发布图
参数
facilityId `string` （必填） workflowId `string` （必填）请求正文
端点
POST /api/workflow-engine/workflows/{facilityId}/{workflowId}/run请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/run \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
测试已保存的草稿而不发布
执行当前草稿图，并以 `mode: test` 且不带 `versionId` 的方式记录结果。不会触及发布状态、实时标志和 `publishedVersionId`。副作用默认是模拟的；`sideEffects: live` 还需要 `confirmLiveSideEffects: true`。
参数
facilityId `string` （必填） workflowId `string` （必填）请求正文
端点
POST /api/workflow-engine/workflows/{facilityId}/{workflowId}/test请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/test \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
测试一个列入允许列表的工作流节点
执行已保存草稿中一个可独立测试的节点。变量值可以从已记录的运行步骤中提供。会修改数据的 HTTP 方法需要明确确认。
参数
facilityId `string` （必填） workflowId `string` （必填）请求正文
端点
POST /api/workflow-engine/workflows/{facilityId}/{workflowId}/test-node请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/test-node \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
列出工作流的最近运行
参数
facilityId `string` （必填） workflowId `string` （必填）端点
GET /api/workflow-engine/workflows/{facilityId}/{workflowId}/runs请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/runs \
-H "x-api-key: YOUR_API_KEY"
响应
{}
读取一次运行（状态 + 有序步骤）
参数
facilityId `string` （必填） workflowId `string` （必填） executionId `string` （必填）端点
GET /api/workflow-engine/workflows/{facilityId}/{workflowId}/runs/{executionId}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/runs/{executionId} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
取消等待中的运行当前所处的待执行 Delay
参数
facilityId `string` （必填） workflowId `string` （必填） executionId `string` （必填）端点
POST /api/workflow-engine/workflows/{facilityId}/{workflowId}/runs/{executionId}/cancel请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/runs/{executionId}/cancel \
-H "x-api-key: YOUR_API_KEY"
响应
{}
根据已记录的触发器负载重放已完成的运行
`mode: published` 会以真实副作用重新执行原始运行所固定的确切版本。`mode: draft-test` 会将当前草稿作为模拟测试重新执行。写入时触发器负载被截断的运行无法重放。
参数
facilityId `string` （必填） workflowId `string` （必填） executionId `string` （必填）请求正文
端点
POST /api/workflow-engine/workflows/{facilityId}/{workflowId}/runs/{executionId}/retry请求示例
curl -X POST https://portal.hub.gymsystems.co/api/workflow-engine/workflows/{facilityId}/{workflowId}/runs/{executionId}/retry \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
响应
{}
按索引查找包含某节点类型的工作流
参数
nodeType `string` （必填） facilityId `string` （可选） organisationId `string` （可选）端点
GET /api/workflow-engine/master-view/{nodeType}请求示例
curl -X GET https://portal.hub.gymsystems.co/api/workflow-engine/master-view/{nodeType} \
-H "x-api-key: YOUR_API_KEY"
响应
{}
白标 OAuth 重定向代理（Connected Apps）
公开的、无需认证的 302 重定向，将 OAuth 提供商回调转发到上游工具平台的认证回调，并保留查询字符串。这使 PH 拥有的 OAuth 应用可以注册 performancehub.co 重定向 URI，从而使上游供应商的域名永远不会出现在地址栏中（为未来的自定义 OAuth 应用项目所需；在托管认证模式下无影响）。
端点
GET /guest/connected-apps/oauth-callback请求示例
curl -X GET https://portal.hub.gymsystems.co/guest/connected-apps/oauth-callback \
-H "x-api-key: YOUR_API_KEY"
连接链完成页面（Connected Apps）
运行连接链的 OAuth 标签页所使用的轻量级“您可以关闭此窗口”着陆页。通过同源的 window.opener.postMessage 将结果（已连接的套件/工具包 + 新账户 ID，或失败的工具包）发回应用市场标签页；当与打开者的关联已断开时，回退到 ph-ai-agent 小程序的深层链接，以重现应用内着陆页。仅用于提供信息，不持有任何密钥，也不执行任何写入。
参数
connected `string` （可选） 已完成连接的套件 ID 或工具包 slug（成功情况）。 accounts `string` （可选） 连接链创建的已连接账户 ID，以逗号分隔。 connectError `string` （可选） 步骤失败的工具包 slug（失败情况）。端点
GET /guest/connected-apps/finish请求示例
curl -X GET https://portal.hub.gymsystems.co/guest/connected-apps/finish \
-H "x-api-key: YOUR_API_KEY"
响应
{}
套件连接链回调（Connected Apps）
一键套件连接流程中的 OAuth 回调中转。已签名的 state JWT（HS256，TTL 30 分钟）编码了 { clubID, deviceId, suite, toolkits, step, caids }：账户连接到该代理设备，caids 会累积每一跳创建的账户 ID（最终的小程序重定向会携带这些 ID，以便应用市场提示为新账户添加标签）。将该步骤的工具包标记为已连接，然后以 302 跳转到下一个工具包的 Connect Link；当套件完成时，则跳转到 ph-ai-agent 小程序页面（深层链接到该代理）。单个工具包的连接也通过同一处理程序运行，视为只含一个工具包的套件。
参数
state `string` （必填） 已签名的连接链 state JWT。端点
GET /guest/connected-apps/connect-next请求示例
curl -X GET https://portal.hub.gymsystems.co/guest/connected-apps/connect-next \
-H "x-api-key: YOUR_API_KEY"
触发密码设置电子邮件
验证欢迎电子邮件中的签名链接，触发密码重置电子邮件，并显示确认页面。无需认证。
参数
email `string` （必填） 用户电子邮件地址 sig `string` （必填） 电子邮件的 HMAC 签名端点
GET /guest/setup-password请求示例
curl -X GET https://portal.hub.gymsystems.co/guest/setup-password \
-H "x-api-key: YOUR_API_KEY"
响应
{}