Analytics REST API

为调用者在某个工作区中创建 API 令牌，并仅在 token 字段中返回一次密钥。请立即复制，它无法再次读取，丢失的令牌必须撤销后重新创建。令牌只能缩小其成员的权限范围。省略 permissions 时默认为该成员自己的全部权限（显式传入空列表会被拒绝，请求您没有的权限会报错）。site_ids 接受公开站点 ID（pa_...），并将令牌限制在这些站点，为空时令牌可用于其成员能访问的所有站点（或沿用发起此调用的令牌的站点列表）。expires_at 为可选的 ISO 8601 时间，必须晚于当前时间且最长不超过 3 年，省略则令牌永不过期。allowed_ips 将令牌限制在这些 IP 或 CIDR 范围内。发起此调用的令牌需要 tokens.manage。要求双重验证的工作区会拒绝为没有自己第二验证因素的成员创建令牌。返回与 api_tokens_list 相同的字段，外加 token。

权限： member · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/api_tokens.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

立即且永久地撤销一个 API 令牌。使用它的请求此后都会失败，已撤销的令牌无法恢复，请改为创建新令牌。令牌记录会以 revoked 状态保留在列表中（使用带 include_revoked 的 api_tokens_list 查看），重复撤销已撤销的令牌不会有任何变化。请从 api_tokens_list 获取 id（uuid）。您可以撤销自己的令牌，撤销他人的令牌需要 tokens.manage，并且需要覆盖该令牌涉及的所有站点。调用此接口的令牌需要 tokens.manage。返回已撤销的令牌，不含其密钥。

权限： member · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/api_tokens/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出工作区的 API 令牌，按时间从新到旧排序并分页。没有 tokens.manage 权限时只能看到自己的令牌，拥有该权限则可看到所有成员的令牌。已撤销和已过期的令牌默认隐藏，除非 include_revoked 为 true。每一项包含 id（uuid，供 api_tokens_delete 使用）、name、token_prefix（开头的几个字符，用于识别令牌）、owner（成员的邮箱）、permissions（如 analytics.read 之类的名称）、site_ids（公开站点 ID pa_...，空数组表示所有者能访问的每个站点）、allowed_ips、oauth_client（令牌通过 OAuth 签发时为所连接应用的名称，否则为 null）、status（active、expired 或 revoked）、expires_at、last_used_at、revoked_at 和 created_at。密钥本身绝不会在此返回，列表中的 token 始终为 null。它只会在 api_tokens_create 时显示一次。

权限： member

curl https://privatusanalytics.com/workspaces/:workspace_id/api_tokens.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回站点的 Domain Rating，这是 0 到 100 的估值，表示指向其域名的链接有多强，另含入站和出站链接数量及其历史。这是 Privatus Analytics 自己的评分，不是 Google 的指标。评级每个版本每月更新一次，因此变化按月显示。months（1 到 120，默认 12）设置包含多少个月度历史点。结果包含 domain、checked_at（站点上次检查的时间，从未检查则为 null）、release（最新数据所在月份，格式 YYYY-MM）、rating、inbound_links、outbound_links（尚未知晓时均为 null）、changes（这三项指标与上一版本的差值，任一未知时为 null）和 history（每月一行，含 month、rating、inbound_links、outbound_links，最早的在前）。新站点可能在几分钟内没有评级。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/domain-rating.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/scim/v2/Users.json \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/scim/v2/Users/:id.json \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/scim/v2/Users.json

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/scim/v2/Users/:id.json

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X PATCH https://privatusanalytics.com/scim/v2/Users/:id.json \
  -H "Content-Type: application/json" -d '{…}'

为工作区开启 SSO。配置的 status 必须已是 tested（这在试用登录成功之后发生，需在应用中的工作区 SSO 设置页发起，需要浏览器登录，无法在此运行），或已经是 active。仅限 Business 套餐。激活之后成员可以用 SSO 登录，而通过 sso_update 设置 enforced 则要求每次登录都使用 SSO。如果配置未经测试或套餐不含 SSO，则会失败。需要 workspace.manage。返回 status 为 active 的配置（见 sso_get）。

权限： workspace.manage · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/activate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

通过将配置恢复为 draft 并清除 enforced 来关闭 SSO，使成员回到工作区的其他登录方式。身份提供商的详细信息会保留。重新激活需要新的试用登录和 sso_activate。请先确保成员有其他登录方式。这在任何套餐上都可使用。需要 workspace.manage。返回 status 为 draft 的配置（见 sso_get）。

权限： workspace.manage · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/deactivate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

权限： workspace.manage · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/scim_token.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回工作区的单点登录（SSO）配置，不存在时返回空的草稿。字段包括 protocol（saml 或 oidc）、status（draft、testing、tested 或 active）、enforced（成员必须通过 SSO 登录）、domains（使用此 SSO 的邮箱域名）、SAML 的 idp_sso_url 和 idp_entity_id、OIDC 的 oidc_issuer 和 oidc_client_id、default_role 和 jit_provisioning（首次 SSO 登录时创建成员）以及 scim_enabled。密钥绝不会返回，只有 idp_cert_present 和 oidc_client_secret_present 这两个布尔值。SSO 是 Business 套餐的功能。需要 workspace.manage。

权限： workspace.manage

curl https://privatusanalytics.com/workspaces/:workspace_id/sso.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

创建或编辑工作区的 SSO 设置。仅限 Business 套餐。只有您发送的输入会被更改。对于 SAML，请发送 protocol 为 saml 以及 idp_sso_url、idp_entity_id 和 idp_cert（PEM 文本）。对于 OIDC，请发送 protocol 为 oidc 以及 oidc_issuer、oidc_client_id 和 oidc_client_secret，其中最后一项只写，空值会保留现有密钥。domains 列出使用此 SSO 的邮箱域名。default_role 是授予首次登录配置或 SCIM 所创建成员的角色（不能是 owner 或 custom），且您只能设置自己有权授予的角色。更改任何身份提供商详细信息都会将 active 或 tested 的配置退回 draft 并关闭 enforced，因此必须重新测试，sso_activate 才能生效。enforced 为 true 仅在 status 为 active 时被接受。需要 workspace.manage。返回配置（见 sso_get）。

权限： workspace.manage · 仅限 HTTP（不是 MCP 工具）

curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/sso.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出发送到某个 Webhook 的推送记录（路径接受 webhook_id），按时间从新到旧排序并分页。每条记录包含 id（whd_...）、event、status（pending、对任何 2xx 响应为 succeeded，或 failed）、status_code（没有响应时为 null）、error（如超时之类的简短原因，否则为 null）、attempt（目前已尝试的次数）、duration_ms、payload（发送的 JSON 数据）、response_body（响应的前 2000 个字符）以及 delivered_at 和 created_at。可用 status 为 succeeded 或 failed 筛选。用它调试端点，用 webhook_deliveries_redeliver 重新发送。

权限： workspace.manage

curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:webhook_id/deliveries.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

将过去一次推送的载荷作为新的推送再次发送到同一端点（id 为 whd_...，来自 webhook_deliveries_list）。这会向客户的 URL 发起 HTTP 请求，因此接收方可能会处理同一事件两次。它按工作区进行频率限制（与 webhooks_test 共用）。它会被加入队列，因此响应是一条状态为 pending 的新推送记录，请读取 webhook_deliveries_list 查看结果。

权限： workspace.manage

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:webhook_id/deliveries/:id/redeliver.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

添加一个接收工作区事件的 POST JSON 端点（路径接受 workspace_id）。url 必须是公开的 https 地址，私有和内部地址会被拒绝。events 是必填列表，从 alert.triggered、alert.resolved、goal.completed_threshold、uptime.down、uptime.up、export.ready、import.completed、import.failed、site.created、site.deleted、member.added、usage.threshold 和 site_audit.completed 中选择。enabled 默认为 true。系统会生成签名密钥（whsec_...）并在响应中返回，每次推送都带有 Privatus-Signature 标头，其中包含时间戳以及用该密钥对正文计算的 HMAC-SHA256。失败的推送会按退避策略重试，连续失败 20 次后该端点会被禁用。使用 webhooks_test 发送示例。

权限： workspace.manage

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/webhooks.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

删除一个 Webhook 端点及其整个推送日志。此操作无法撤销，待处理的重试也会停止。若只想暂停，请改用 enabled 为 false 的 webhooks_update。id（wh_...）来自 webhooks_list。返回已删除的 Webhook。

权限： workspace.manage

curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出工作区发出的 Webhook 端点（路径接受 workspace_id），按时间从旧到新排序。每个端点包含 id（wh_...）、url、events（它接收的事件名称）、enabled、status（active、最近有失败时为 failing，或 disabled）、secret（签名密钥，请视为敏感信息）、consecutive_failures、last_success_at、last_failure_at 和 created_at。需要 workspace.manage 权限。这用于将原始事件发送到您自己的服务器。若要通知人员，请使用 notification_channels_list。已发送的内容请使用 webhook_deliveries_list。

权限： workspace.manage

curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

按 id（wh_...，来自 webhooks_list）返回一个 Webhook 端点，包括其签名密钥（whsec_...），用于验证每次推送的 Privatus-Signature 标头。字段包括 url、events、enabled、status（active、failing 或 disabled）、secret、consecutive_failures、last_success_at、last_failure_at 和 created_at。需要 workspace.manage 权限。

权限： workspace.manage

curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

将一条带示例消息的 webhook.test 推送加入队列并发送到某个端点，即使它已被禁用，这会向客户的 URL 发起 HTTP 请求。它按工作区进行频率限制（与 webhook_deliveries_redeliver 共用），测试不会重试。推送在后台发送，因此响应返回状态为 pending 的已排队推送记录。稍后读取 webhook_deliveries_list 即可查看 status_code、error、duration_ms 和 response_body。

权限： workspace.manage

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id/test.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

修改 Webhook（id 来自 webhooks_list）。只有您发送的输入会被更改。发送 events 会替换整个列表。对已禁用的端点将 enabled 设为 true 会重置其失败计数，这是重新启用因多次失败而被禁用的端点的方式。将 rotate_secret 设为 true 会生成新的签名密钥并在响应中显示，旧密钥会立即失效，因此必须更新接收方。url 规则与 webhooks_create 相同。返回该 Webhook。

权限： workspace.manage

curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出自定义事件在过去 30 天内携带的属性键及其显示设置。返回 {key, events, display_name, hidden, export_safe} 的列表。events 是携带该键的自定义事件数量（有设置但最近未出现的键为 0），display_name 是重命名后的名称（没有时为 null），hidden 表示该键在报告中被隐藏，export_safe 表示已标记为不含个人数据。最多返回 200 个键，使用最多的在前。传入 event 可只查看某个原始事件名称上出现过的键。属性值绝不会在此返回，查看值请使用 dimension 为 prop:<key> 的 stats_breakdown 或 events_get。使用 event_properties_update 更改设置。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/events/properties.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

在整个站点范围内重命名、隐藏某个事件属性键，或将其标记为可安全导出。只有您发送的输入会被更改。key 必须是存储的键（小写字母、数字和下划线，最多 64 个字符，例如 plan）。display_name 是最多 64 个字符的标签（发送空值可移除重命名）。hidden 会将该键从报告和事件详情透视表中移除，同时保留数据。export_safe 声明该键绝不包含个人数据，这会将其值包含在原始导出和数据仓库同步中，因此仅在确实如此时才设置。重命名和隐藏在读取报告时生效，不会改写任何存储的数据。返回 {key, display_name, hidden, export_safe}。需要 sites.manage 权限。使用 event_properties_list 列出这些键。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:site_id/events/properties.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一个自定义事件及其全部历史。此操作无法撤销。作为安全检查，必须发送两次原始事件名称，分别在 name 和 confirm 中。返回 {name, status: queued} 和 HTTP 202，因为这些行会在后台分批移除，所以在完成之前数字会持续变化。该事件也会立即被隐藏，删除操作会记录在审计日志中。浏览量不受影响。如果您只是想不再显示某个事件，请使用 hidden 为 true 的 events_update，它会保留数据。需要 sites.manage 权限。名称来自 events_list（如果事件被重命名或合并，请使用 raw_names 字段）。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/events.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

事件浏览器：该时间段内的每个自定义事件。返回 period、events 和 hidden。每个事件包含 name（重命名和合并后的显示名称）、raw_names（跟踪器发送的名称）、completions、visits、conversion_rate（占访问的百分比，0 到 100）、revenue（最小货币单位，分）、first_seen 和 last_seen（该时间段内的 ISO 8601 时间戳）以及 currency（收入货币，未设置时为 null）。hidden 以 {name, display_name} 的形式列出您隐藏的事件。使用 search 可只保留名称包含某段文本的事件。这里的浏览量不算事件。深入查看单个事件请使用 events_get，获取排序且分页的列表请使用 dimension 为 event 的 stats_breakdown。接受共享的 period、compare、filters 和 segment 输入。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/events.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

将多个原始事件名称合并为一个显示名称，例如将 signup_click 和 signup_button 合并为 Signup。之后报告会显示一个合并了计数的事件。它在读取报告时生效，存储的事件不会被更改或删除。传入 names（原始名称，至少一个）和 into（显示名称）。为每个被合并的名称返回一个设置对象，格式为 {name, display_name, hidden, currency, updated_at}。若要撤销，请对某个名称调用 events_update 并将 display_name 设为空。需要 sites.manage 权限。名称来自 events_list（raw_names）。

权限： sites.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/events/merge.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

单个自定义事件的详情。传入 name，需与 events_list 中显示的完全一致（重命名和合并后的显示名称）。返回 period、name、raw_names（其背后存储的名称）、interval、totals、setting、series、property_keys、pivot、numeric、pages、channels 和 referrers。totals 包含 completions、visits（触发过它的访问）、revenue（最小货币单位，分）和 conversion_rate（占该时间段所有访问的百分比）。series 是每个时间段的 completions。setting 包含 display_name、hidden 和 currency。property_keys 列出出现过的属性键。发送 properties（最多 3 个键）可获得 pivot，即每种值组合的 {values, completions, visits} 行，取前 100。numeric 给出包含数字的属性的总和、平均值和其他数据。pages、channels 和 referrers 是该事件触发最多的前 10 个位置，格式为 {value, completions, visits}。查看所有事件请使用 events_list，查看某个属性在整个站点的情况请使用 dimension 为 prop:<key> 的 stats_breakdown，重命名请使用 events_update。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/events/detail.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

更改某个自定义事件的显示方式：用 display_name 重命名，用 hidden 隐藏或取消隐藏，或设置收入货币。name 是跟踪器发送的原始事件名称（见 events_list 中的 raw_names）。只有您发送的输入会被更改。display_name 为空会移除重命名。hidden 会将事件从列表和报告中移除，同时保留其数据。currency 是三位 ISO 4217 代码，如 USD，以大写存储。这在读取报告时生效，不会改写任何存储的事件。返回 {name, display_name, hidden, currency, updated_at}。若要合并多个事件请使用 events_merge，若要清除数据请使用 events_delete。需要 sites.manage 权限。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:site_id/events/settings.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回自定义仪表板中某一张卡片的实时数据。仪表板是卡片的列表（卡片列表见 dashboards_get），每张卡片单独加载，因此请对每张卡片调用一次，用 index 传入其位置（从 0 开始计数）。返回 index、type、title、site_id、site_name、params、status 和 data。status 为 ok、not_available（卡片没有可显示的内容，例如没有漏斗的站点上的漏斗卡片，或没有检查的正常运行时间卡片）或 no_access（卡片属于您的令牌或角色无法打开的站点，此时 title、params 和 data 为空）。data 的结构取决于 type。metric 给出 {metric, value, previous, change, period}，与上一周期对比。chart 给出 {metric, interval, period, series: [{date, value}]}。breakdown 给出 {dimension, label, rows}。goal 给出目标完成情况的 {rows}。live 给出 {visitors}。funnel 给出 {funnel_id, name, overall_conversion_rate, steps}。uptime 给出 {checks: [{name, status, uptime}]}。vitals 给出 {scorecard}。subscriptions 给出 {currency, mrr_minor, previous_mrr_minor（30 天前）, change（百分比，30 天前没有 MRR 时为 null）, active_subscriptions, subscription_churn_rate（最近 30 天）}，并且在站点未连接支付服务商时为 not_available。卡片 params 默认为 period 30d、metric visitors、dimension page 和 5 行（limit 上限为 10）。超出列表的 index 会返回 404。请先使用 dashboards_get 查看有多少张卡片。

权限： analytics.read

curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id/cards/:index.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

在工作区中创建自定义仪表板。自定义仪表板是一个有名称、有顺序的列表，最多包含 40 张卡片，这些卡片可以来自工作区的不同站点。传入 name（最多 100 个字符）和 cards，后者是对象列表，每个对象含 type（metric、chart、breakdown、goal、live、funnel、uptime、vitals 或 subscriptions）、site_id（pa_...，来自 sites_list），并可选 title（最多 80 个字符）和 params。各 type 使用的 params 为：metric（period、metric）、chart（period、metric、interval）、breakdown（period、dimension、limit）、goal（period、limit）、funnel（period、funnel_id）、uptime（limit）和 vitals（period）。live 和 subscriptions 不带参数。其他 params 会被丢弃。period 必须是 30d 这样的预设（不能是 custom），metric 必须是 visitors、visits、pageviews、views_per_visit、bounce_rate 或 visit_duration 之一。每张卡片都必须指向您的令牌可访问的站点，仅限部分站点的令牌必须至少包含一张卡片。返回仪表板，含 id（dash_...）、name、cards 和时间戳。用 dashboards_get 读取它，并用 dashboards_card 加载每张卡片的数据。需要 content.write 权限。套餐决定工作区可拥有多少个仪表板：Free 为 1 个，Pro 为 3 个，Business 不限。超出数量会因验证错误而被拒绝。

权限： content.write

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/dashboards.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一个自定义仪表板。只会移除仪表板的布局，不会触及任何分析数据，且无法撤销。您需要有权访问仪表板上每个有卡片的站点，且仪表板至少要有一张您可访问站点的卡片。返回已删除的仪表板。若要修改仪表板请改用 dashboards_update。ID（dash_...）来自 dashboards_list。需要 content.write 权限。

权限： content.write

curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出工作区的自定义仪表板，按名称排序。每一项包含 id（dash_...）、name、cards 和时间戳，结构与 dashboards_get 相同。仅限部分站点的令牌只能看到包含其站点卡片的仪表板，其他站点的卡片会被清空为 {type, status: no_access}。通过 page 和 per_page 分页（最大 100）。使用 dashboards_card 加载卡片的数据，使用 dashboards_create 添加仪表板。对于单个站点，stats_overview 无需仪表板即可给出同类数字。

权限： analytics.read

curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回一个自定义仪表板：id（dash_...）、name、cards 以及 created_at 和 updated_at。每张卡片的格式为 {type, site_id, title, params}（type 为 metric、chart、breakdown、goal、live、funnel、uptime、vitals 或 subscriptions）。您无法访问的站点上的卡片会以 {type, status: no_access} 返回，没有其他字段。这里只返回布局，不含数字。请用 dashboards_card 加载卡片的数字，使用卡片的位置（从 0 开始计数）。ID 来自 dashboards_list。超出套餐数量（Free 为 1 个，Pro 为 3 个）的仪表板会被保留并锁定：在工作区升级或删除另一个仪表板之前，它会返回 402 plan_limit。

权限： analytics.read

curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

重命名自定义仪表板，和/或替换其全部卡片列表。只有您发送的字段会被更改，name 为空时保持不变。发送 cards 会替换每一张卡片，因此请按您想要的顺序发送完整列表，可取自 dashboards_get 并加以编辑。卡片格式和各 type 的 params 与 dashboards_create 相同（最多 40 张卡片）。显示为 {type, status: no_access} 的卡片属于您无法打开的站点。请原样发回以保留它，它不能被编辑，此类站点的最后一张卡片也不能被移除。仅限部分站点的令牌不能让仪表板变空。返回更新后的仪表板。需要 content.write 权限。

权限： content.write

curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/badge/:site_id.json

立即撤销一个共享链接，使其 URL 和嵌入代码对所有人都失效。此操作无法撤销，已撤销的链接无法恢复，请改为创建新链接。该记录会在内部保留，但会从 shared_links_list 中消失。id（shr_...）来自 shared_links_list。返回已撤销的链接。撤销会写入安全日志。

权限： sites.manage

curl -X DELETE https://privatusanalytics.com/sites/:site_id/shared_links/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出某个站点有效的（未撤销的）共享链接（路径接受 site_id），按时间从新到旧排序，为不分页的普通列表。每个链接包含 id（shr_...）、kind（public、password、sso 或 embed）、name、url（要分享的页面）、embed_url（用于 iframe）、sections、locked_filters、locked_period、options（theme 和 allow_filters）、expires_at 和 usable（过期后为 false）。可按 kind 筛选。大屏看板链接是单独的，请使用 wallboard_links_list。需要 sites.manage 权限。

权限： sites.manage

curl https://privatusanalytics.com/sites/:site_id/shared_links.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

共享链接背后某个维度的热门值，是 stats_breakdown 的共享版本。路径接受 token（共享 URL 的最后一部分）和 dimension，后者必须属于该链接共享的某个栏目，例如 sources 共享 channel、referrer 和 referrer_url，pages 共享 page、entry_page、exit_page 和 hostname，campaigns 共享 utm_ 维度，locations 共享 country 和 language，technology 共享 device、browser、os 和 screen，conversions 共享 goal，events 共享 event。链接栏目之外的维度会因验证错误而被拒绝。limit 为 1 到 100 行（默认 10）。行的字段和单位与该维度在 stats_breakdown 中的相同。链接锁定的时间段和筛选条件优先于 period、from、to 和 filters，当链接不允许时，调用者提供的筛选条件会被忽略。密码链接需要 X-Share-Password 标头。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/share/:token/breakdown/:dimension.json

为没有账户的人读取共享链接背后的仪表板。路径中的 token 是共享 URL（/share/<token>）的最后一部分，也是唯一的凭据，密码链接还需要 X-Share-Password 标头，sso 链接需要已登录的成员。当站点开启了公开仪表板时，它也接受站点 ID（pa_...）。返回与 stats_overview 相同的数据，仅限于链接共享的内容。包括 period、metrics（visitors、visits、pageviews、views_per_visit、百分比形式的 bounce_rate、以毫秒表示的 visit_duration、以最小货币单位表示的 revenue）、对应 interval 的图表 series、设置 compare 时的对比数据，以及仅限共享栏目的热门值 panels。它还会加入 site（id、name、domain、timezone）、sections 和 locked_period。只有链接共享 live 时才会出现 live_visitors。链接上锁定的时间段和筛选条件会覆盖 period、from、to 和 filters。需要某个维度的更多行请使用 shares_breakdown。对于您自己的站点，请使用 stats_overview。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/share/:token.json

来自点击跟踪模块的每个元素的点击数。元素用一个简短的 CSS 选择器表示（标签、id 和最多两个类，最多四层），如果站点给它起了名字，则用 [data-privatus-click="name"]。传入 path（以斜杠开头，与存储的值一致）可查看单个页面，此时 elements 为 {selector, clicks, visits, visit_share}，page_visits 是查看过该页面的访问数，visit_share 是其中点击过该元素的百分比（0 到 100）。不传 path 时，elements 为全站的 {path, selector, clicks, visits}。visits 统计至少点击过一次的访问。返回 period、path、page_visits 和 elements，点击最多的在前。绝不会收集元素上的文字、坐标或鼠标移动。页面的其他内容请用 pages_detail。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/clicks.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

一次调用即可返回站点概览页显示的全部内容：回答“站点表现如何”这类宽泛问题时使用它，无需调用多个工具。返回 period、metrics（visitors、visits、pageviews、views_per_visit、bounce_rate、visit_duration、revenue）、interval、series（每个时间段一项）、panels、notes 和 live_visitors。带 compare 时，还会像 stats_aggregate 和 stats_timeseries 一样增加 comparison_period、comparison、change 和 comparison_series。单位与这些工具一致：bounce_rate 是 0 到 100 的百分比，visit_duration 是互动时长的中位数（毫秒），revenue 是以最小货币单位（分）表示的整数。panels 是以维度名称为键的对象，每个包含前 10 行及其占比，行的格式与该维度在 stats_breakdown 中的相同。默认返回 channel、referrer、page、entry_page、country、device、browser、os、utm_campaign、event 和 goal。发送 panels 可选择其他维度（除属性键之外的任何维度名称）。notes 列出该范围内的注释，格式为 {id, date, end_date, title, url, color}。live_visitors 统计最近 5 分钟内的访客。需要某个维度超过 10 行时使用 stats_breakdown，只要一个数字时使用 stats_aggregate。接受共享的 period、compare、filters 和 segment 输入。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/overview.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

使用事件数据报告 A/B 测试。访问会被分配到事件属性中的变体（该访问中最先出现的值，例如属性 variant，值为 control 和 b），转化则是完成了某个目标的访问。必填输入是 property（小写键，最多 64 个字符）和 goal_id（一个启用的目标，来自 goals_list）。返回 period、property、goal {id, name}、control、confidence（0.95）和 variants。每个变体包含 visits、conversions、conversion_rate（百分比，0 到 100）、control（基准为 true）、uplift（转化率相对对照组的变化百分比，对照组或对照组转化率为 0 时为 null）、z、p_value 和 significant（p_value 低于 0.05 时为 true，使用双比例 z 检验）。对照组是您在 control 中传入的变体，否则是名为 control 的变体，再否则是访问最多的变体。最多 20 个变体，访问最多的排在前面。请先确保站点将变体作为事件属性发送。接受共享的 period 和 filters 输入。若只需普通的目标转化率，请使用 goals_get。需要 Business 或 Enterprise 套餐（否则返回 402 plan_limit）。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/experiments/external.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

以通俗的英文语句描述站点的显著变化，与上一个等长周期对比。返回 period、comparison_period 和 insights。周期涵盖截至昨天的整天，通过 period 选择（7d、14d、28d 或 30d，默认 7d）。每条洞察包含 dimension（total、channel、page、country 或 goal）、metric、value、previous、current、change 和 sentence。change 对计数是百分比，对目标转化率是百分点，sentence 是可直接阅读的英文语句。内容包括总访客和浏览量、每个维度变化最大的两项（变化达 20% 或以上且至少有 10 次访问或浏览），以及转化率变化达半个百分点或以上的目标。最重要的排在前面，数量由 limit 限制（默认 8，最大 20）。结果按天缓存。需要精确数字时使用 stats_aggregate 和 stats_breakdown，用本接口来找出发生了什么变化。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/insights.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

探索访问中最常见的三步页面路径。在正向模式（默认）下，显示 path 中给定的起始页面之后的路径，path 为空时显示任意入口之后的路径。在反向模式下，显示通向结束页面（path）或目标（goal_id，会自动切换为反向）的路径。反向模式需要 path 或 goal_id。path 必须以斜杠开头。返回 period、mode、path、goal、sampled、sample_rate（百分比）、total_visits，以及按步骤包含 nodes 和 links 的路径图，每步最多显示 limit 个页面（2 到 12，默认 6）。访问量超过 100,000 时会对数据抽样。页面筛选会被忽略，因为它们会截断路径。路径按每次访问构建，因为不存储访客 ID。接受共享的 period、filters 和 segment 输入。查看某个页面的相邻页面请使用 pages_detail，步骤转化请使用 funnels_get。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/journeys.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

深入查看单个页面。传入 path（必须以斜杠开头，例如 /pricing），需与存储的值完全一致（不含查询字符串和主机）。返回 period、path、url、metrics、previous_pages、next_pages、sources、vitals、events、clicks、goals 和 notes。metrics 包含 visitors、visits、pageviews、entrances、exits、entry_rate、exit_rate 和 bounce_rate（百分比，0 到 100）、time_on_page（中位数，毫秒）和 scroll_depth（中位数百分比），后两项在没有互动数据时为 null。previous_pages 和 next_pages 是同一次访问中之前和之后查看的页面，格式为 {value, count, share}，其中 (entrance) 和 (exit) 是特殊值。sources 包含从此页面进入的访问的主要渠道和来源。vitals 包含各项核心网页指标的 p75 值及评级。events 是在该页面上触发的自定义事件，clicks 是被点击最多的元素选择器，goals 是在该页面上完成的目标，notes 是提到该页面的注释。使用带 dimension 为 page 的 stats_breakdown 对页面排名，使用 referrers_detail 查看某个来源站点。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/pages/detail.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

对带来访客的外部站点排名，并给出各自带来的数据。直接访问（没有来源）不包含在内。返回 period、summary、channels、page、limit、has_more 和 rows。summary 包含 visitors、visits、pageviews、bounce_rate（百分比）、visit_duration（互动时长中位数，毫秒）、revenue（最小货币单位，分）、sites（来源站点数量）和 share（来自外部来源的访问占全部访问的百分比）。channels 以 {value, visitors, visits} 显示各类流量。每行包含 value（来源主机）、visitors、visits、pageviews、bounce_rate、visit_duration、revenue、channel（其常见渠道）、linking_pages（该站点上有多少个不同页面链接到此处）和 share（来自外部来源的访客所占百分比）。使用 sort 排序（visitors、visits、pageviews 或 revenue，默认 visitors），使用 search 缩小范围（主机名包含的文本），并在 has_more 为 true 时用 page 和 limit（最大 100）翻页。查看单个站点请使用 referrers_detail。接受共享的 period、compare、filters 和 segment 输入。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/referrers.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

深入查看单个来源站点。传入 referrer，为不含 www 和路径的主机名（例如 news.ycombinator.com），与 referrers_list 中的值相同。返回 period、referrer、url、channel（其最常见的渠道）、metrics、share（占全部访问的百分比）、interval、series（流量随时间的变化）、linking_pages、landing_pages、channels、countries、devices、campaigns、goals，带 compare 时还有 comparison、change 和 comparison_series。metrics 和 series 使用与 stats_aggregate 和 stats_timeseries 相同的字段和单位。linking_pages 是该来源站点上带来访客的页面，行包含 path、url、visitors 和 share（绝不存储查询字符串）。landing_pages 是这些访客进入的页面。channels、countries、devices 和 campaigns 是带指标的热门值，goals 列出它们完成的目标及 conversions 和 conversion_rate。使用 referrers_list 对来源站点排名，使用带 dimension 为 referrer 的 stats_breakdown 获取简单列表。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/referrers/detail.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

一个时间段的核心数字，作为一个对象返回。返回 period {from, to} 和 metrics {visitors, visits, pageviews, views_per_visit, bounce_rate, visit_duration, revenue}。带 compare 时还会返回 comparison_period、comparison（另一个时间范围的相同指标）和 change（每项指标的变化百分比，之前的值为 0 时为 null）。单位：bounce_rate 是 0 到 100 的百分比（10.9 表示 10.9%）。visit_duration 是一次访问的互动时长中位数，单位为毫秒。revenue 是以站点货币的最小单位（分）表示的整数。views_per_visit 是小数。访客按天统计，因为不存储持久的访客 ID，所以在另一天再次回访的人会被重复计数。用它获取总数和周期对比的变化。随时间变化的图表请使用 stats_timeseries，某个维度的热门值请使用 stats_breakdown，一次获取全部内容请使用 stats_overview。以上任何一个都可以用 filters 缩小范围（维度名称和运算符见 filters）。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/stats/aggregate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

某个维度的热门值及其指标，按重要性排序并分页。维度是路径的最后一部分，必须是其描述中的确切名称（例如 country、page、channel、utm_campaign、prop:plan）。返回 period、dimension、label、page、limit、has_more 和 rows。has_more 为 true 时可请求下一页。每行都有 value 和 share（占该周期总数的百分比）。行中的其他字段取决于维度。访问维度（channel、referrer、referrer_url、utm_*、ref、hostname、country、language、device、browser、browser_version、os、os_version、screen、entry_page、exit_page、interaction、bot_score）给出 visitors、visits、pageviews、views_per_visit、bounce_rate、visit_duration 和 revenue。page 给出 pageviews、visits、time_on_page（毫秒）和 scroll_depth（百分比），不含 visitors。event 和 prop:<key> 给出 completions、visits、revenue 和 conversion_rate。goal 给出 goal_id、completions、conversions、conversion_rate 和 revenue。单位：bounce_rate 和 conversion_rate 是百分比（0 到 100），时长为毫秒，revenue 为最小货币单位（分）。维度错误会返回 422 并列出有效的名称。使用 search 在所有行中查找某个值，并先用 filters 缩小数据范围（例如某个国家或地区访问过的页面）。深入查看单个页面或来源请使用 pages_detail 或 referrers_detail。interaction 和 bot_score 维度需要 Business 或 Enterprise 套餐：作为细分时，在其他套餐上会响应 402 plan_limit，而对其中任一维度的筛选会被忽略。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/breakdown/:dimension.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

按时间段给出的指标，用于图表和趋势。返回 period、interval（实际使用的时间段）和 series，后者是 {date, visitors, visits, pageviews, views_per_visit, bounce_rate, visit_duration, revenue} 的列表，每个时间段一项，date 为该时间段的 ISO 8601 起点。带 compare 时，还会逐个时间段返回另一个时间范围的 comparison_series。单位与 stats_aggregate 相同：bounce_rate 是百分比（0 到 100），visit_duration 是互动时长中位数（毫秒），revenue 为最小货币单位（分）。interval 默认为 auto，它会根据范围选择分钟、小时、天、周或月。设置它可强制指定时间段大小。单个总数请使用 stats_aggregate，按 country 或 page 等维度拆分请使用 stats_breakdown。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/stats/timeseries.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

在某个站点上发起一个新的 Ask 对话，并利用该站点的分析数据回答第一个问题。用它来向站点提出通俗易懂的问题。要继续已有对话请使用 assistant_ask_followup，已经知道确切查询时请使用统计工具。回答由 AI 模型自行运行只读分析查询生成，因此调用可能需要很多秒。它会计为工作区每月额度中的一次 AI 提问（Free 为 5 次，Pro 为 20 次，Business 为 100 次），额度用完后会因额度错误而失败。问题最长 2,000 个字符。对话仅对发起者本人可见，并在最后一条消息 30 天后删除。返回对话（id、site_id、取自问题的 title、created_at、updated_at、expires_at）及 messages 数组。每条消息包含 role（user 或 assistant）、content（回答文本）、queries（助手运行的确切分析查询）、chart（可为空的图表定义）、goal_draft（可为空的建议目标）、令牌计数和 created_at。如果回答失败，对话会被移除，也不会计入提问次数。需要 analytics.read。

权限： analytics.read

curl -X POST https://privatusanalytics.com/sites/:site_id/ask.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

立即永久删除一个 Ask 对话及其所有消息。此操作无法撤销。对话 ID 来自 assistant_conversations_list。只有发起对话的成员才能看到并删除它。需要 analytics.read 和 site_id。返回已删除对话的摘要（id、site_id、title、时间戳）。它不会退还当月已计入的 AI 提问次数。

权限： analytics.read

curl -X DELETE https://privatusanalytics.com/sites/:site_id/ask/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出已登录成员在某个站点上的 Ask 对话，按最近更新时间排序。其他成员的对话绝不会显示。用它查找对话 ID，以供 assistant_conversations_get、assistant_ask_followup 或 assistant_conversations_delete 使用。每一项包含 id、site_id、title（第一个问题，截断为 80 个字符）、created_at、updated_at 和 expires_at，但不含消息。通过 page 和 per_page 分页（最大 100）。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/ask.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回一个 Ask 对话及其完整的消息历史。对话 ID 来自 assistant_conversations_list 或 assistant_ask 的结果。字段包括 id、site_id、title、created_at、updated_at、expires_at（最后一条消息 30 天后，之后对话会被删除）和 messages。每条消息包含 role（user 或 assistant）、content、queries（助手运行的分析查询）、chart（可为空）、goal_draft（可为空）以及 input_tokens 和 output_tokens（可为空的整数）。只有发起对话的成员才能读取。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/ask/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

在已有的 Ask 对话中提出追问，使助手将之前的问答作为上下文。若要开始新对话请改用 assistant_ask。conversation_id 来自 assistant_conversations_list。由于助手要运行只读分析查询，调用可能需要很多秒。每个问题都会计入工作区每月的 AI 提问额度（Free 为 5 次，Pro 为 20 次，Business 为 100 次），用完后会因额度错误而失败。问题最长 2,000 个字符。只返回新的助手消息（不是整个对话），包含 id、role、content（回答）、queries（运行的确切查询）、chart（可为空）、goal_draft（可为空）、input_tokens、output_tokens 和 created_at。需要 analytics.read，且只适用于您自己的对话。

权限： analytics.read

curl -X POST https://privatusanalytics.com/sites/:site_id/ask/:ask_conversation_id/messages.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

在某个站点的图表上添加注释，例如一次发布、一个营销活动或一个版本。若要添加显示在每个站点上的备注，请改用 workspace_notes_create。date 默认为站点时区中的今天，end_date 标记一个范围（YYYY-MM-DD）。title 显示在图表上，body 是纯文本，url 可指向 PR 或更新日志。color 为 neutral、brand、blue、amber、red 或 violet 之一，默认 neutral。source 默认为 manual。部署集成会发送 source 为 deploy，此时 title 默认为由 version（发布版本或提交）生成的文本，color 默认为 blue。需要 content.write。返回已创建的备注（字段见 notes_list）。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/notes.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一条站点备注，它会从图表中消失且无法恢复。该备注必须属于此站点，工作区范围的备注请用 workspace_notes_delete 删除。id（note_...）来自 notes_list。需要 content.write。返回已删除的备注。

权限： content.write

curl -X DELETE https://privatusanalytics.com/sites/:site_id/notes/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出显示在站点图表上的注释（备注），按日期从新到旧排序并分页。它返回站点自己的备注，以及适用于每个站点的工作区范围备注。可用 from 和 to（YYYY-MM-DD，备注日期落在该范围内即匹配）、source（manual、deploy、system、import 或 incident）和 query（对 title、body 和 url 进行不区分大小写的搜索）筛选。查看跨所有站点的工作区视图请使用 workspace_notes_list。每条备注包含 id（note_...）、site_id（公开站点 ID pa_...，工作区范围的备注为 null）、date、end_date（单日为 null）、title、body（可为空的纯文本）、url（可为空）、color（neutral、brand、blue、amber、red 或 violet）、source 和 created_at。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/notes.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

按 id（note_...，来自 notes_list）为某个站点返回一条备注，包括适用于该站点的工作区范围备注。备注是显示在图表上带日期的注释，例如一次发布、一个营销活动或一次部署。字段包括 id、site_id（工作区范围时为 null）、date 和 end_date（YYYY-MM-DD，单日时 end_date 为 null）、title、body（可为空）、url（可为空）、color（neutral、brand、blue、amber、red 或 violet）、source（manual、deploy、system、import 或 incident）和 created_at。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/notes/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

编辑一条站点备注，只更改您发送的字段（date、end_date、title、body、url、color）。source 不能更改。发送空的 url 会移除链接，date 为 null 会被忽略。该备注必须属于此站点，工作区范围的备注请用 workspace_notes_update 编辑。id（note_...）来自 notes_list。需要 content.write。返回更新后的备注。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/notes/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

添加一条工作区范围的注释，它会出现在工作区中每个站点的图表上，例如公司范围的发布或一次故障。它在创建时不关联站点（site_id 为 null）。若是针对单个站点的备注，请使用 notes_create。date 默认为工作区时区中的今天，end_date 标记一个范围（YYYY-MM-DD），color 为 neutral、brand、blue、amber、red 或 violet 之一。需要 content.write，且仅限部分站点的调用者不能创建工作区范围的备注。返回已创建的备注。

权限： content.write

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/notes.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一条工作区范围的备注，使其从每个站点的图表中消失，且无法恢复。这里只能删除不关联站点的备注，站点备注请使用 notes_delete。id（note_...）来自 workspace_notes_list。需要 content.write，且仅限部分站点的调用者不能删除工作区范围的备注。返回已删除的备注。

权限： content.write

curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/notes/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出工作区范围内的注释，按日期从新到旧排序并分页。它返回工作区范围的备注（显示在每个站点上）以及调用者可访问的每个站点的备注，因此请查看每一项的 site_id（null 表示工作区范围）。单个站点请使用 notes_list。可用 from 和 to（YYYY-MM-DD）、source（manual、deploy、system、import 或 incident）和 query（搜索 title、body 和 url）筛选。字段包括 id（note_...）、site_id、date、end_date、title、body、url、color（neutral、brand、blue、amber、red 或 violet）、source 和 created_at。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/workspaces/:workspace_id/notes.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

编辑一条工作区范围的备注，只更改您发送的字段（date、end_date、title、body、url、color）。这里只能编辑不关联站点的备注，站点备注请使用 notes_update。id（note_...）来自 workspace_notes_list。需要 content.write，且仅限部分站点的调用者不能编辑工作区范围的备注。返回更新后的备注。

权限： content.write

curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/notes/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

把此表单奖励的标题、文字、代码以及开启或关闭状态，复制到 form_ids 中的每个表单（同一网站中 1 到 100 个不在回收站的表单）。目标表单已有的奖励会被替换。当某个 id 不是该网站的表单时，服务器以 422 和代码 unknown_ids 响应，此时不会复制任何内容。

权限： sites.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/settings/rewards/:id/copy.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

每个表单一行。没有设置奖励的表单其 enabled 为 false。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/settings/rewards.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

id 是表单的 id。代码是你提供的文本。Privatus Analytics 不会创建、检查或使其过期。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/settings/rewards/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出公开的套餐（free、pro、business 和 enterprise）及其限制和价格档位，便于您为 billing_checkout、billing_preview 和 billing_change_plan 选择有效的值。每个套餐包含 name、events（包含的每月事件数，分档或定制套餐为 null）、badge_bonus（来自徽章的额外每月事件数，仅限 Free，否则为 null）、limits（套餐限制的对象，如站点数、成员席位、历史保留月数、每个站点的目标数、AI 提问次数和每小时 API 请求数）、tiers（每档含每月事件数以及整数美元的月价和年价，已含增值税或销售税）和 contact_sales（定制套餐为 true）。meta 对象另有 currency、关于年付价格的说明、counted（哪些算作计费事件）和 not_counted。查看某个工作区自己的套餐请使用 billing_get。公开，无需身份验证。

权限： public

curl https://privatusanalytics.com/plans.json

位于 https://privatus.page/w/<slug> 的托管页面。省略的内容会采用默认值：标题 Wall of Love、瀑布流布局，slug 来自名称。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/walls.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

在恢复之前，它的页面会响应已被撤下，嵌入的副本也不会渲染任何内容。恢复后它会回到同一地址。30 天后它会被永久删除。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/walls/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

生成一个带有新 id、名称以“copy”结尾和独立 slug 的副本，因此它有自己的地址。原件及其地址不会改变。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/walls/:id/duplicate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

好评墙的公开地址，以及把它放入其他页面的脚本、框架和纯链接代码片段。编辑好评墙时，这些代码片段不会改变。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/walls/:id/embed.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

网站中所有不在回收站的好评墙，含其地址、内容来源，以及展示的客户评价数量。使用 q 按名称或 slug 搜索，使用 sort 按名称或最新排序。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/walls.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

把好评墙移出回收站。它的页面会在同一地址重新响应，每个嵌入的副本也会重新显示它，无需更改已粘贴的代码。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/walls/:id/restore.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

构建器存储的全部内容：地址（/w/<slug>）、标题和按钮、布局、内容来源、每张卡片显示的内容、样式以及搜索引擎设置。回收站中的好评墙响应 404。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/walls/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

只有发送的输入会更改。更改后的 slug 会让旧地址继续重定向。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/walls/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

站点此刻正在发生什么。返回 live_visitors（最近 5 分钟的访客）、window_minutes（30）、sparkline（最近 30 分钟每分钟的访问数，最早的在前，每项为 {minute, visits}）、feed（最新活动）、top_pages、top_referrers、top_countries（每项最多 8 行 {value, visits}）和 top_events（最多 8 项 {value, completions}），均针对最近 30 分钟。feed 条目包含 occurred_at、kind、name、path、channel、referrer_host、country、device 和 browser。它们是匿名的，没有 IP、城市或访客轨迹。feed 默认显示所有点击，也可只显示浏览量或事件，条数由 limit 决定（默认 50，最多为缓冲区大小 100）。这些数字不会被缓存，也不接受 period。传入 filters（格式与 stats_aggregate 相同），可将所有数字和 feed 限定为匹配的点击。多站点的精简视图请使用 live_wallboard，完整时间段请使用 stats_overview。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/live.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

为一个或多个站点提供精简的大数字卡片，专为办公室屏幕设计。返回 rotate_seconds、generated_at 和 sites。每个站点卡片包含 id（pa_...）、name、domain、live_visitors（最近 5 分钟）、sparkline（最近 30 分钟，每分钟一个点）、visitors_today、pageviews_today、bounce_rate_today（百分比，0 到 100）、top_pages、top_countries 和 top_referrers（各 5 行）。今天指站点自己的时区，数字读取自实时数据。site_ids 列出要包含的站点（最多 12 个，仅限您的令牌可打开的站点），否则使用路径中的站点。rotate_seconds 会被限制在 5 到 300 之间，仅用于告诉屏幕每张卡片显示多久。若要可分享的公开屏幕，请使用 wallboard_links_create。查看单个站点的完整实时视图请使用 live_get。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/live/wallboard.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/wallboard/:token.json

创建一个只读的大屏看板 URL，任何持有它的人无需登录即可打开，因此只应分享给应当看到这些数字的人。路径接受 site_id，此站点始终包含在内。site_ids 添加更多轮播的站点（您可访问的 pa_... ID，总共最多 12 个站点）。rotate_seconds 是每个站点在屏幕上停留的时间，范围 5 到 300（默认 20，超出范围的值会被限制）。expires_at 是 ISO 8601 日期时间，或纯 YYYY-MM-DD 日期，表示站点时区中当天的结束。大屏看板只显示实时数据和当天的汇总数字。返回带 url 的链接。可用 wallboard_links_delete 撤销。

权限： sites.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/live/wallboard/links.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

撤销一个大屏看板链接，使显示它的电视停止更新，URL 也不再有效。此操作无法撤销，请改为创建新链接。重复撤销已撤销的链接不会有任何效果。id（shr_...）来自 wallboard_links_list。返回设置了 revoked_at 的链接。

权限： sites.manage

curl -X DELETE https://privatusanalytics.com/sites/:site_id/live/wallboard/links/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出某个站点的大屏看板链接（路径接受 site_id），按时间从新到旧排序，包括已撤销的。大屏看板链接是一个保密 URL，无需登录即可在电视上显示实时访客和当天的数字。每个链接包含 id（shr_...）、name、url、site_ids（其轮播站点的 pa_... ID）、rotate_seconds、expires_at、revoked_at（撤销后设置）和 created_at。仅限部分站点的调用者只能看到其站点全部属于自己的链接。大屏看板数据本身请使用 live_wallboard。需要 sites.manage 权限。

权限： sites.manage

curl https://privatusanalytics.com/sites/:site_id/live/wallboard/links.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

为站点创建 A/B 测试或分割 URL 测试。它以草稿保存，在有人于应用中启动之前不会把任何访客发送到别处。必填输入为 name、path（原始页面，例如 /pricing）、goal_id（来自 goals_list）和 variants：{ name, path, weight } 的列表，其中第一行是原始页面（忽略其 path），其他每一行是同一站点的一个页面。省略所有 weight 表示平均分配，或发送相加等于 100 的 weight。Free 套餐一次允许一个实验，包含原始页面和一个变体。Pro 及以上增加更多变体、自动分配、定向、路径中的 *、次要目标、定时开始和互斥分组。需要 content.write。返回该实验。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/experiments.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除实验及其变体和结果。此操作无法撤销。若要停止实验并保留结果，请使用 experiments_pause。MCP 工具不会执行它，而是响应 human_only 以及供人删除它的页面。需要 content.write。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/experiments/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

创建一个草稿，其页面、比例、目标和规则与现有实验相同，但没有任何结果。用它来修改已经开始的测试。与新实验一样计入套餐限额。需要 content.write。返回新的实验。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/experiments/:id/duplicate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

结束正在运行或已暂停的实验。它不能再次启动，其结果会保留，并且不再计入套餐限额。MCP 工具不会执行它，而是响应 human_only 以及供人结束它的页面。API 会执行它。需要 content.write。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/sites/:site_id/experiments/:id/end.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

按最新优先列出站点的 A/B 测试和分割 URL 测试。可用 status 筛选（draft、scheduled、running、paused、ended 或 all，默认 all）。使用 page 和 per_page 分页（默认 25，最多 100）。每个实验包含 id（exp_...）、name、status、path（原始页面）、goal_id、variants（id、name、path、weight、control）、结束规则，以及 locked（套餐不再覆盖它时为 true）。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/experiments.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

暂停正在运行或已排期的实验。每位访客会立即再次看到原始页面，目前为止的结果会保留。experiments_start 可以恢复它。需要 content.write。返回该实验。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/experiments/:id/pause.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

按 id（exp_...，来自 experiments_list）返回一个实验及其结果：每个变体在目标上的访问、转化和转化率，以及相对原始页面的提升、差异的可能范围、p 值、在所选置信度下是否显著，以及它胜过原始页面的概率。results.progress 说明距离能够判定获胜者还有多远，results.mismatch.found 为 true 表示访问没有按权重所述分配，因此不应信任该结果。split 按设备、渠道或国家拆分结果（Pro 及以上），humans_only 只保留机器人评分判定为可能是真人的访问（Business）。当访问看到某个变体时，才会计入该变体的访问，转化只在此之后计数。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/experiments/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

启动草稿或已暂停的实验，使原始页面的访客开始被发送到各变体。如果 starts_at 在未来，则会等到那个时间。由于它会重定向真实访客，MCP 工具不会执行它，而是响应 human_only 以及供人启动它的页面。API 会执行它。需要 content.write。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/sites/:site_id/experiments/:id/start.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

更改实验。只有您发送的输入会改变，variants 会替换整个列表。实验开始后，只有 name 和 send_to_winner 可以更改，因为中途更换页面、比例或目标会破坏结果：请使用 experiments_duplicate 并编辑副本。需要 content.write。返回该实验。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/experiments/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回工作区的审计日志，这是一份按时间从新到旧排序并分页的记录，说明谁更改了什么（设置、成员、站点、目标、令牌等）。它需要 workspace.manage 权限和带有审计历史的套餐。Free 套餐没有审计历史，调用会因套餐限制错误而失败，Pro 保留 30 天，Business 保留 365 天，Enterprise 没有限制。超出保留期的条目绝不会返回。可用 actor（成员的邮箱，精确匹配）、item_type（记录类型，如 Site、Goal 或 Membership）、event（create、update 或 destroy）以及 from 和 to（YYYY-MM-DD，含边界，UTC）筛选。每个条目包含 id、created_at、event、item_type、item_id、target（可读的标签，如 Site: example.com）、actor_email（由系统或已删除的用户所做的更改为 null）、actor_name、token_name（使用的 API 令牌，浏览器会话为 null）、changes（将每个更改字段映射到 [before, after] 对的对象，已移除密钥）和 ip（成员或 API 客户端使用的地址，未知时为 null）。同一日志的 CSV 导出仅在应用中提供。

权限： workspace.manage

curl https://privatusanalytics.com/workspaces/:workspace_id/audit_log.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

stats 包含概览页的五个数字：已通过的客户评价、待审核、本月新增、平均评分和使用中。attention 列出需要决定的事项及其数量。activity 是最近 10 个事件，latest_approved 是最近通过的三条客户评价。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/overview.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回 import、testimonials、approve、ask、widget 和 teammate 这些项目，每个都带有 done 和 dismissed。项目是否完成取决于网站实际拥有的内容，绝不是靠点击。当每个项目都已完成或已忽略时 hidden 为 true，此时收件箱不再显示该卡片。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/setup.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

dismiss 是某个项目的键（import、testimonials、approve、ask、widget 或 teammate），或 all 表示整张卡片。忽略会隐藏该项目但绝不会把它标记为已完成，并且无法通过 API 恢复。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/setup.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

等待额度的客户评价不能被通过：服务器以 422 和代码 waiting_for_allowance 响应。响应带有 meta.undo_id。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/:id/approve.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

发送 ids（最多 100 个，一次执行，要么全部成功要么全部不执行）或带 confirm_count 的 filters（整个结果）。超过 100 个会在后台运行，响应的 state 为 running。操作：approve、reject、mark_pending、pin、unpin、add_tags、remove_tags、add_to_collection、remove_from_collection、set_property、trash、restore。每个操作都会响应一个撤销 id，testimonials_bulk_undo 可在 7 天内使用它。delete_permanently 是唯一无法撤销的操作：它需要 sites.manage，其响应显示 undoable 为 false。通过 MCP 时，两个删除类操作 trash 和 delete_permanently 不会执行：工具会以 human_only 和由人工操作的应用页面响应，其他所有操作照常执行。通过 API 时，操作 export（带 ids 或 filters，以及可选的 csv、json、ndjson 或 xlsx 格式）不会更改任何内容：它需要 analytics.export，并以 202 和待下载的导出响应。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/bulk.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

把该次运行更改过的每条客户评价恢复为之前的值。此后又被更改过的评价不会被动，并计入 left。通过 MCP 时，会删除或移入回收站的撤销不会执行（恢复、翻译运行和制作图片运行的撤销）：工具会以 human_only 和由人工操作的应用页面响应。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/bulk/:id/undo.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

通过所有路径共用的同一入口存储。它会计入套餐每月的新客户评价额度，达到额度时服务器以 422 和代码 allowance_reached 响应（只有客户的表单提交会被保留为等待状态）。同一个人再次提交相同内容会被拒绝，代码为 duplicate，除非 allow_duplicate 为 true。再次使用相同的 external_id 会返回已存储的那一条。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

此操作无法撤销。它适用于回收站内或回收站外的客户评价，需要 confirm 和 sites.manage 权限。通过 MCP 时，该工具不会删除任何内容，而是响应由人工操作的页面。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/:id/permanent.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

该客户评价保留其状态、标签、合集和文件，不在任何地方展示，并在 30 天后被永久删除。testimonials_restore 会把它原样恢复。响应带有 meta.undo_id。再次移入已在回收站中的评价不会有任何变化。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

无需读取任何客户评价即可了解整个库的情况。每个筛选项在统计其各个值时，会忽略它自己的选择，并应用其他所有筛选条件。meta 包含总数以及用文字表述的筛选条件。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/facets.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

highlight 必须是客户评价内容中的原文片段，否则服务器以 422 响应。空的 highlight 表示清除。每次更改都是历史记录中的一个版本。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/:id/highlight.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

最新的在前。版本 1 是收到时的客户评价，没有作者。之后的每个版本包含做出更改的成员、时间、他们留下的备注，对于恢复操作，还包含被恢复的版本。通过 page 和 per_page 分页。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/:id/history.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

有三种方式指定范围，且会叠加：筛选项输入（status、tag_id、has_video 等）、q（带运算符的搜索框，例如 rating:5 has:video tag:onboarding "saved us"）以及带 match 的 conditions（结构化行）。发送 facets 为 true，可在 meta.facets 中获得每个筛选值背后的实时数量。除非 trashed 为 true（只列出回收站），否则不会列出回收站中的内容。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

把已通过或已拒绝的客户评价恢复为待审核，因此在再次做出决定之前不会在任何地方展示。响应带有 meta.undo_id。回收站中的客户评价会被拒绝，代码为 in_trash。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/:id/pend.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

置顶的客户评价会在所有展示位置优先显示。发送 pinned 为 false 可取消置顶。有变化时，响应带有 meta.undo_id。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/:id/pin.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

该客户评价保留其所有内容，且不在任何地方展示。再次拒绝已被拒绝的评价不会有任何变化。响应带有 meta.undo_id，testimonials_bulk_undo 可在 7 天内使用它。回收站中的客户评价会被拒绝，代码为 in_trash。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/:id/reject.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

把回收站中的客户评价恢复到其原来的状态、标签、合集和曾经展示它的位置。它绝不会算作新的客户评价。不在回收站中的评价会被拒绝，代码为 not_in_trash。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/:id/restore.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

历史记录中不会移除任何内容。恢复本身是一个新版本，并说明它来自哪个版本。version 1 会把客户评价还原为收到时的内容。未知的版本号会返回 422。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/:id/restore_version.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

按 id（tm_...）返回网站的一条客户评价，无论是否在回收站。除非调用者拥有 content.write，否则 person.email 为 null，has_email 表示是否有记录的邮箱。media 列出文件及其处理状态。used_in 列出展示它的所有小部件、好评墙和图片。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

网站中可公开展示的最新已通过客户评价，用于你在小部件和好评墙之外的自有展示。每条只包含其授权记录允许的内容：不允许显示姓名的人显示为“A customer”，照片或录音除非获得允许否则会被省略。待审核、已拒绝或已移入回收站的客户评价，以及等待额度的评价，永远不会被列出。响应中没有邮箱。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/showable.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

不带筛选时，队列是待审核、不在等待额度的评价，按收到时间从早到晚。带收件箱筛选时，队列是按其排序得到的结果。发送 after 并带上刚处理的 id，即可获得其后的一条。队列处理完时 data 为 null。meta 包含 remaining 和 total。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/triage.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

只更改发送的输入。对 body、title、rating 或 highlight 的更改会在历史记录中添加一个带有 edit_note 的版本，并且绝不会更改已验证标记。rating 为 null 表示清除。highlight 必须是内容中的原文片段，空值表示清除。properties 只更改发送的键。add_tags 和 remove_tags 接受名称或 id。状态、置顶和回收站有各自的工具。回收站中的客户评价不能编辑。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

它使用此人上次用过的表单，或入门表单。在请求被发送之前不会发送任何内容。当此人无法被询问时，服务器以 422 响应，代码为 no_email、bounced 或 unsubscribed，当请求功能不可用时为 requests_unavailable。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/people/:id/ask_again.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

name 为必填（最多 120 个字符）。email 绝不会公开显示：它用于把之后的客户评价归到此人名下，并让网站可以再次询问他们，网站中已有其他人使用的地址会被拒绝。avatar_media_id 是已上传到该网站的图片的 id（med_...）。添加一个人不会添加客户评价。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/people.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

用于删除请求。此操作无法撤销。它需要 confirm（此人的姓名或 id），并留下一条既不含姓名也不含内容的审计记录。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/people/:id/permanent.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

每个人都带有其客户评价数量、已通过的数量、平均评分，以及最近一次询问及其结果。除非调用者拥有 content.write，否则邮箱为 null，而 has_email 仍会说明是否有记录的邮箱。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/people.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

路径中的人会保留。其他记录说过的所有内容和发给他们的每次询问都会转移过来，其他记录会被移除。此人为空的字段会按从旧到新的顺序用其他记录补全，use 指明某个字段以哪条记录的值为准。响应带有 meta.undo_id，testimonial_undo_records_undo 可在 7 天内使用它。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/people/:id/merge.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

他们的客户评价可通过 testimonials_list 加 person_id 获取。can_ask 和 cannot_ask_reason 说明 testimonial_people_ask_again 是否能成功。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/people/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

空值会清除字段，姓名除外。网站中已有其他人使用的邮箱会被拒绝。某人所属的公司页面会跟随公司名称和网站。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/people/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

每个公司一行，根据网站人员的公司名称和网站分组。没有公司的人不属于任何公司。query 匹配公司名称或其网站主机名的一部分。sort 为 name（默认）、people_desc、testimonials_desc 或 received_desc。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/companies.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

路径中的公司的每个人员，都会采用 into 所指定公司的名称和网址。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/companies/:id/merge.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

id 是公司的键，即网站主机名或规范化后的名称，与 testimonial_companies_list 返回的一致。它的客户评价可通过 testimonials_list 加 company 获取。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/companies/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

公司的 id 来自其网址或名称，因此响应中可能带有新的 id。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/companies/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回行，最大的在前，每行带有 key、label、value 和 share（占总数的百分比），比率则带有 numerator 和 denominator。记录类的行（表单、请求、小部件、好评墙、客户评价）带有其 id。每个维度只接受部分指标：form 和 channel 接受表单指标，request 接受请求指标，widget 和 wall 接受各自的浏览、点击、点击率和 video_plays，testimonial 接受 testimonial_views 和 video_plays，page 和 country 接受浏览和点击指标，source 接受 new_testimonials。不匹配的组合会响应 422 并指出可用的指标。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/analytics/breakdown.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

为给定时间段创建一个 kind 为 testimonial_stats 的导出，并返回排队状态。请轮询 exports_get 直到 status 为 complete，然后调用 exports_download。section 选择行：days（每日、每周或每月一行，含所有指标）、forms、channels、requests、widgets、walls、pages、testimonials、sources 或 countries。文件保留 7 天。当排队的导出过多时，响应 422 in_progress。

权限： analytics.export

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/analytics/export.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回“客户评价”下“分析”标签页在某个时间段内显示的全部内容：cards（form_views、submissions、completion_rate、answer_rate、widget_views、wall_views，设置 compare 时各带有 previous 和 change）、chart（一个指标随时间的变化）、每个表单、请求、小部件和好评墙一行、channels（表单是如何被打开的）、pages（在哪里看到了小部件和好评墙）、top_testimonials、new_testimonials（按来源和当前状态）以及 countries。比率是 0 到 100 的百分数，没有分母可除时为 null。网站从未统计过任何内容时 blank 为 true，recorded 列出它曾统计过的指标。这些是客户评价功能的每日合计，不是网站分析：访客和浏览量请使用 stats_overview。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/analytics.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回带有 date、to、value 的数据点，设置 compare 时还有 previous 和 previous_date，以及 total、previous_total 和 change。比率（completion_rate、answer_rate、widget_click_rate、wall_click_rate）根据每个时间段的合计计算，没有分母可除的时间段为 null。new_testimonials 根据客户评价本身按其添加的日期统计。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/analytics/timeseries.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

一次最多 100 条。它们按给定顺序加入到底部，或在 position 为 top 时加入到顶部。响应带有 meta.undo_id，testimonials_bulk_undo 可在 7 天内使用它。智能合集不接受手动添加。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/collections/:id/items.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

kind 为 manual 的合集由人工组合，testimonial_ids 可让它一开始就有内容。kind 为 smart 的合集由条件保持最新：条件是由 match 连接的 field、operator 和 value 行。响应包含数量和用通俗英文描述的规则，因此一次调用就能把一句话变成一个动态合集。请先用 testimonial_collections_preview 试一试规则。kind 之后永远不会改变。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/collections.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

它的客户评价不会受到影响。由它供应内容的小部件或好评墙在其恢复之前不会显示来自它的任何内容。请用 testimonial_trash_restore 恢复它。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/collections/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

每个合集都带有当前包含的客户评价数量、其中已通过的数量、智能合集的规则（用通俗英文描述），以及它所提供内容的小部件和好评墙。回收站中的合集不会列出。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/collections.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

响应当前匹配的客户评价数量、用通俗英文描述的规则和五个示例。请在 testimonial_collections_create 或 testimonial_tags_update 之前使用。无效的行会返回 422 并指出是哪一行。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/collections/preview.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

一次最多 100 条。客户评价本身不会更改。响应带有 meta.undo_id，撤销会把每条放回原来的位置。

权限： content.write

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/collections/:id/items.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

用 position（从 1 开始计数）、before_id 或 after_id 中恰好一个来指定位置。该顺序就是提供给该合集所供应的每个小部件和好评墙的顺序。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/collections/:id/reorder.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

它的客户评价可通过 testimonials_list 加 collection_id 获取。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/collections/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

只有发送的内容会更改。发送 conditions 会替换智能合集的所有规则。kind 是固定的。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/collections/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

一步清除所有颜色、字体、半径、评分样式、徽标和自定义 CSS，每个表单、小部件和好评墙都会随之改变。此操作无法撤销，因此 AI 助手会被引导到品牌套件页面，而不是直接执行。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/settings/brand_kit.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回网站的每个表单、小部件和好评墙所使用的颜色、字体、圆角半径、评分样式、徽标、徽章开关和自定义 CSS。从未更改过的设置会返回 Privatus Analytics 的默认值。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/settings/brand_kit.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

只有你发送的输入会更改。发送空字符串可把某项设置恢复为 Privatus Analytics 的默认值。自定义 CSS 在保存时会被检查，不允许的内容会被拒绝，并指出所在的行。自定义 CSS 需要 Business 套餐，隐藏徽章也需要 Business 套餐。没有该套餐时，服务器响应 402 plan_limit。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/settings/brand_kit.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

此操作无法撤销。对于单个条目，confirm 是该条目的名称（客户评价则为此人的姓名）或其 id，对于多个条目则是网站的名称。只接受回收站中的条目。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/trash/permanent.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

此操作无法撤销。confirm 是网站的名称。一次最多删除 100 个条目。更大的回收站会在后台清空，响应的 state 为 running。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/trash/empty.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

响应一种类型的条目（默认为 testimonial），并在 meta.counts 中给出回收站中每种类型的数量。每个条目会说明它恢复后的状态、曾展示它的位置、谁把它移入回收站以及何时会被清除。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/trash.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

id 必须属于同一种类型。恢复客户评价会响应一个撤销 id（data.id 和 meta.undo_id），testimonial_undo_records_undo 可在 7 天内使用它。恢复绝不会算作新的客户评价。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/trash/restore.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

每次运行最多 200 条客户评价，每种尺寸一张图。对图片来说过长的文字，会取其高亮部分来绘制，否则取开头的几句话（excerpted 说明有多少条如此处理）。响应列出已开始制作的图片、被排除的客户评价及原因，以及 export_id：图片绘制完成后，一个包含这些 PNG 的 zip 会出现在“导出”页面。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/images/bulk.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

只有已通过的客户评价才能被绘制成图，因为 PNG 会有一个公开地址：任何其他评价都会被拒绝，代码为 not_approved。每张图片开始时为 rendering，并在后台绘制。响应是已开始制作的图片列表。请轮询 testimonial_images_get 获取 file_url。返回 422 且代码为 text_too_long 表示文字放不下：请使用 text_mode 为 highlight 或 excerpt，或使用更高的尺寸。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/images.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

PNG 会从媒体主机上删除，其地址随之失效。图片没有回收站。可以用 testimonial_images_create 从其客户评价重新制作。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/images/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

由已通过的客户评价制作的图片，最新的在前，每页 25 张。可按 status、template、size 或 testimonial_id 筛选。每张图片在就绪后都带有 file_url。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/images.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

status 为 rendering、ready 或 failed。就绪后会设置 file_url。在 testimonial_images_create 之后请轮询它，直到 status 不再是 rendering。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/images/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

只发送要更改的内容。什么都不发送时，它会根据客户评价当前的内容重新渲染同一张图片，这也是重试失败图片的方式。新的渲染有新的 file_url，旧文件会被删除。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/images/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

有两种方式。上传时，发送 filename、content_type 和 byte_size：响应包含 upload，其中有用于 PUT 文件的 url、随请求发送的标头，对于大文件还有可以逐个发送的 parts。然后调用 testimonial_media_uploads_finish。或者发送 source_url，系统会为你下载并处理文件：请轮询 testimonial_media_get 直到其 state 为 ready。限制：视频和音频最大 500 MB，时长以套餐允许为限（Pro 为 2 分钟，Business 为 10 分钟，Free 不支持，此时服务器响应 402 plan_limit），图片最大 10 MB，徽标最大 2 MB。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/media/uploads.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

属于某条客户评价的文件会随该客户评价一起通过回收站被删除。已存储的文件会被删除，其地址会从缓存中清除。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/media/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

文件发送完毕后调用它。文件必须已在上传存储中，且大小与承诺的完全一致。调用两次也是安全的。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/media/uploads/:id/finish.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

根据保留的上传重新处理该文件。上传在失败后保留 24 小时。之后服务器会以 not_retryable 响应，文件需要重新上传。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/media/:id/retry.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

url 是媒体主机上已完成文件的持久地址，在 state 变为 ready 之前为 null。该地址对所有人都相同且未经签名，因此只应传递 shareable 字段为 true 的文件的地址。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/media/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

平台会根据链接自动识别。运行找到的内容会在审核步骤（testimonial_import_sources_review）中等待，在 testimonial_import_sources_keep 之前不会存储任何内容。任何导入的内容都不计入每月的客户评价额度。Free 套餐每月可从评价网站或页面获取 1 次导入。超出后响应为 402 plan_limit。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/imports/sources.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

删除该来源及其运行历史、审核步骤中等待的内容和上传的文件。已从该来源保留的客户评价会留在网站中。这需要由人工在来源页面上操作，因此该工具不会执行任何操作，而是返回该页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/imports/sources/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

提供 item_ids（来自 testimonial_import_sources_review 的 id）或设置 all 为 true 以丢弃仍在等待的全部条目，不能同时使用。被丢弃的条目会离开审核步骤，读取到的有关此人的信息会被清除。不会删除任何客户评价。否则服务器以 422 和代码 selection 或 unknown_ids 响应。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/imports/sources/:id/discard.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

读取网站的域名，以及它所链接的、看起来包含客户评价的页面，每个网站只读一次。这是免费的：它不算 Free 套餐的获取导入次数。找到的内容会在它返回的来源的审核步骤中等待处理。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/imports/find.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

meta 包含 fetched_imports（本月的 used、limit 和 resets_on，limit 为 null 表示不限）和 sync（套餐允许的频率）。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/imports.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

提供 item_ids（最多 100 个）或 all。每个保留的条目都通过与其他客户评价相同的路径存储，因此重复项绝不会被存储两次。任何保留的内容都不计入每月的客户评价额度。meta 说明保留了多少条。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/imports/sources/:id/keep.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

经过测试的来源注册表。只有在针对真实页面验证过导入后，平台才会被列出。每个条目会说明要粘贴哪个链接。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/imports/platforms.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

meta 包含按标记统计的数量（new、already_here、likely_duplicate）。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/imports/sources/:id/review.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

手动运行算作一次获取导入，并在 Free 套餐上计入当月的次数（超出后为 402 plan_limit）。当有运行正在进行时会被拒绝（422 in_progress），在任何套餐上，同一来源 24 小时内运行 3 次之后也会被拒绝（422 too_many_runs）。对出错的来源，它会清除失败次数。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/imports/sources/:id/run.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回平台、名称、读取的地址、重新读取的频率、状态、审核步骤中等待的条目数、已保留的数量、连续失败次数，以及上次运行和下次运行的时间。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/imports/sources/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

超出套餐的同步（Free 上的任何同步，Pro 上的每周同步）会被拒绝，响应为 402 plan_limit。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/imports/sources/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

每次运行包含其编号、触发方式、状态、读取的页面数，以及找到的客户评价数、其中新增、重复、失败和保留的数量，还有开始和结束时间。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/imports/sources/:import_source_id/runs.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

个人视图只需要 analytics.read。共享视图需要 content.write，否则会被拒绝，代码为 not_allowed。固定的视图会连同数量显示在侧边栏中。请使用 testimonials_list 和 view_id 打开它。

权限： analytics.read

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/views.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

已保存视图只是一个存储的筛选条件，因此只会删除视图本身。由该视图提供内容的小部件或好评墙会保留其设置，在为它指定其他数据来源之前没有内容可展示。个人视图由其所有者删除，共享视图需要 content.write，否则调用会被拒绝，代码为 not_allowed。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： analytics.read · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/views/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回调用者自己的视图和所有共享视图，固定的在前并按其顺序排列，然后按名称排序。scope 为 all（默认）、mine 或 shared。把视图的 id 作为 view_id 传给 testimonials_list，即可读取它包含的客户评价。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/views.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

只有发送的输入会更改：name、已存储的搜索（q）、filters、sort、layout、columns、position、pinned 和 shared。个人视图由其所有者更改。更改共享视图，以及共享或取消共享任何视图，都需要 content.write。

权限： analytics.read

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/views/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

每个词都带有包含它的客户评价数量、占比、这些评价的平均评分，以及最近 90 天与之前 90 天的对比。按 rating_asc 排序可看到人们抱怨什么，按 rising 排序可看到有什么新情况。meta.refreshed_at 说明这些词上次重建的时间。把词作为 mention 传给 testimonials_list，即可读取相应的客户评价。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/mentions.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

对整个结果执行的一个批量操作，可撤销。这个词可以是任何单词或双词短语，按照统计“提及”时的方式用词干匹配。首次使用的标签名称会被创建。响应一个撤销 id，testimonials_bulk_undo 可在 7 天内使用它。超过 100 条会在后台运行。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/mentions/tag.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

被隐藏的词会离开“提及”列表和收件箱的“提及”筛选项，并在重建这些词时保持隐藏。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/mentions.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

最新的在前。每条记录说明运行了什么、谁运行的、更改和跳过了多少条及原因，以及可撤销到什么时候。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/settings/undo.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

对于在后台运行的任务，state 为 running，processed 说明进度。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/settings/undo/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

把该次运行更改过的所有内容恢复为之前的值。此后又被更改过的内容不会被动，并计入 left。人员合并或重复项合并也以同样的方式撤销。通过 MCP 时，会删除或移入回收站的撤销不会执行（恢复、翻译运行和制作图片运行的撤销）：工具会以 human_only 和由人工操作的应用页面响应。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/settings/undo/:id/undo.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

dry_run 为 true（默认）时不会更改任何内容，只响应数量：会给多少条打标签、共有多少条，以及多少条已有该标签。dry_run 为 false 时，会作为一个批量操作打标签，并响应 undo_id，testimonials_bulk_undo 可在 7 天内使用它。超过 100 条会在后台运行，响应的 state 为 running。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/tags/:id/apply_rules.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

规则的形式为 { match, conditions }。满足任意一条规则的客户评价会在到达的那一刻获得该标签。规则只会添加标签。要给已存储的评价打标签，请接着调用 testimonial_tags_apply_rules。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/tags.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

它会从每条客户评价、筛选器和选择器中消失。用 testimonial_trash_restore 恢复它，会把它放回曾有它的每条客户评价上。规则中提到它的智能合集，在此之前不会匹配任何内容。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/tags/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

每个标签都带有使用它的客户评价数量、以结构化条件和通俗英文表示的自动标签规则，以及规则上次应用的时间。回收站中的标签不会列出。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/tags.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

拥有此标签的每条客户评价都会获得另一个标签，每条规则都会转移到另一个标签，每个提到此标签的智能合集、已保存视图、小部件和好评墙都会改为引用另一个标签，而此标签会被清空并移入回收站。响应保留下来的那个标签。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/tags/:id/merge.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

只有发送的内容会更改。发送 rules 会替换该标签的所有规则，空列表会移除全部规则。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/tags/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

电子表格导入的第 1 步。发送 file（CSV、TSV 或 XLSX，最大 10 MB 和 5,000 行，首行为表头）或 content（最大 1 MB 的 CSV 文本）。响应包含各列、每列的三个示例值，以及对每列去向的初步猜测。此时还没有导入任何内容：请继续使用 testimonial_spreadsheet_imports_update 和 testimonial_spreadsheet_imports_run。电子表格绝不计入每月的客户评价额度或获取导入次数。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/imports/spreadsheet.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

可用的行会带着勾选框等待处理。不可用的行会连同行号和原因一起列出。请使用 testimonial_import_sources_keep 保留它们，并把电子表格的 id 作为来源 id。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/imports/spreadsheet/:id/run.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回文件的各列及示例值、每列对应的字段、选项（默认状态、标签、合集、日期格式、重复项的处理方式），以及运行之后在审核步骤中等待的行数和已保留的行数。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/imports/spreadsheet/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

电子表格导入的第 2 步和第 3 步。mapping 是列名到字段的对象，空值表示忽略该列，两列不能对应同一个字段。选项包括 default_status（pending 或 approved）、tags、collection_id（手动合集）、default_source_name、date_format（auto、ymd、dmy 或 mdy）和 duplicates（skip 或 queue）。只有发送的内容会更改，在 testimonial_spreadsheet_imports_run 之前不会导入任何内容。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/imports/spreadsheet/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

请先调用 testimonial_translations_estimate。这会把所选客户评价的内容、标题和高亮发送到 Google Cloud Translation（绝不包含姓名、邮箱或公司），并通过电子邮件告知成员这是由 AI 助手启动的。翻译在后台进行，已存储的行绝不会被再次获取。达到本月字符配额时，其余的会被存为等待状态，并在 1 日继续。低于 Business 套餐时响应 402 plan_limit，翻译尚未设置时响应 422 not_configured。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/translations.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

在使用该语言的任何地方，客户评价都会重新以其自己的原文展示。已为它花费的字符不会退还。在每个套餐上都可使用。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/translations/:testimonial_id/:language.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

用其中一种方式指定客户评价：testimonial_ids、collection_id 或 all_approved。响应给出客户评价数量、将发送的字符数、已存储的字符数以及本月剩余的字符数。它只说明字符数，绝不给出价格。不会获取任何内容。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/translations/estimate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

每条客户评价每种语言一行，最近更改的在前，每页 25 条。可按 language、state、origin 或 testimonial_id 筛选。在每个套餐上都可使用，因此降级前制作的翻译仍可阅读。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/translations.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

该行会被标记为已编辑，之后的运行不会覆盖它，除非发送了 overwrite_edited。不会获取任何内容，也不会计入配额。原文永远不会被更改。适用于 Business 及以上（其他套餐为 402 plan_limit）。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/translations/:testimonial_id/:language.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

客户评价的自定义域名由 Privatus Analytics 团队手动设置。这会保存请求并通知团队，团队会通过电子邮件发送需要添加的 DNS 记录。在请求状态变为 active 之前，该主机名不会生效。适用于 Business 及以上：其他套餐会得到 402 plan_limit。

权限： sites.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/settings/custom_domain.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

只有团队尚未开始处理的请求（状态为 requested）才能撤回。处理中的请求会响应 wrong_state。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/settings/custom_domain.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

针对好评墙或表单的每个主机名请求，最新的在前，含其状态。只有状态变为 active 后主机名才会生效。在每个套餐上都可使用，因此之前的请求仍可阅读。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/settings/custom_domain.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

一个网站最多可有 20 个启用的属性。key 一经创建就固定，因为表单链接、规则和 API 都会用到它。省略时会根据标签文字给出建议。

权限： sites.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/settings/properties.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

此操作无法撤销。它会移除该属性，以及每条客户评价上的对应值。confirm 是该属性的 key。被智能合集或自动标签规则使用的属性，在它们仍在使用时不能被删除。归档才是日常停用属性的方式。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/settings/properties/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

每个属性都会说明其 key、类型和选项、有多少条客户评价有值（filled）、其类型是否仍可更改，以及哪些智能合集和自动标签规则使用了它。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/settings/properties.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

只有你发送的输入才会产生更改。重命名某个选项会在所有拥有它的客户评价上同步重命名。被智能合集或自动标签规则使用的属性，在它们仍在使用时不能被归档。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/settings/properties/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

默认语言、提供的语言、新通过的客户评价是否自动翻译、套餐是否包含翻译、翻译是否已设置，以及本月已用和剩余的字符数。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/settings/languages.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

只发送要更改的内容。默认语言始终包含在提供的语言中，表单所用的语言不能被移除（in_use）。开启 auto_translate 需要 Business 或更高套餐（其他套餐为 402 plan_limit）：此后每条新通过的客户评价的内容都会发送到 Google Cloud Translation，并且会通过电子邮件告知成员这是由 AI 助手更改的。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/settings/languages.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

这是确认页面按钮背后的 POST。它会解除退订，因此可以再次向该地址发出请求。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/requests/resubscribe/:token.json \
  -H "Content-Type: application/json" -d '{…}'

如果该地址曾退订，会向该地址本身发送一封确认邮件。无论其是否退订过，响应都相同。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/requests/resubscribe.json \
  -H "Content-Type: application/json" -d '{…}'

这是退订页面按钮背后的 POST，也是邮件应用自带的退订按钮所调用的接口。令牌来自邮件中的链接。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/requests/unsubscribe/:token.json \
  -H "Content-Type: application/json" -d '{…}'

创建一个带有邮件和收件人的草稿。在 testimonial_requests_send 之前不会发送任何内容。省略的内容会采用默认值：邮件内容、5 天后的一封跟进邮件、以网站名称作为发件人、你作为回复地址。每个收件人会被存储为排队状态，或附带原因存储为跳过。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/requests.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

只有从未发送过的请求才能被删除。已发送的请求会作为已发邮件的记录保留。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/requests/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

副本使用相同的表单和邮件，尚无收件人。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/requests/:id/duplicate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

最新的在前，每个都带有其邮件和漏斗数量。可按状态、表单或时间段筛选。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/requests.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

发件人、主题，以及填入合并字段后的正文。不会发送任何内容。step 为 0 是第一封邮件，1 到 3 是跟进邮件。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/requests/:id/preview.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

从停止的地方继续。停止期间到期的跟进邮件会从现在起重新计时，因此不会一下子全部发出。这会向工作区之外的人发送邮件，因此会通过电子邮件告知成员这是由 AI 助手恢复的。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/requests/:id/resume.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

需要 confirm_relationship: true。排队的收件人会再检查一次，然后发出第一批邮件（或等待 send_at）。跟进邮件会发给尚未回复的人。请求邮件通过网站自己的邮件服务商发送（设置 > 邮件发送，Business 及以上），因此没有可用连接的网站会得到 422 no_email_connection 或 email_connection_paused，其他套餐会得到 402 plan_limit。每封邮件都计入网站每月的请求邮件上限（10,000 封，除非我们另行设置）。达到上限时不会丢弃任何内容：这些人仍保持排队状态，并在 1 日继续发送。这会向工作区之外的人发送邮件，因此会通过电子邮件告知成员这是由 AI 助手发送的。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/requests/:id/send.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

只会发送到调用者自己的地址，并像真实邮件一样通过网站自己的邮件服务商发送（没有连接时为 422 no_email_connection）。它没有个人链接和打开计数器，也不计入网站每月的上限。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/requests/:id/send_test.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回一个请求的邮件、跟进邮件、状态和漏斗数量（sent、opened、clicked、submitted、bounced、unsubscribed）。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/requests/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

立即取消每封尚未发送的邮件。已经发送的内容不受影响，testimonial_requests_resume 会从停止的地方继续。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/requests/:id/stop.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

随时都可以更改。更改会应用于所有尚未发送的邮件。更改跟进邮件的延迟会重新安排正在等待的跟进邮件的时间。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/requests/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

一次调用最多 500 人。添加到草稿中的人会等待 testimonial_requests_send。添加到进行中的请求的人会立即收到第一封邮件。响应会按原因说明有多少人已排队、多少人被跳过。向进行中的请求添加人员会向工作区之外的人发送邮件，因此会通过电子邮件告知成员。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/requests/:request_id/recipients.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

只限尚未向其发送过任何内容的人（排队或跳过）。请求正文最多接受 100 个地址。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/requests/:request_id/recipients.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

需要两次调用。先发送文件（或其文本 csv），获取各列、前几行和 upload_token。然后发送从列号到字段的映射。最大 5 MB 和 10,000 行。向进行中的请求添加人员会向工作区之外的人发送邮件，因此会通过电子邮件告知成员。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/requests/:request_id/recipients/import.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

按此人当前所处的状态筛选：状态 opened 表示“已打开但未点击或回复”。除非调用者可以编辑内容，否则邮箱地址为 null。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/requests/:request_id/recipients.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

他们从停止的地方继续。请求正文最多接受 100 个地址。这会向工作区之外的人发送邮件，因此会通过电子邮件告知成员。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/requests/:request_id/recipients/resume.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

他们不会再收到邮件。每个人保留其状态，并额外获得“stopped”标记。请求正文最多接受 100 个地址。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/requests/:request_id/recipients/stop.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

删除该连接及其密钥。仍在等待第一封邮件的买家不会被询问。常设请求会保留，作为已发送内容的记录。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/settings/purchase_connections/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

每个连接都带有其规则、状态和常设请求。密钥绝不会被返回。在不包含购买后请求功能的套餐上，paused 为 true：连接会被保留，但不读取付款，也不向任何人发出请求。

权限： sites.manage

curl https://privatusanalytics.com/sites/:site_id/testimonials/settings/purchase_connections.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

提供 item_ids（来自 testimonial_migrations_review 的 id）或设置 all 为 true 以丢弃仍在等待的全部内容，不能同时使用。被丢弃的条目会离开审核步骤，读取到的有关此人的信息会被清除。不会删除任何客户评价。否则服务器以 422 和代码 selection 或 unknown_ids 响应。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/imports/migrations/:id/discard.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

最新的在前。一次迁移对应来自另一个客户评价工具的一个导出文件。每次迁移包含来源工具、状态，以及找到、保留、重复和失败的客户评价数量。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/imports/migrations.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

提供 item_ids（每次调用最多 100 个，来自 testimonial_migrations_review）或设置 all 为 true，不能同时使用。每个保留的条目都会成为状态为 pending 或 approved 的客户评价，keep_approval 为 true 时会保留其在另一个工具中的通过状态。使用 all 时，疑似重复项会被排除，除非 include_likely_duplicates 为 true。任何保留的内容都不计入每月的客户评价额度。未保留的内容会在审核步骤中保留 30 天。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/imports/migrations/:id/keep.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出仍在等待决定的条目，最新一次运行的在前。show 为 new、duplicates 或 all（默认），rating 只保留所列的星级评分。把条目 id 传给 testimonial_migrations_keep 或 testimonial_migrations_discard。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/imports/migrations/:id/review.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回文件来自哪个工具、状态、找到、保留、重复和失败的客户评价数量、带来多少媒体文件，以及开始和结束时间。当状态显示文件仍在读取时请轮询它。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/imports/migrations/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

testimonial_ids 必须是重复项队列中某个未处理分组的所有不在回收站中的副本，与 testimonial_duplicates_list 返回的一致。不会合并任何内容，也不会更改客户评价，它们永远不会再被分到一组。要拆分一个三条的分组，请先合并其中相同的两条。当这些 id 不恰好是一个未处理的分组时，服务器以 422 响应。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/duplicates/dismiss.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

完全匹配的在前。每个分组包含其全部副本，以及 keeper_id，即将被保留的副本。meta.exact_groups 是 testimonial_duplicates_merge_exact 会合并的分组数。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/duplicates.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

保留者保留其状态和已验证状态，以及它自己的内容，除非 body_from 指定了另一个副本。它会获得自己缺少的标签、手动合集、展示位置和自定义属性。副本会被移入回收站并标记为已合并，恢复某个副本会撤销该副本的合并。本月到达的副本不再算作新的客户评价。响应带有 meta.undo_id。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/:id/merge.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

先发送 dry_run 获取数量，再发送 confirm_count 并带上它给出的总数。每次调用最多合并 100 个分组。响应带有 meta.undo_id，一次撤销就能撤回整个运行。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/duplicates/merge_exact.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

移除调用成员为此站点所在工作区存储的 Google Analytics 连接，因此在应用中重新连接之前，GA4 导入将无法再从 Google 读取。已导入的数据会保留，只有用 imports_delete 删除对应的导入才会移除。授权不会在 Google 一侧被撤销。如果没有连接，或该成员的某个 GA4 导入正在排队或运行，它会因验证错误而失败。返回 disconnected 为 true 的对象。连接需在应用中完成（Google 登录界面），没有对应的工具。

权限： sites.manage

curl -X DELETE https://privatusanalytics.com/sites/:site_id/imports/google/connection.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出调用成员已连接的 Google 账户可读取的 Google Analytics 4 媒体资源。在使用 source 为 ga4 的 imports_create 之前调用它，以获得要使用的 property_id。返回对象列表，每个含 id（如 properties/123456789，将其作为 property_id 传入）、name 和 account。如果该成员尚未为此工作区连接 Google（需在应用中完成，没有对应的工具），或 Google 拒绝了请求，它会因验证错误而失败。它会实时调用 Google，且不会更改任何内容。

权限： sites.manage

curl https://privatusanalytics.com/sites/:site_id/imports/google/properties.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

开始将另一个分析工具中的历史数据导入到站点，在后台处理，并返回状态为 queued 的导入。选择 source 为 ga4 可从 Google Analytics 4 API 拉取，这需要在应用中建立的 Google 连接、property_id（来自 imports_google_properties）和 date_from。date_to 默认为站点第一个被跟踪事件的前一天，或昨天。其他来源（universal_analytics、fathom、simple_analytics、plausible、matomo、umami、clicky）需要以 file 输入上传的 CSV 导出（multipart 表单上传，最大 50 MB），这使得它们不便通过 MCP 发起，最好在应用中完成。dimension 仅在需要覆盖对 CSV 行拆分依据的自动检测时才需要，例如 Matomo 的 Label 导出。导入的行绝不会计入事件额度，只有在您传入 include_imported 为 true 时才会出现在统计中。一个工作区同时最多可有 5 个排队或运行中的导入。请轮询 imports_get 直到 status 为 complete 或 failed。需要 sites.manage 权限。

权限： sites.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/imports.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一个导入及其带入的每一行数据和上传的文件。当 include_imported 开启时，包含导入数据的统计会立即变化，此操作无法撤销，不过您可以重新导入。id 来自 imports_list，并且需要 site_id。返回已删除的导入。需要 sites.manage 权限。跟踪器收集的数据不受影响。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/imports/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出某个站点的导入，按时间从新到旧排序。用它查找导入 ID，或检查某个导入是否仍在运行。可按 status（queued、running、complete 或 failed）筛选。通过 page 和 per_page 分页（最大 100）。每一项包含 id、site_id、source、status、date_from、date_to、rows_imported、error、completed_at 和 created_at。详情见 imports_get，开始导入见 imports_create。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/imports.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回某个站点的一个导入，用于轮询由 imports_create 启动的导入。字段包括 id（imp_...）、site_id、source、status（queued、running、complete 或 failed）、date_from 和 date_to（YYYY-MM-DD，未知时为 null）、rows_imported（已导入的每日行数）、error（失败时设置）、completed_at 和 created_at。id 来自 imports_create 或 imports_list。只有当统计调用将 include_imported 设为 true 时，导入的行才会显示在统计中。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/imports/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

将数据导出加入队列，在后台生成，并立即返回状态为 queued 的导出。需要文件（CSV、JSON、XLSX、NDJSON，或仪表板面板的 ZIP）时选择它，并可先用 exports_preview 检查列和大小而不创建任何内容。对于轻量的数字，请改用统计工具。必填输入为 workspace_id（路径）、site_id、from 和 to（YYYY-MM-DD，含边界，使用导出时区）。kind 决定导出什么以及适用哪些选项。aggregated（默认）按时间段给出访问指标，并使用 grouping、dimensions（最多 6 个）、metrics、filters 和 segment_id。pageviews、events 和 raw 每次点击一行，使用 fields、filters 和 segment_id，需要 Pro 或更高套餐，并限制在 400 天内（raw 为 93 天）。imported 给出导入的每日统计，只使用 dimensions。dashboard 给出概览面板的 ZIP（仅限 zip 格式）。各 kind 允许的 file_format 为：aggregated、pageviews、events 和 imported 使用 csv、json 或 xlsx，raw 使用 csv 或 ndjson，dashboard 使用 zip。不适用于所选 kind 的选项会被忽略。一个工作区同时最多可有 5 个排队或运行中的导出。响应是导出对象，包含 id（exp_...）、status、row_count 和 expires_at（生成之前为 null）。请轮询 exports_get 直到 status 为 complete，然后调用 exports_download。就绪时发起请求的用户会收到邮件，并发送 export.ready Webhook，该操作也会写入审计日志。props 列中的事件属性只包含已标记为可安全导出的属性（见 event_properties_list）。

权限： analytics.export

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/exports.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一个导出及其生成的文件。下载链接会立即失效，此操作无法撤销，但您可以重新创建该导出。用它来移除不再需要的已完成或失败的导出，因为文件在生成 7 天后也会被自动删除。id 来自 exports_list。返回删除前的导出对象。

权限： analytics.export · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/exports/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回已完成导出的短期下载链接。在 exports_get 显示 status 为 complete 之后选用它。响应包含 url（有效期 10 分钟的签名链接，请立即获取）、expires_at（链接失效的时间，ISO 8601）、filename 和 byte_size（字节）。当导出已超过 7 天时，它会以错误代码 expired 的 not found 错误失败，当导出仍在排队或运行，或已失败时，则以验证错误失败（错误消息会说明原因）。只要导出本身未过期，再次调用即可获得新的链接。id 来自 exports_list。

权限： analytics.export

curl https://privatusanalytics.com/exports/:id/download.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

列出工作区中您可访问站点的导出，按时间从新到旧排序。用它查找导出 ID、查看哪些导出仍在运行，或查看哪些已过期。可用 site_id、status（queued、running、complete、failed 或 expired）和 kind（aggregated、pageviews、events、imported、raw 或 dashboard）筛选。通过 page 和 per_page 分页（最大 100），返回 data（导出列表，字段见 exports_get）以及分页 meta。需要来自 workspaces_list 的 workspace_id。

权限： analytics.export

curl https://privatusanalytics.com/workspaces/:workspace_id/exports.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

导出的试运行，不会创建任何内容。它接受与 exports_create 相同的输入，并返回 kind、file_format、columns（按顺序排列的列名）、rows（最多 20 行示例，以列为键的对象）和 estimated_rows（完整文件的大致行数）。对于 dashboard 类型，示例行会列出每个文件名及其行数。在调用 exports_create 之前，用它来验证维度、字段、筛选条件和日期范围，并了解导出会有多大。它是同步运行的，因此请让日期范围保持合理。验证错误与 exports_create 相同，包括行级类型需要 Pro 套餐的要求。不会存储任何内容，也不会发送邮件。

权限： analytics.export

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/exports/preview.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回一个导出，包括其进度。用它轮询由 exports_create 启动的导出，直到 status 为 complete 或 failed。状态有 queued、running、complete、failed 和 expired。字段包括 id（exp_...）、site_id（pa_...）、kind、format、status、params（导出的存储定义）、row_count（完成之前为 null）、error（失败时设置）、completed_at、expires_at（文件在完成后保留 7 天）、download_url（仅在文件可下载时设置，请使用 exports_download 获取签名链接）和 created_at。id 来自 exports_create 或 exports_list。

权限： analytics.export

curl https://privatusanalytics.com/exports/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

粘贴式 HTML 不会自行更新。调用之后，testimonial_widgets_embed 会报告此后小部件改变了多少次。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/widgets/:id/copied.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

一次调用就包含整个小部件：布局及其选项、内容来源、每张卡片显示的内容以及外观。省略的内容会采用默认值，留空的样式设置会继承品牌套件。随后请调用 testimonial_widgets_embed 获取要粘贴的代码。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/widgets.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

在恢复之前，它的嵌入不会渲染任何内容，也不占用空间。30 天后它会被永久删除。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/widgets/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

生成一个带有新 id、名称以“copy”结尾的副本。副本有自己的嵌入代码，且尚未在任何地方被看到上线。原件不会改变。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/widgets/:id/duplicate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回脚本代码片段（推荐）、粘贴式 HTML、框架代码和公开数据的地址，以及加载器脚本和此小部件的实测大小。对于角落弹窗，粘贴式 HTML 和框架为 null。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/widgets/:id/embed.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

回收站中的小部件不会列出。每个小部件都带有其设置、当前展示的客户评价数量、最近 30 天的浏览和点击，以及它首次被看到上线的页面。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/widgets.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

最多 50 个页面，最新的在前。只能检测到脚本和框架。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/widgets/:id/installs.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

它会回到被粘贴过的每个位置。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/widgets/:id/restore.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

构建器存储的全部内容：布局及其选项、提供内容的来源（合集、已保存视图、标签或手动挑选的列表）、每张卡片显示的内容、样式、语言和评价标记，以及它在哪里被看到上线、当前展示多少条客户评价。回收站中的小部件响应 404。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/widgets/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

只有发送的输入会更改。保存的更改会传到小部件所在的每个网站，无需改动它们的代码，因为它的缓存副本会被清除。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/widgets/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回工作区的白标品牌设置。字段包括 workspace_id（ws_...）、brand_name、brand_logo_url 和 brand_color（十六进制颜色，如 #06755b），未设置时均为 null，另有 hide_branding、available（套餐包含白标时为 true，即 Business 及以上）和 active（已设置品牌且已生效时为 true）。该品牌设置会在共享仪表板、嵌入内容、状态页和邮件报告中替代 Privatus Analytics。需要 workspace.manage。

权限： workspace.manage

curl https://privatusanalytics.com/workspaces/:workspace_id/white_label.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

设置工作区的白标品牌。仅限 Business 套餐，否则会因套餐错误而失败。只有您发送的输入会被更改，空字符串会清除 brand_name、brand_logo_url 或 brand_color。brand_logo_url 必须是指向图片的 https URL，brand_color 必须是 #06755b 这样的十六进制颜色。hide_branding 为 true 会移除共享仪表板、嵌入内容和状态页中指向 Privatus Analytics 的链接，以及邮件报告中的徽标。更改会立即应用于现有的共享链接。需要 workspace.manage。返回品牌设置（见 white_label_get）。

权限： workspace.manage

curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/white_label.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回工作区的安全策略。字段包括 workspace_id（ws_...）、enforce_2fa（成员必须使用双重验证）、login_methods（允许的登录方式，取自 password、magic_link、passkey、google、github 和 sso）、session_ttl_hours（经过这么多小时后退出登录，不限制时为 null）、app_ip_allowlist（允许使用应用和 API 的 IP 或 CIDR 范围，为空表示任何地方）和 support_access_until（Privatus Analytics 支持团队可查看该工作区的截止时间，ISO 8601，未授予访问权限时为 null）。需要 workspace.manage。

权限： workspace.manage

curl https://privatusanalytics.com/workspaces/:workspace_id/security.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

更改工作区的安全策略，只更改您发送的输入。enforce_2fa 为 true 会要求每位成员使用双重验证，并需要 Business 套餐。login_methods 会用 password、magic_link、passkey、google、github 和 sso 中的值替换允许列表，移除某种方式会使成员已记住的登录退出，他们必须重新登录。session_ttl_hours 会在这么多小时后让成员退出登录（0 表示取消限制）。app_ip_allowlist 会替换允许访问应用和 API 的 IP 或 CIDR 范围列表（Business 套餐，空列表表示任何地方），如果它会把调用者的 IP 排除在外则会被拒绝，因此您不会把自己锁在外面。support_access 为 true 会让 Privatus Analytics 支持团队查看该工作区 7 天，false 则撤回该访问权限。需要 workspace.manage。返回该策略（见 workspace_security_get）。

权限： workspace.manage · 仅限 HTTP（不是 MCP 工具）

curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/security.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

权限： member · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/workspaces.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

删除工作区及其所有站点。这是软删除，所有内容会立即消失并在 7 天后被永久清除，因此请将其视为不可逆。只有所有者可以执行，且 confirm 必须是工作区的确切名称（区分大小写）。有效的付费订阅会先被立即取消，如果取消失败则不会删除任何内容。该工作区待处理的站点转让会被取消。成员会失去访问权限。使用 workspaces_get 读取名称。需要 workspace.manage 和所有者角色。返回该工作区。

权限： workspace.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/workspaces/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出调用者所属的工作区，按名称排序。API 令牌或 MCP 连接只能看到为其签发的那一个工作区。每一项包含 id（ws_...，大多数工具用作 workspace_id）、name、timezone、currency、plan、plan_events、subscription_status 和 role（调用者的角色）。接下来请用工作区 ID 调用 sites_list 查找站点 ID。只能在应用中创建工作区。

权限： member

curl https://privatusanalytics.com/workspaces.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

按公开 ID（ws_...，来自 workspaces_list）返回一个工作区。字段包括 id、name、timezone（IANA 名称）、currency（ISO 4217）、plan（free、pro、business 或 enterprise）、plan_events（套餐的每月事件额度）、subscription_status（none、trialing、active、past_due、paused 或 canceled）、role（调用者在其中的角色）和 created_at。完整的计费详情请使用 billing_get，本月的用量请使用 billing_usage。任何成员都可以读取。

权限： member

curl https://privatusanalytics.com/workspaces/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

更改工作区的名称、默认时区或默认货币，只更改您发送的输入。timezone 是 Europe/Berlin 这样的 IANA 名称，currency 是 3 位 ISO 4217 代码。这些是新站点的默认值，不会更改现有站点（请使用 sites_update 更改它们）。需要 workspace.manage。返回该工作区（见 workspaces_get）。

权限： workspace.manage

curl -X PATCH https://privatusanalytics.com/workspaces/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

消息会通过电子邮件发送给团队，并附上您的账户、工作区和套餐详情。回复和回执会发送到您的账户邮箱。每天最多 10 条消息。

权限： member

curl -X POST https://privatusanalytics.com/help.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

在站点上创建一个固定尺寸的广告位。传入 size（常见尺寸，如 medium_rectangle 或 leaderboard），或以像素为单位的 width 和 height。key 是站点上的标签用来称呼它的名称，省略时由名称生成。随后用 ad_creatives_create 添加素材，并把 ad_placements_embed 返回的标签放到站点上。需要 content.write。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/experiments/ads.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除广告位及其素材和图片、广告实验及其结果，以及赞助商链接。之后站点上的标签将不显示任何内容。MCP 工具不会执行此操作，而是返回 human_only 和由人来删除的页面。需要 content.write。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/experiments/ads/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

加载器脚本（每个页面一次）和此广告位的占位元素，以 html 形式供粘贴。加载器运行前，占位元素会保持其尺寸。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/experiments/ads/:id/embed.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

每个广告位的 key、尺寸、素材数量，以及近 30 天的统计（展示、可见展示、点击和 ctr，即每次可见展示的点击率）。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/experiments/ads.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

广告位、其素材在所选周期（7d、30d 或 90d）内的统计，以及广告位的每日数据。humans_only 只保留机器人评分判定为可能是真人的数据（Pro 及以上）。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/experiments/ads/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

修改名称、key、尺寸或标签文字。只有传入的字段会更改。新的 key 需要在站点上使用新的标签。需要 content.write。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/experiments/ads/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

添加一张符合广告位比例的图片（不小于其尺寸，使用两倍尺寸最清晰）和点击后的跳转地址。图片可作为 multipart 文件发送，或用 image_url 让我们下载。图片在后台处理，请轮询 ad_creatives_get，直到 state 为 ready。排期、设备和页面需要 Pro 及以上。需要 content.write。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/experiments/ads/:ad_placement_id/creatives.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除素材及其图片。有实验正在比较的素材无法删除，请改为关闭它。MCP 工具不会执行此操作，而是返回 human_only 和由人来删除的页面。需要 content.write。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/experiments/ads/:ad_placement_id/creatives/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

素材在图片生成之前为 processing，之后为 ready（或 failed，原因见 error）。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/experiments/ads/:ad_placement_id/creatives/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

修改链接、权重、排期或定向，将其关闭（active 设为 false）或替换图片。只有传入的字段会更改。新图片处理完成后会替换旧图片。需要 content.write。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/experiments/ads/:ad_placement_id/creatives/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

来自真实访客的核心网页指标报告。返回 period、metric、sample_rate、scorecard、trend 和 breakdowns。scorecard 对 LCP、INP、CLS、FCP 和 TTFB 各有一行，包含 p75（第 75 百分位，单位为毫秒，CLS 除外，它是无单位的分数）、samples、rating（good、needs_improvement 或 poor，没有数据时为 null）、good、needs_improvement 和 poor（占样本的百分比）、previous_p75、change（相对上一时间段的百分比，未知时为 null）和 thresholds [good 上限, poor 上限]。trend 是所选指标的每日 p75，格式为 {date, p75, samples}。breakdowns 包含 page、device、browser 和 country，每项最多 limit 行（默认 10，最大 100）所选指标，格式为 {value, p75, samples, rating, slow_share, poor}，最差且最繁忙的在前。metric 请恰好选择大写的 LCP、INP、CLS、FCP 或 TTFB 之一（默认 LCP）。sample_rate 是上报核心网页指标的访问所占比例，因此计数是样本而不是全部访问。接受共享的 period、compare、filters 和 segment 输入。单个页面的指标请使用 pages_detail。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/performance.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

通过邮件邀请一个或多个人加入工作区，并向每人发送带有链接的邀请邮件，链接有效期为 14 天。emails 是最多 50 个地址的列表（在应用表单中，用逗号、空格或分号分隔的字符串也可以），已是成员的地址会被跳过，但如果全部都是成员则会报错。邀请已有待处理邀请的地址会替换该邀请并发送新邮件。role 是 members_list 中的角色之一（默认 viewer，不能邀请 owner）。将 role 设为 custom 并配合 custom_role_id（来自 roles_list 的 id，Business 套餐）。默认情况下访问范围涵盖所有站点，包括未来的站点。若要限制访问，请将 all_sites 设为 false，并以公开站点 ID（pa_...）列出 site_ids。待处理的邀请会计入套餐的成员数量上限（Free 允许 3 名成员），超出上限时调用会失败。邀请邮件有频率限制。您不能授予比自己权限或站点更多的角色。需要 members.manage。返回已创建的邀请（字段见 invitations_list）。

权限： members.manage · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/invitations.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

撤销一个待处理的邀请，使其链接失效，并释放它占用的席位。删除无法撤销，请用 invitations_create 重新邀请对方。id（uuid）来自 invitations_list。仅限部分站点的调用者只能撤销所授予站点不超出其自身站点的邀请。需要 members.manage。返回已撤销的邀请。

权限： members.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/invitations/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出工作区待处理的团队邀请，按时间从新到旧排序并分页。已接受和已撤销的邀请不会列出（已加入的人请使用 members_list），已过期的会保留到被替换或撤销为止。需要 members.manage。仅限部分站点的调用者只能看到其权限范围内的邀请。每一项包含 id（uuid，供 invitations_delete 使用）、email、role、custom_role（role 为 custom 时是自定义角色的名称，否则为 null）、all_sites、site_ids（公开站点 ID pa_...，all_sites 为 true 时为空）、invited_by（邀请人的邮箱）、expires_at 和 created_at。

权限： members.manage

curl https://privatusanalytics.com/workspaces/:workspace_id/invitations.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

从工作区中移除一名成员，或在 id 是调用者自己的成员资格时让调用者退出。此操作立即生效且无法撤销，该成员会失去访问权限，其在此工作区的 API 令牌会被撤销，任何 SCIM 关联也会被移除。其备注和过往的审计条目会保留。所有者不能被移除或退出，请先通过 ownership_transfers_create 转让所有权。移除他人需要 members.manage，且您不能移除权限或站点比您更多的人。退出不需要权限，但权限或站点受限的令牌不能用于退出。之后可以用 invitations_create 再次邀请该成员。id（成员资格 uuid）来自 members_list。返回已移除的成员。

权限： member · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/members/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

按加入顺序列出工作区的成员并分页。用 query 按姓名或邮箱搜索（部分匹配，不区分大小写），用 role 按角色筛选。待处理的邀请不包括在内（请使用 invitations_list）。每位成员包含 id（成员资格 uuid，供 members_update、members_delete 和 ownership_transfers_create 使用）、email、name（可为空）、role、custom_role（名称，除非 role 为 custom 否则为 null）、custom_role_id、all_sites、include_future_sites、site_ids（公开站点 ID pa_...，all_sites 为 true 时为空）、two_factor（成员是否有验证器应用或通行密钥）、last_active_at（可为空）和 created_at。仅限部分站点的调用者只能看到其权限范围内的成员。

权限： member

curl https://privatusanalytics.com/workspaces/:workspace_id/members.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

更改工作区中某位成员的角色和/或站点访问权限。只有您发送的输入会被更改。要更改角色，请发送 role（admin、editor、analyst、viewer 或 billing，在 Business 套餐上还可用 custom 并附带来自 roles_list 的 custom_role_id）。所有者的角色不能在这里更改，请改用 ownership_transfers_create，您也不能编辑自己的成员资格或职级高于您的人。要限制站点，请发送 all_sites 为 false 并附带 site_ids（公开站点 ID pa_...），并加上 include_future_sites 为 true 以同时授予日后创建的站点。发送 all_sites 为 true 可授予所有站点的访问权限。对目前拥有所有站点的成员，发送不带 all_sites 为 false 的 site_ids 列表会报错。您不能授予比自己更多的权限或站点。需要 members.manage。id 来自 members_list。返回更新后的成员。

权限： members.manage · 仅限 HTTP（不是 MCP 工具）

curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/members/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

将工作区的所有权转让给另一名成员，并将调用者降级为 admin，这很难撤销，因为只有新所有者才能转回。只有当前所有者可以调用，且令牌不能限制在特定站点或权限上。membership_id 是来自 members_list 的新所有者的成员资格 uuid（不是用户 ID 或邮箱），该人必须已是成员，否则请先邀请。新所有者获得 owner 角色并可访问所有站点，owner 角色不能通过 members_update 授予。Free 工作区不能转让给已拥有另一个 Free 工作区的人。计费随工作区保留。调用此接口的令牌需要 members.manage。返回新所有者的成员记录。

权限： member · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/ownership_transfer.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

来自 Google Search Console 和 Bing Webmaster 的搜索表现，并与站点自己的落地页指标关联。选择 provider：all（默认）会将所有已连接的搜索引擎合并计算，排名按展示次数加权，国家/地区和设备仅来自 Google，也可以只选 google 或 bing，并使用常用的 period 或自定义的 from 和 to。limit（1 到 100，默认 25）限制每个表的行数。结果包含 period、provider、connection（所选搜索引擎的 property、status、last_synced_at，未连接或 provider 为 all 时为 null）、connections（每个已连接的搜索引擎，含 provider、property、status 和 last_synced_at）、latest_date（有数据的最新一天）、delayed（范围超过 latest_date 时为 true）、totals 和 series（按天），均含 clicks、impressions、ctr（百分比而非小数，保留 2 位小数）和 position（平均排名，1 为最佳，未知时为 null）、query、page、country 和 device 的 breakdowns（value 加上相同的四项指标的行）、landing_pages（热门页面，含 visits、百分比形式的 bounce_rate 和 conversion_rate，以及 conversions）以及 opportunities（low_ctr_queries，即至少有 100 次展示且 CTR 低于 2% 的查询，以及 striking_distance 页面，即平均排名在 8 到 20 之间）。country 值与服务商报告的一致。访客数据请使用 stats_breakdown，点击之前发生的情况请使用本工具。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/search.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

断开站点与某个搜索服务商（google 或 bing）的连接，并永久删除该服务商已导入的搜索数据。此操作无法撤销。一旦没有站点使用，Google 授权也会被移除。如果未连接该服务商则会失败。返回已移除的连接。需要 sites.manage。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/search/connections/:provider.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

为已连接的服务商（google 为默认，或 bing）将一次立即的搜索数据导入加入队列，而不是等待常规计划。它会立即返回（HTTP 202）并附带连接信息，导入在后台运行。请轮询 search_report 并观察 connection.last_synced_at。搜索引擎的报告有几天的延迟，因此即使同步之后，最新几天仍然为空。如果未连接该服务商则会失败。需要 sites.manage。

权限： sites.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/search/sync.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

添加一个接收每日原始事件的数据仓库目的地（仅限 Business 套餐）。每天 UTC 02:00 会上传前一个 UTC 日的数据，首次运行在下一个 UTC 02:00，失败的运行会在一小时后重试。必须提供 kind，它决定必需的设置。s3（通过 endpoint 也可用于 GCS、R2 和 MinIO）需要 bucket、access_key_id 和 secret_access_key，可选 region、prefix 和 endpoint（仅限 https 公共主机）。bigquery 需要 service_account_json、dataset 和 table，可选 project_id。snowflake 需要 account、user、private_key（PEM RSA）、database、schema 和 table，可选 warehouse 和 role。azure 需要 sas_url（具有写入权限的 https blob 容器 SAS 链接），可选 prefix。机密项（secret_access_key、service_account_json、private_key、sas_url）只写，绝不返回。site_ids 限制站点（pa_... ID），为空表示每个站点，仅限部分站点的成员或令牌必须指明这些站点。事件属性只有在标记为可安全导出时才会发送（见 event_properties_list）。需要 workspace.manage 权限。返回目的地，包含 id（whd_...）、已遮盖的 target 和 configured（已填写设置的名称）。

权限： workspace.manage · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/warehouses.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

删除一个数据仓库目的地，不再发送任何内容。已经上传的数据会保留在您的存储桶或数据仓库中，此操作无法撤销，不过您可以重新添加该目的地（历史数据不会自动重新发送）。仍在排队的手动同步不会被召回。id 来自 warehouse_destinations_list。需要 workspace.manage 权限。返回已删除的目的地。

权限： workspace.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/warehouses/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出工作区的数据仓库目的地，按名称排序，也可只列出某一种 kind（s3、bigquery、snowflake 或 azure）。仅限部分站点的成员或令牌只能看到其站点全部属于自己的目的地，发送所有站点的目的地对他们是隐藏的。通过 page 和 per_page 分页（最大 100）。每一项的字段如 warehouse_destinations_get 所述。需要来自 workspaces_list 的 workspace_id 和 workspace.manage 权限。

权限： workspace.manage

curl https://privatusanalytics.com/workspaces/:workspace_id/warehouses.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回一个不含凭据的数据仓库目的地。字段包括 id（whd_...）、kind（s3、bigquery、snowflake 或 azure）、name、target（已遮盖的摘要，如 s3://bucket/prefix）、configured（已填写设置的名称，机密项只显示名称）、site_ids（为空表示每个站点）、schedule（daily）、schema_version（发送的行结构）、last_run_at、next_run_at、last_error（上次运行成功时为 null）和 created_at。id 来自 warehouse_destinations_list。在 warehouse_destinations_sync 之后查看 last_error，了解同步进行得如何。

权限： workspace.manage

curl https://privatusanalytics.com/warehouses/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

在每日计划之外，将某个 UTC 日的原始事件的一次立即上传加入队列。仅限 Business 套餐。date（YYYY-MM-DD）必须早于 UTC 的今天，默认为昨天。它会上传该目的地所有站点在那一天的数据，因此请避免同步已发送过的日期，手动同步按每个工作区每小时 30 次进行频率限制。调用会立即返回 202 和目的地，上传在后台运行。请轮询 warehouse_destinations_get 并读取 last_run_at 和 last_error 查看结果。id 来自 warehouse_destinations_list。需要 workspace.manage 权限。

权限： workspace.manage · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/warehouses/:id/sync.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

修改数据仓库目的地（仅限 Business 套餐）。只有您发送的输入会被更改，kind 不能更改。空的机密项会保留已存储的值，因此无需再次发送凭据即可编辑其他设置。设置会按目的地的 kind 验证，与 warehouse_destinations_create 相同。发送 site_ids 会替换站点列表。当目标改变时（另一个存储桶、数据集、表、数据库或类似项），未完成日期的进度会重新开始，因此这些日期会重新发送到新的位置。id 来自 warehouse_destinations_list。需要 workspace.manage 权限。返回更新后的目的地。

权限： workspace.manage · 仅限 HTTP（不是 MCP 工具）

curl -X PATCH https://privatusanalytics.com/warehouses/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/embed/ads/e.json \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/embed/ads/:site.json

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/api/overlay.json \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/api/logs.json \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/api/event.json \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/api/experiment.json

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/js/exp/:site.json

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/api/survey.json \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/api/surveys.json

返回所有 API 操作的完整目录，这同时也是所有 MCP 工具。用它来发现有哪些工具或端点，以及它们确切需要什么。每一项包含 tool_name、summary、description（可为空）、group、verb（HTTP 方法）、path（带占位符的模板）、permission（成员或令牌所需的权限，公开工具可为空）、input_schema（输入的 JSON Schema）和 response_schema（响应的 JSON Schema）。响应很大。对于您已知道的单个工具，建议使用文档页面（docs_search）。docs_openapi 以 OpenAPI 文档的形式返回相同的信息。公开，无需身份验证。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/docs/api.json

列出所有文档页面，包含 title、description、path（如 /docs/api/authentication）、section，不含正文。用它浏览现有内容。按主题查找页面请使用 docs_search，阅读某一页请使用 docs_get 并传入其 section 和 page。通过 page 和 per_page 分页（最大 100）。公开，无需身份验证。

权限： public

curl https://privatusanalytics.com/docs.json

返回描述整个公开 API 的 OpenAPI 3 文档，为原始 JSON（不包在 data 字段中）。需要用于代码生成的机器可读规范时使用它。若要获取可浏览的操作列表及其输入和响应结构，docs_api 更易阅读。它描述的是与 MCP 工具相同的那些操作。公开，无需身份验证。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/openapi.json

搜索服务器上的文档并返回排序后的页面。在猜测之前，用它来了解某个功能的工作方式。q 会被拆分为最多 10 个词，每个词都必须出现在页面中，标题和小标题的匹配排名最高。q 为空时按目录顺序返回所有页面。给出 q 时 limit 默认为 20，最大为 100。每个结果包含 title、path（其中的 section 和 page 部分可用于 docs_get）、section、headings（id 和 text 的列表，可用作标题锚点）、excerpt 和 score（q 为空时为 null）。搜索请求所用的语言，默认为英文。公开，无需身份验证。

权限： public

curl https://privatusanalytics.com/docs/search.json

section 和 page 来自页面路径 /docs/<section>/<page>。使用页面 "index" 获取章节概览。

权限： public

curl https://privatusanalytics.com/docs/:section/:page.json

报告站点蜜罐页面上的访问记录。蜜罐页面是只能通过隐藏链接到达的页面，按应用中高级机器人检测页面的指引设置。这些访问都是机器人，因此绝不会成为浏览量或访问，也不会出现在 stats_overview 或 stats_breakdown 中。用 period 选择范围（7d、30d（默认）、90d 或 12mo）。记录保留 12 个月。结果包含 period、from（范围的起点）、has_data（在第一条记录出现之前为 false）、totals（hits、不同页面数、automated（跟踪器检测到自动化浏览器的 hits）和 no_interaction（没有指针、按键或触摸输入的 hits））、pages（最多 50 行，含 path、hits 和 last_hit_at）、reasons（按标准机器人过滤结果统计的 hits：known_bot、automation、datacenter、empty_user_agent、referrer_spam，或者对于过滤器本会当作真人计数的记录为 undetected）和 recent（最近 50 条记录，含 occurred_at、path、country、browser、device、bot_reason、automation 和 interacted）。记录中不保留 IP 地址或 User-Agent，只保留它们的密钥哈希值，无法识别任何人，且这些哈希值绝不会返回。需要 analytics.read 以及 Business 或 Enterprise 套餐（否则返回 402 plan_limit）。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/bot-detection.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

添加一个与某个站点关联的正常运行时间检查。若是不属于任何站点的检查，请使用 workspace_uptime_checks_create。kind 决定检查目标。http 检查 url 的状态码，keyword 检查 url 的响应正文是否包含 keyword，tcp 连接 host 和 port，dns 检查 host 能否解析。其他类型不适用的字段会被忽略。对于 http 检查，url 默认为站点首页。expected_status（100 到 599，默认 200）、http_method（GET 或 HEAD）和 timeout_seconds（1 到 30，默认 20）适用于 http 和 keyword 检查。interval_seconds 是探测之间的间隔，必须不小于套餐的最小值（Free 为 300，Pro 为 60，Business 为 30），默认为 300，或在最小值更高时取最小值。public 为 true 时该检查可以显示在状态页上。私有和内部地址会被拒绝，套餐限制每个工作区的检查数量（Free 为 3，Pro 为 20，Business 为 100）。第一次探测会在片刻之内运行，status 初始为 pending。需要 uptime.manage 权限。返回带 id（upc_...）的检查。

权限： uptime.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/uptime.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一个正常运行时间检查及其结果和事故历史，并将其从显示它的所有状态页中移除。此操作无法撤销。若只想停止探测但保留历史，请使用 uptime_checks_pause。id 来自 uptime_checks_list。需要 uptime.manage 权限。返回已删除的检查。

权限： uptime.manage

curl -X DELETE https://privatusanalytics.com/uptime/checks/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出某个站点的正常运行时间检查，包括探测该站点域名或其子域名的工作区级检查。按名称排序。要查看工作区中的所有检查，请使用 workspace_uptime_checks_list。可用 status（up、down、pending 或 paused）或 query（name、url 或 host 的一部分）筛选。通过 page 和 per_page 分页（最大 100）。每个检查包含 id（upc_...）、workspace_id、site_id（工作区级检查为 null）、name、kind、url、host、port、keyword、expected_status、http_method、interval_seconds、timeout_seconds、status（up、down、pending 或 paused）、enabled、public、last_checked_at、next_check_at、last_response_ms（毫秒）、ssl_expires_at、ssl_issuer、domain_expires_at 和 created_at。查看正常运行率和事故请使用 uptime_checks_get。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/uptime.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

暂停一个正常运行时间检查，使其不再被探测。任何未结事故会被立即关闭，暂停期间不会发送宕机或恢复警报。历史会保留，其状态显示为 paused。可用 uptime_checks_resume 恢复。id 来自 uptime_checks_list。需要 uptime.manage 权限。返回该检查。

权限： uptime.manage

curl -X POST https://privatusanalytics.com/uptime/checks/:id/pause.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

恢复已暂停的正常运行时间检查。它会在下一个调度周期被探测，在第一个结果到来之前其状态为 pending。id 来自 uptime_checks_list。需要 uptime.manage 权限。返回该检查。

权限： uptime.manage

curl -X POST https://privatusanalytics.com/uptime/checks/:id/resume.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回一个正常运行时间检查及其历史，而不仅仅是设置。为响应时间图表选择 range（24h 为默认，或 7d、30d）。响应包含 check（设置和实时状态，见 uptime_checks_list）、uptime（24h、7d 和 30d 的百分比，第一次探测运行之前为 null）、range、response_times（单位为小时或天，标签为 ISO 8601 时间，以及每个位置的平均响应时间序列，单位毫秒，缺口为 null）和 incidents（最近 50 条，含 started_at、仍未解决时 resolved_at 为 null、duration_seconds、cause 和 failed_locations）。只有成功的探测才计入响应时间。id 来自 uptime_checks_list。

权限： analytics.read

curl https://privatusanalytics.com/uptime/checks/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

修改一个正常运行时间检查。只有您发送的输入会被更改。规则和限制与 uptime_checks_create 相同（间隔必须不小于套餐的最小值，私有地址会被拒绝）。更改 kind 会清除不再适用的目标字段。更改 interval_seconds 会立即安排下一次探测。id 来自 uptime_checks_list。需要 uptime.manage 权限。返回更新后的检查。

权限： uptime.manage

curl -X PATCH https://privatusanalytics.com/uptime/checks/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/uptime/probes.json

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/uptime/probes/results.json \
  -H "Content-Type: application/json" -d '{…}'

添加一个属于整个工作区而不是某个站点的正常运行时间检查。若要把检查关联到站点，请使用 uptime_checks_create。输入、套餐限制和规则相同，请参见 uptime_checks_create。kind 为 http、keyword、tcp 或 dns，并决定 url、keyword、host 和 port 中哪些适用。由于没有站点，http 检查需要明确的 url。仅限部分站点的调用者不能创建工作区级检查。需要来自 workspaces_list 的 workspace_id 和 uptime.manage 权限。返回带 id（upc_...）且 site_id 为 null 的检查。

权限： uptime.manage

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/uptime.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出工作区的每个正常运行时间检查，包括不关联任何站点的检查，按名称排序。仅限部分站点的调用者只能看到这些站点的检查。要查看单个站点的检查，请使用 uptime_checks_list。可用 status（up、down、pending 或 paused）或 query（name、url 或 host 的一部分）筛选。通过 page 和 per_page 分页（最大 100）。每一项的字段如 uptime_checks_list 所述。需要来自 workspaces_list 的 workspace_id。

权限： analytics.read

curl https://privatusanalytics.com/workspaces/:workspace_id/uptime.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

向站点的拦截或允许列表之一添加一个模式。list 为 hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events 之一。pattern 使用 * 作为通配符且匹配不区分大小写，例如 /admin/*、主机名、spam.example 这样的来源主机、两位的国家或地区代码（以大写存储）、由于 User-Agent 已被精简而采用的浏览器名称加主版本（例如 Chrome 120），或自定义事件名称。ip_ranges 接受 IPv4 或 IPv6 地址或 CIDR（203.0.113.0/24），必须有效。同一个模式在每个列表中只能存在一次，一个站点最多可有 500 条规则。该列表是拦截还是允许匹配项取决于其模式，默认为 block，可通过 sites_update 更改。匹配的点击会在采集时被丢弃且不存储，规则会在几分钟内仅对新的点击生效。需要 sites.manage。需要 Pro 或更高套餐（否则返回 402 plan_limit）。

权限： sites.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/traffic_rules.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

删除一条流量规则，通过 traffic_rules_list 中的 id 查找。它此前丢弃的点击从此时起会重新计入，已被丢弃的点击则永久丢失。请注意，删除允许模式列表中的最后一个模式会使该列表停止过滤。返回已删除的规则。需要 sites.manage。

权限： sites.manage

curl -X DELETE https://privatusanalytics.com/sites/:site_id/traffic_rules/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出站点的流量规则，即在采集时应用、用于决定哪些点击计数的拦截或允许列表。每条规则包含 id（用于更新和删除的 UUID）、list（hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events）、pattern、label（可选的备注）、mode（block 或 allow，即整个列表的模式）和 created_at。在 block 模式下，匹配列表中任一模式的点击会被丢弃，在 allow 模式下，一个都不匹配的点击会被丢弃，空列表不会过滤任何内容。可用 list 筛选。列表的模式不在这里设置，而是通过 sites_update 使用 traffic_rule_modes 设置。使用 traffic_rules_test 检查一次示例点击。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/traffic_rules.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

试运行，告诉您一次示例点击在站点当前的流量规则下是否会被计数。不会存储任何内容。可发送 url（完整的页面 URL，会检查其主机和路径）、referrer（URL 或主机名）、country（两位代码）、ip（对照 ip_ranges 检查，绝不存储）、user_agent（完整的 User-Agent 字符串，会被精简为浏览器和主版本）和 event（自定义事件名称）中的任意项。您省略的值不会被检查。结果包含 counted（该点击会被记录时为 true）、blocked_by（丢弃它的列表，或 null）、mode（该列表的 block 或 allow，或 null）和 values（被检查的规范化值）。规则是实时读取的，因此新规则会立即体现。需要 analytics.read。需要 Pro 或更高套餐（否则返回 402 plan_limit）。

权限： analytics.read

curl -X POST https://privatusanalytics.com/sites/:site_id/traffic_rules/test.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

更改流量规则的模式或标签，通过 traffic_rules_list 中的 id 查找。只有您发送的输入会被更改。list 不能更改，若要移到另一个列表，请删除后重新创建规则。pattern 必须对其所在列表保持有效（ip_ranges 为 CIDR）且在其中唯一。发送空的 label 可将其清除。仅适用于新的点击。需要 sites.manage。需要 Pro 或更高套餐（否则返回 402 plan_limit）。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:site_id/traffic_rules/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

在列表末尾添加一条自定义渠道规则，因此它在所有现有规则之后运行，只有在没有规则匹配时才会应用内置分类。channel 是要分配的名称（最多 32 个字符，例如 Partners）。conditions 是由对象组成的非空列表，每个对象包含 field（referrer_host、utm_source、utm_medium、utm_campaign、ref 或 path）、operator（is、contains、starts_with 或 regex）和 value。所有条件都必须匹配，规则才会生效，匹配不区分大小写。值为空的条件会被丢弃，没有任何条件的规则会被拒绝。无法编译的正则表达式会被拒绝。规则会在几分钟内应用于新的访问，不会更改历史数据。使用 channel_rules_move 调整顺序，使用 channel_rules_preview 测试。需要 sites.manage。

权限： sites.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/channel_rules.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

删除一条自定义渠道规则，通过 channel_rules_list 中的 id 查找。已被它归类的访问保留其渠道，新的访问会落到下一条匹配的规则或内置分类。其余规则保持其顺序。返回已删除的规则。需要 sites.manage。

权限： sites.manage

curl -X DELETE https://privatusanalytics.com/sites/:site_id/channel_rules/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

按评估顺序（position 1 在前）列出站点的自定义渠道规则。规则会自上而下对每次新访问运行，第一条所有条件都匹配的规则决定渠道。没有匹配任何规则的访问会得到内置渠道（direct、organic_search、paid_search、email 等）。每条规则包含 id（UUID）、channel（它分配的名称）、position（从 1 开始）、conditions（field、operator 和 value 对象的列表，必须全部匹配）和 created_at。规则只影响规则存在之后记录的访问，绝不会改写旧数据。使用 channel_rules_preview 测试一次示例访问。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/channel_rules.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

在评估顺序中移动一条渠道规则，因为第一条匹配的规则胜出，顺序决定访问得到哪个渠道。direction 为 up 或 down（移动一位），或 top 或 bottom（移到两端）。已在边缘的规则保持不动且不会报错。位置会重新编号为 1 到 n，并返回带有新位置的更新后规则。请先使用 channel_rules_list 查看当前顺序。需要 sites.manage。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:site_id/channel_rules/:id/move.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

试运行，告诉您一次示例访问按站点当前规则会得到哪个渠道。不会存储任何内容。可发送 referrer（URL 或纯主机名，会忽略 www 和 m 前缀）、utm_source、utm_medium、utm_campaign、ref、path（落地路径，如 /pricing）和 paid_click（URL 带有 gclid 之类的点击 ID 时为 true）中的任意项。结果包含 channel（胜出的渠道名称）、custom_rule（由自定义规则决定时为 true，由内置分类决定时为 false）和 referrer_host（用于匹配的清理后主机名）。来自站点自身域名的来源会被视为内部来源。在 channel_rules_create 或 channel_rules_move 之后使用它来确认效果。需要 analytics.read。

权限： analytics.read

curl -X POST https://privatusanalytics.com/sites/:site_id/channel_rules/preview.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

修改一条自定义渠道规则，通过 channel_rules_list 中的 id 查找。发送 channel 可重命名它分配的渠道，发送 conditions 可替换整个条件列表（列表是被替换而不是合并，因此请发送您想保留的每一个条件）。省略的输入保持不变。条件的字段、运算符和正则有效性的检查方式与 channel_rules_create 相同。更改仅适用于新的访问。要更改顺序请使用 channel_rules_move。需要 sites.manage。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:site_id/channel_rules/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

创建一个漏斗，即访问依次经过的一系列步骤，按每次访问衡量。传入 name 和 steps，后者是 {type, value, match, name} 的有序列表。type 为 page、event 或 goal。value 对 page 步骤是路径（例如 /pricing），对 event 步骤是自定义事件名称，对 goal 步骤是目标 ID（goal_...，来自 goals_list）。match 仅用于 page 步骤，取值为 exact、prefix、glob（* 通配符）或 regex，当 value 含有 * 时默认为 glob，否则为 exact。name 是可选的标签。value 为空的步骤会被丢弃。order_mode 为 strict（每一步都必须在上一步之后，默认）或 any（步骤顺序不限）。window 为 visit（默认）或 day，由于不存储访客 ID，两者都在单次访问内衡量。适用套餐限制。Free 每个站点允许 3 个漏斗和 5 个步骤，Pro 允许 10 个步骤，Business 允许 20 个，漏斗至少需要 2 个步骤。返回带 id（fun_...）的漏斗。使用 funnels_get 读取结果。需要 content.write 权限。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/funnels.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一个漏斗定义。不会触及任何分析数据，但漏斗及其设置无法恢复，也无法撤销。返回已删除的漏斗。ID（fun_...）来自 funnels_list。若要修改漏斗请改用 funnels_update。需要 content.write 权限。

权限： content.write

curl -X DELETE https://privatusanalytics.com/sites/:site_id/funnels/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出某个站点的漏斗及其在该时间段内的核心结果，按名称排序。每个漏斗包含 id（fun_...）、name、steps、order_mode、window 和 stats {entered, completed, conversion_rate}，其中 entered 是到达第 1 步的访问数，completed 是到达最后一步的访问数，conversion_rate 是百分比（0 到 100）。通过 page 和 per_page 分页（最大 100，默认 25）。接受共享的 period 和 filters 输入。需要逐步详情请使用 funnels_get，添加漏斗请使用 funnels_create。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/funnels.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

某个漏斗在一个时间段内的转化报告。返回 period、funnel_id、name、order_mode、window、steps、overall_conversion_rate、breakdown，带 compare 时还有 comparison。每个步骤包含 index（从 1 开始）、name、type、value、match、count（到达该步骤的访问数）、step_conversion_rate（占上一步的百分比）、overall_conversion_rate（占第 1 步的百分比）、dropoff 和 dropoff_rate（在此步骤之后离开的访问）、median_seconds_from_previous（第 1 步为 null）和 next_pages（流失访问接下来访问的前 5 个页面，离开的用 (exit) 表示）。比率均为 0 到 100 的百分比。将 breakdown 设为 channel、device、country、utm_campaign、utm_source、browser 或 os，可获得每个值的整体转化（前 20 个）。comparison 包含另一个时间段的计数、overall_conversion_rate 和 change（百分比，之前的比率为 0 时为 null）。页面筛选在这里会被忽略，因为它们会截断访问，请改用 page 步骤。接受共享的 period、compare、filters 和 segment 输入。ID 来自 funnels_list。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/funnels/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

修改漏斗。只有您发送的输入会被更改。发送 steps 会替换整个步骤列表，因此请按顺序发送每一个步骤（格式和步骤上限与 funnels_create 相同，Free 允许 5 个步骤，Pro 10 个，Business 20 个，goal 步骤必须指定本站点的目标）。您也可以更改 name、order_mode（strict 或 any）和 window（visit 或 day）。结果在读取时根据定义计算，因此更改漏斗会立即应用于全部历史，之前显示过的历史数字会有所不同。返回漏斗。ID 来自 funnels_list。需要 content.write 权限。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/funnels/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

断开站点与 Cloudflare 的连接。这会删除已存储的 API 令牌以及从 Cloudflare 导入的所有爬虫记录，且无法撤销。来自已传送服务器日志的记录会保留。该令牌在您的 Cloudflare 账户中仍然存在，直到您在那里删除它。如果站点没有连接则会失败。返回已移除的连接。需要 sites.manage。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/crawlers/connection.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

为已连接的站点将一次立即的 Cloudflare 导入加入队列，而不是等待常规计划。它会立即返回（HTTP 202）并附带连接信息，导入在后台运行。轮询 crawlers_report 并观察 cloudflare.last_synced_at，即可知道何时完成。如果站点没有 Cloudflare 连接则会失败。需要 sites.manage。

权限： sites.manage

curl -X POST https://privatusanalytics.com/sites/:site_id/crawlers/sync.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

根据已传送的服务器日志和 Cloudflare 导入的数据，报告哪些 AI、搜索和 SEO 爬虫抓取了站点、频率如何以及抓取了哪些路径。这是爬虫流量而非访客流量，因此不会出现在 stats_breakdown 中。category 为 ai（默认）、search、seo、other 或 all，crawler 可缩小到某个具名机器人，如 GPTBot 或 ClaudeBot。用 period（默认 30d）或自定义的 from 和 to 选择范围。结果包含 period（from 和 to 为日期）、category、crawler、totals（hits、不同路径数、不同爬虫数）、categories（每个类别的 hits，忽略 category 筛选）、crawlers（最多 50 行，含 crawler、category、hits、paths）、series（每天的标签以及前 8 个爬虫的每日 hits）、top_paths（前 8 个爬虫各自被抓取最多的 10 个路径）、has_data（在出现任何 hits 之前为 false）和 cloudflare（含 zone、status 和 last_synced_at 的连接，或 null）。结果最多缓存 30 分钟，Cloudflare 变更后立即刷新除外。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/crawlers.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/status/:slug/confirm/:token.json

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/status/:slug.json

浏览器客户端会以 `cf-turnstile-response` 发送 Cloudflare Turnstile 令牌。使用 API 令牌的请求无需发送。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/status/:slug/subscribers.json \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/status/:slug/unsubscribe/:token.json \
  -H "Content-Type: application/json" -d '{…}'

在状态页上发布事故更新，默认还会向已确认的订阅者发送邮件。用它来公布或更新事故，要推进已有的事故（例如改为 resolved），请使用 status_page_posts_update 而不是创建新帖子。title 为必填（最多 200 个字符）。status 为 investigating（默认）、identified、monitoring 或 resolved 之一。body 是纯文本（最多 10,000 个字符），posted_at 是 ISO 8601 时间，默认为当前时间，notify（默认 true）控制是否发送邮件。只有已发布的页面才会发送邮件，并按页面进行频率限制，超过限制时帖子仍会发布，但不会给任何人发邮件。status_page_id 来自 status_pages_list。需要 uptime.manage 权限。返回帖子，包含 id（spp_...）、title、body、status、posted_at 和 updated_at。

权限： uptime.manage

curl -X POST https://privatusanalytics.com/status_pages/:status_page_id/posts.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除状态页上的一篇事故帖子。它会立即从公开页面消失，且无法撤销。不会发送邮件。id 来自 status_page_posts_list。需要 uptime.manage 权限。返回已删除的帖子。

权限： uptime.manage

curl -X DELETE https://privatusanalytics.com/status_pages/:status_page_id/posts/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出状态页的事故帖子，按 posted_at 从新到旧排序。用它查找帖子 ID 或查看事故历史。可按 status（investigating、identified、monitoring 或 resolved）筛选。通过 page 和 per_page 分页（最大 100）。每篇帖子包含 id（spp_...）、title、body（为空时为 null）、status、posted_at 和 updated_at。status_page_id 来自 status_pages_list。

权限： analytics.read

curl https://privatusanalytics.com/status_pages/:status_page_id/posts.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

编辑事故帖子。只有您发送的输入会被更改，因此只发送 status 即可解决事故。只有当 status 确实改变且 notify 不为 false（默认 true）时才会给订阅者发邮件。仅编辑 title 或 body 不会发送邮件。邮件会发送给已发布页面的已确认订阅者，并按页面进行频率限制。有效的 status 值为 investigating、identified、monitoring 和 resolved。id 来自 status_page_posts_list。需要 uptime.manage 权限。返回更新后的帖子。

权限： uptime.manage

curl -X PATCH https://privatusanalytics.com/status_pages/:status_page_id/posts/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

从状态页移除一位邮件订阅者，使其不再收到事故和正常运行时间邮件。此操作无法撤销，但对方可以在公开页面重新订阅。id 是来自 status_page_subscribers_list 的订阅者 ID（普通 UUID，不是带前缀的 ID）。需要 uptime.manage 权限。返回已移除的订阅者。

权限： uptime.manage

curl -X DELETE https://privatusanalytics.com/status_pages/:status_page_id/subscribers/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出状态页的邮件订阅者，按邮箱排序。使用 confirmed 为 true 可只查看已确认其地址的人（只有他们会收到邮件），confirmed 为 false 则查看待确认的人。通过 page 和 per_page 分页（最大 100）。每一项包含 id（UUID，供 status_page_subscribers_delete 使用）、email、confirmed_at（待确认时为 null）和 created_at。status_page_id 来自 status_pages_list。需要 uptime.manage 权限，并会返回个人数据（邮箱地址）。需要 Business 或 Enterprise 套餐（否则返回 402 plan_limit）。

权限： uptime.manage

curl https://privatusanalytics.com/status_pages/:status_page_id/subscribers.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

为工作区创建公开的状态页，显示所选的正常运行时间检查、事故帖子和邮件订阅入口。name 为必填（最多 100 个字符）。slug（小写字母、数字和连字符，在所有工作区中唯一）默认由名称生成，页面位于 /status/<slug>。check_ids 列出要显示的正常运行时间检查（来自 uptime_checks_list 的 upc_... ID），且只接受以 public 为 true 创建的检查。published 默认为 true，因此页面会立即对所有人可见。可选的品牌设置包括 description（最多 2,000 个字符）、logo_url（必须是 https）、brand_color（十六进制，如 #06755b）和 custom_domain（您将 CNAME 指向应用的主机名，唯一）。之后用 status_page_posts_create 发布事故。需要 uptime.manage 权限。返回页面，包含 id（sp_...）、slug、check_ids 和 subscribers（已确认订阅者的数量）。套餐决定工作区可拥有多少个页面：Free 没有（402 plan_limit），Pro 为 1 个，Business 为 10 个。custom_domain 和邮件订阅者需要 Business 或 Enterprise 套餐。超出套餐数量的页面会被保留但处于下线状态。

权限： uptime.manage

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/status_pages.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一个状态页及其所有事故帖子和订阅者。公开页面及其自定义域名会立即停止工作，且此操作无法撤销。正常运行时间检查本身不会被删除。id 来自 status_pages_list。需要 uptime.manage 权限。返回已删除的页面。

权限： uptime.manage

curl -X DELETE https://privatusanalytics.com/status_pages/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出工作区的状态页，按名称排序。用 query 匹配名称或 slug 的一部分。当调用者仅限于部分站点时，只返回其检查全部属于这些站点的页面。通过 page 和 per_page 分页（最大 100）。每一项的字段如 status_pages_get 所述。需要来自 workspaces_list 的 workspace_id。

权限： analytics.read

curl https://privatusanalytics.com/workspaces/:workspace_id/status_pages.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回一个状态页及其设置。字段包括 id（sp_...）、workspace_id、name、slug、custom_domain（没有时为 null）、description、logo_url、brand_color、published、check_ids（页面上显示的正常运行时间检查 ID）、subscribers（已确认邮件订阅者的数量）和 created_at。其事故请使用 status_page_posts_list，订阅者请使用 status_page_subscribers_list。id 来自 status_pages_list。

权限： analytics.read

curl https://privatusanalytics.com/status_pages/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

修改状态页。只有您发送的输入会被更改，因此只发送 published 为 false 即可使页面下线，或发送 check_ids 来替换显示的检查（整个列表会被替换而不是合并）。输入及其限制与 status_pages_create 相同。将 custom_domain 发送为空字符串可移除自定义域名。只有 public 为 true 的检查才能显示，且仅限部分站点的调用者只能将这些站点的检查放到页面上。id 来自 status_pages_list。需要 uptime.manage 权限。返回更新后的页面。

权限： uptime.manage

curl -X PATCH https://privatusanalytics.com/status_pages/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

归档一个目标。已归档的目标会从报告中隐藏，不计入套餐的目标数量上限，并保留其定义，因此日后可用 goals_unarchive 恢复。不会删除任何数据。返回 archived 为 true 且设置了 archived_at 的目标。归档已归档的目标不会有任何效果。若要彻底移除请使用 goals_delete。需要 content.write 权限。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/goals/:id/archive.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

创建一个转化目标。目标是在读取报告时应用的定义，因此新目标会立即统计所有已有历史中匹配的事件。必填项为 name 和 kind。kind 决定适用哪些其他输入。page 需要 pattern（路径，例如 /thank-you，配合 match_type 为 exact、prefix、glob 或 regex），并可使用 hostname。event 需要 event_name，并可使用 conditions（属性测试，如 {key: plan, operator: is, value: pro}，必须全部匹配，运算符为 is、is_not、contains、gt、lt）。engagement 需要 pattern，加上 scroll_threshold（1 到 100 的百分比）和/或 time_threshold_seconds（满足任一条件即达成）。outbound 用 pattern 匹配链接域名（例如 stripe.com），download 用 pattern 匹配文件（例如 *.pdf）。value_mode 为 none（默认）、fixed（使用 fixed_value，即以站点货币表示的小数金额，如 49.5，按分存储为 fixed_value_minor）或 revenue（事件自带的收入）。count_mode 为 once_per_visit（默认）或 every。Free 工作区每个站点允许 10 个启用的目标，付费套餐不限。返回带 id（goal_...）的目标。需要 content.write 权限。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/goals.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一个目标定义。不会删除任何事件数据，但该目标会从报告中消失，指向它的漏斗步骤、路径和实验也会停止工作。无法撤销。若要隐藏目标并保留它，请使用 goals_archive。返回已删除的目标。ID（goal_...）来自 goals_list。需要 content.write 权限。

权限： content.write

curl -X DELETE https://privatusanalytics.com/sites/:site_id/goals/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

将一个目标的定义复制为新的启用目标。如果您发送了 name，副本就用这个名称，否则为原名称加上 (copy)。它计入套餐的目标数量上限（Free 每个站点 10 个启用的目标）。返回带新 id 的新目标。用它来创建目标的变体，再用 goals_update 修改。需要 content.write 权限。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/goals/:id/duplicate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出某个站点的目标及其在该时间段内的结果。每个目标包含定义（id goal_...、name、kind、match_type、pattern、hostname、event_name、conditions、scroll_threshold、time_threshold_seconds、value_mode、以分为单位的 fixed_value_minor、count_mode、archived、archived_at）以及 stats {completions, conversions, conversion_rate, value, change}。conversion_rate 是百分比（0 到 100），value 以最小货币单位（分）表示，change 是转化数相对上一时间段的变化百分比（之前的计数为 0 时为 null）。status 可筛选为 active（默认）、archived 或 all。通过 page 和 per_page 分页（最大 100，默认 25）。查看单个目标的完整报告请使用 goals_get。接受共享的 period、compare 和 filters 输入。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/goals.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

深入查看某个目标在一个时间段内的情况。返回 period、goal_id、goal（定义）、metrics、interval、series、breakdowns、journey，带 compare 时还有 comparison_period、comparison 和 change。metrics 包含 completions（每个匹配的事件）、conversions（至少有一次完成的访问）、conversion_rate（0 到 100 的百分比）和 value（最小货币单位，分）。conversion_rate 除以访问数，站点按此设置时则除以访客数。series 是每个时间段的 {date, completions, conversions, conversion_rate} 列表（设置 interval 可更改）。breakdowns 包含 channel、utm_campaign、entry_page、country 和 device 按转化数排名的前 10 项，每项格式为 {value, completions, conversions, conversion_rate}。journey 显示 converting_visits、median_seconds_to_convert、median_pages_before 和 pages_before（转化前查看的前 10 个页面，含 visits 和 share）。一次查看所有目标请使用 goals_list，多步骤流程请使用 funnels_get。接受共享的 period、compare、filters 和 segment 输入。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/goals/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

恢复已归档的目标，使其重新显示在报告中。它会再次计入套餐的目标数量上限（Free 每个站点 10 个启用的目标），因此站点已满时，调用会因套餐限制错误而失败。恢复未归档的目标不会有任何效果。返回 archived 为 false 的目标。ID 来自 status 为 archived 的 goals_list。需要 content.write 权限。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/goals/:id/unarchive.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

更改目标的定义。只有您发送的输入会被更改。新定义会立即应用于全部历史，因此过去的转化数字会改变。输入与 goals_create 相同，适用同样的组合，例如 event_name 和 conditions 只对事件目标有意义，scroll_threshold 和 time_threshold_seconds 只对互动目标有意义。fixed_value 是以站点货币表示的小数金额（按分存储）。发送 conditions 会替换所有现有条件。返回目标。ID 来自 goals_list。需要 content.write 权限。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/goals/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

私下反馈是在开启低评分路由的表单上、评分为 1 到 3 的回答（Business 及以上）。它绝不是客户评价，绝不公开，也不会被计数。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/forms/:form_id/feedback.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

为一条私下反馈设置 read_at，或在 read 为 false 时清除它。标记已读的回答会保留其首次被阅读的时间。不会向写下它的人发送任何内容。

权限： analytics.read

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/forms/:form_id/feedback/:id/mark_read.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回评分、文字、对方提供的姓名以及被阅读的时间。私下反馈是在开启低评分路由的表单上、评分较低的回答。它绝不是客户评价，也绝不公开。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/forms/:form_id/feedback/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回某个工作区（路径中使用 workspace_id）的以下内容：调用者在该工作区的角色和权限，features（套餐包含哪些受限报告：traffic_quality、bot_detection、external_experiments、campaign_costs、status_pages、traffic_rules、experiment_advanced（实验的高级设置）和 survey_ai_themes（问卷文字回答的主题），值为 true 或 false，以及 retention_months，值为月数，或为 null 表示无限制），sites_count（调用者可以打开的站点数量）和 min_app_version（API 仍然支持的最旧移动应用版本）。移动应用在打开工作区时读取一次，这样就可以将套餐未包含的报告显示为未包含，而不必去请求它。需要 analytics.read。

权限： analytics.read · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/workspaces/:workspace_id/app.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

移除当前调用的移动应用登录的推送注册，使设备不再收到推送。登录本身保持不变，应用可以重新注册。退出登录（使用刷新令牌调用 POST /oauth/revoke）也会将其移除。只有移动应用的令牌可以调用。

权限： member · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/account/device.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回当前调用的移动应用登录所对应的设备：registered（在应用注册推送令牌之前为 false）、platform、locale、timezone、app_version、kinds（所有推送类型）、muted_kinds 和 muted_site_ids（用户已关闭的内容）。只有移动应用的令牌可以调用。

权限： member · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/account/device.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

为当前调用的移动应用登录所对应的设备注册推送通知，或更改其接收的内容。只有您发送的输入会被更改。首次调用需要 platform 和 push_token。设备会收到以下推送：uptime（检测变为不可用或恢复）、alert（警报触发或已解决）、site_audit（站点审核完成）、experiment（实验有结果或已结束）和 usage（每月额度即将用完或已用完）。适用于其成员可以打开的每个站点，并且所有套餐均可使用。muted_kinds 和 muted_site_ids 用于关闭相应的类型和站点，且各自会替换整个列表。注册另一个应用登录已持有的推送令牌时，该令牌会转移到当前登录。只有移动应用的令牌可以调用。这是此类令牌可以执行的两个写入操作之一。

权限： member · 仅限 HTTP（不是 MCP 工具）

curl -X PATCH https://privatusanalytics.com/account/device.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

附上备注关闭请求，并让客户评价继续展示。不会删除任何内容，也不会向提出请求的人发送邮件。备注为必填。已经决定的请求会响应 422。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/removal_requests/:id/dismiss.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

默认列出未处理的请求，除非要求其他状态。提供者输入的邮箱只会返回给可以更改内容的调用者。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/removal_requests.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

trash 会把客户评价移入回收站，这会立刻把它从每个小部件、好评墙和公开页面上撤下，并且可在 30 天内撤销。dismiss 会让它继续展示，并且需要备注。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/removal_requests/:id/resolve.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

一个请求，含其涉及的客户评价、此人留下的备注、其被撤下后的情况、他们输入的邮箱是否与客户评价上的邮箱一致、询问了多少次，以及一旦做出的决定。邮箱本身只会返回给拥有 content.write 的调用者。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/removal_requests/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

不可逆地删除站点在某个日期范围内的浏览量、自定义事件和访问，且无法撤销。用它来清除测试流量或移除有问题的时段。它不会删除站点、其目标或设置（删除站点请使用 sites_delete）。from 和 to 是 YYYY-MM-DD 日期，均含边界并按站点时区读取，to 不能早于 from。confirm 必须与 sites_get 显示的站点域名完全一致（不区分大小写）。请求会被接受并立即返回，包含 status 为 queued、site_id、from 和 to。删除在后台分批运行，因此统计工具中的数字可能需要一些时间才能稳定，并且没有可轮询的状态端点，请查看统计工具直到该范围为空。该操作会记录在审计日志中。需要 sites.manage 权限。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/sites/:site_id/data_reset.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

最近几天在存储之前被丢弃或清理的点击数量。用它查看站点有多少机器人流量、被规则拦截的流量或被脱敏的内容。用 kind 选择 bot（被当作机器人丢弃的点击）、rule（被流量规则丢弃的点击）或 redaction（被个人数据清理器脱敏的值）。返回 kind、days、total、by_reason、by_country 和 by_day。by_reason 和 by_country 是 {value, count} 的列表（最多 50 项，最大的在前，未知时 value 为 null），by_day 是 {date, count} 的列表。days 会被限制在 1 到 395 之间，默认为 30。这些只是汇总计数。不存储 IP 地址、User-Agent 或被脱敏的值，因此无法追溯到任何个人。这些点击不计入计费事件。查看或更改规则请使用 traffic_rules_list。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/filter_stats.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

显示哪些工作区成员可以看到某个站点。工作区的每位成员都会按加入顺序列出，不分页。字段包括 membership_id（供 sites_access_update 使用的 uuid）、email、name、role、access（成员可以看到此站点时为 true）和 locked（所有者和管理员为 true，他们始终拥有访问权限且无法更改）。其他成员在拥有所有站点或对此站点有明确授权时才有访问权限。查看某位成员的完整站点列表请使用 members_list。需要 members.manage。

权限： members.manage

curl https://privatusanalytics.com/sites/:site_id/access.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

授予或移除某位成员对某个站点的访问权限。membership_id 来自 sites_access_list（或 members_list），access 为 true 表示授予，false 表示移除。所有者和管理员始终拥有访问权限，无法更改。从拥有所有站点的成员处移除访问权限，会将其切换为工作区中其他所有站点的明确列表，并关闭其 include_future_sites，因此他们不会获得日后创建的站点。授予已拥有所有站点的人不会有任何变化。您不能更改持有您所没有的权限或超出您所拥有站点的成员。需要 members.manage。以与 sites_access_list 相同的格式返回该成员的行。

权限： members.manage · 仅限 HTTP（不是 MCP 工具）

curl -X PATCH https://privatusanalytics.com/sites/:site_id/access.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

为调用用户给站点加星标，使其在 sites_list 和“所有站点”页面中排在前面。它只影响调用者，绝不影响其他成员，给已加星标的站点再次加星标不会有任何变化。该调用除站点 ID 外不需要任何输入。使用 sites_unfavorite 移除星标。需要 analytics.read。返回站点（见 sites_get），其中 favorite 为 true。

权限： analytics.read

curl -X POST https://privatusanalytics.com/sites/:site_id/favorite.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

移除调用用户给站点加的星标，使其不再在 sites_list 中置顶。它只影响调用者，如果站点未加星标则不会有任何效果。使用 sites_favorite 可再次加星标。需要 analytics.read。返回站点（见 sites_get），其中 favorite 为 false。

权限： analytics.read

curl -X DELETE https://privatusanalytics.com/sites/:site_id/favorite.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回在站点上安装跟踪所需的内容，以及数据是否已经到达。字段包括 site_id、snippet（可直接粘贴的 HTML script 标签，启用了所有跟踪器模块）、receiving_data（收到第一个事件后为 true）和 first_event_at（ISO 8601，在此之前为 null）。安装之后轮询它，查看事件是否正在进来。若需要自定义代码片段（选择模块、手动浏览量、SPA 模式、掩码），请改用 tracking_snippet，要获取实际页面并检查脚本是否存在，请使用 tracking_verify。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/setup.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

接受站点转让邀请，并将站点移入调用者的某个工作区。路径参数 token 来自邀请链接，workspace_id 是目标工作区（ws_...），调用者在其中拥有 sites.manage。调用者自己的邮箱必须与邀请发送到的地址一致，且目标不能是站点原来所在的工作区。站点会保留其 ID、设置、目标和数据，但按成员授予的访问权限会被清除，其共享链接会转移到新的工作区。如果邀请不再处于待处理状态或已过期，目标工作区已达到其套餐的站点上限，或其中已有相同域名的有效站点，则会失败。迁移无法撤销，只能转回。调用此接口的令牌必须属于目标工作区并拥有 sites.manage。返回 status 为 accepted 的转让。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/transfers/:token/accept.json \
  -H "Content-Type: application/json" -d '{…}'

通过向收件人发送有效期 7 天的邀请链接邮件，开始将站点迁移到另一个工作区。在收件人用该邮箱登录并接受（site_transfers_accept）之前不会移动任何内容，因此在此之前站点会留在这里。发起新的转让会取消同一站点之前任何待处理的转让。email 必须是有效地址，目标工作区由收件人选择。转让邮件有频率限制。使用 sites_transfer_cancel 撤回。需要 sites.manage。返回转让，包含 site_id、site_domain、from_workspace、to_email、status 为 pending 和 expires_at。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/sites/:site_id/transfer.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

取消站点待处理的转让邀请，使其链接失效。如果没有待处理的转让，它会因验证错误而失败。已被接受的转让无法取消。需要 sites.manage。返回 status 为 canceled 的转让。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/transfer.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

根据链接中的 token（路径参数 token，来自 sites_transfer_start 发送的邀请邮件）显示站点转让邀请。调用者必须已登录或使用 API 令牌。返回 site_id、site_domain、from_workspace（发送方工作区的名称）、to_workspace_id（接受之前为 null）、to_email（受邀地址）、status（pending、accepted 或 canceled）和 expires_at。邀请在发送 7 天后过期。使用 site_transfers_accept 接受。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl https://privatusanalytics.com/transfers/:token.json

向工作区添加一个网站并返回它，包括要安装的跟踪代码片段。工作区的套餐限制站点数量（Free 允许 3 个），达到上限时调用会因套餐限制错误而失败。domain 为必填并会被规范化（例如完整 URL 或 www 前缀会被简化为主机名）。name 默认为域名，timezone 默认为工作区的时区（IANA 名称，如 Europe/Berlin），currency 默认为工作区的货币（3 位 ISO 4217 代码，如 USD）。附带效果包括向工作区的通知渠道发送 site.created 通知，将首次 SEO 站点审计和域名评级检查加入队列，并向创建它的成员发送带有跟踪代码的邮件（在没有数据到达期间会有提醒）。限定于所选站点且选择了接收未来站点的成员会获得对它的访问权限。需要 sites.manage。随后请用 tracking_snippet 或 sites_setup_get 安装，用 tracking_verify 检查。

权限： sites.manage

curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sites.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

删除站点。这是软删除，站点会停止采集并立即从列表中消失，其数据在 7 天后被永久清除，因此请将其视为不可逆，如果是误操作请尽快联系支持。confirm 必须是站点的域名（不区分大小写）。该站点待处理的转让会被取消，并向工作区的通知渠道发送 site.deleted 通知。若只想清除部分流量并保留站点，请使用 sites_reset_data。需要 sites.manage。返回站点。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出调用者可访问的工作区站点，分页，调用者加星标的站点在前。用 query 搜索域名或名称（部分匹配，不区分大小写），用 label 只保留带有某个标签的站点，用 sort 选择 position（已保存的顺序，默认）、name 或 visitors（最近 30 天的访客，最多的在前）。响应 meta 除每页分页外，还包含 stats（以站点 ID 为键的对象，含 visitors（近期独立访客）、change（相对上一时间段的变化百分比）、sparkline（每日值的列表）和 live（当前访客））以及整页的 totals。每一项的字段与 sites_get 相同。这是查找其他所有站点工具所使用的站点 ID（pa_...）的起点。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/workspaces/:workspace_id/sites.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

按公开 ID（pa_...，来自 sites_list）返回单个站点的设置和状态。关键字段包括 id、workspace_id（ws_...）、domain、name、extra_domains 和 multi_domain_mode（combined 或 separate）、timezone（IANA 名称）、currency（ISO 4217）、labels、隐私选项（honor_dnt、honor_gpc、pii_scrubber、redaction_rules、allowed_params、path_masks）、retention_months（null 表示保留所有数据）、bot_filtering、traffic_rule_modes（将规则列表映射到 block 或 allow 的对象）、vitals_sample_rate（百分比）、conversion_denominator（visits 或 visitors）、public_dashboard 和 public_indexable、ingest_key_prefix（站点没有爬虫日志密钥时为 null）、verified_at、first_event_at 和 last_event_at（数据到达之前为 null）、domain_rating（可为空）、snippet（HTML 跟踪标签）、favorite（调用者是否加了星标）和 created_at。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

更新站点的设置，只更改您发送的字段。名称和身份字段包括 name、domain（更改它会重新检查域名评级）、extra_domains（主机名列表）和 multi_domain_mode（combined 将跨域名的访客计为一个，separate 则将它们分开）。timezone 是 IANA 名称，currency 是 3 位 ISO 4217 代码。隐私字段包括 honor_dnt、honor_gpc、pii_scrubber、redaction_rules（含 name 和 pattern 的对象列表，pattern 为正则表达式）、allowed_params（要保留的查询参数）、path_masks（含 pattern 和 replacement 的对象列表）和 bot_filtering。列表会替换整个现有列表。retention_months 不得超过套餐的保留期（Free 为 6 个月）。traffic_rule_modes 将规则列表（hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events）映射到 block 或 allow。vitals_sample_rate 是百分比，套餐对其设有上限（Free 为 10，付费套餐为 100）。conversion_denominator 为 visits 或 visitors。public_dashboard 使任何持有链接的人都能查看统计数据，public_indexable 允许搜索引擎为该页面建立索引。更改会在片刻之内对新事件生效。需要 sites.manage。返回更新后的站点。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出某次审计的问题，每个标记了内容的检查一行，最严重的在前（先是错误，再是警告，最后是提示，各自按受影响的 URL 数量排序）。每行包含 check_key（用于 site_audit_issues_get 和静音工具）、title、category、severity（error、warning 或 notice）、affected（被标记的 URL，不含已静音的）、added 和 fixed（相对上一次审计的变化）以及 pageviews（审计前 30 天内对受影响页面的访问）。默认为最新完成的审计，也可传入 audit_id。可用 severity、category 和 new_only（仅限 URL 自上一次审计以来为新增的检查）筛选。通过 page 和 per_page 分页（最大 100，默认 50）。要查看某个检查标记了哪些 URL，请使用 site_audit_issues_get。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/audit/issues.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

按 site_audit_issues_list 中的 check_key（例如 title_missing）查看审计中某个检查的详情。返回 audit_id、issue（与列表中相同的行）、why（该问题的含义）、fix（如何修复）、muted（整个检查对站点已静音时为 true）以及 urls，即被标记的 URL，含 page_id（用于 site_audit_pages_get）、url、pageviews、detail（关于该发现的额外信息，可能为空）、is_new 和 muted。sort 为 pageviews（默认，最繁忙的在前）或 url。通过 page 和 per_page 分页（最大 100，默认 25）。默认为最新完成的审计，也可传入 audit_id。已静音的 URL 排在最后。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/audit/issues/:check_key.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

在一次请求中静音多个发现，要么全部成功要么全部失败。使用两种形式之一。可以发送 check_key 加 urls（最多 100 个 URL）在多个页面上静音一个检查，或发送 check_keys（最多 100 个）为站点静音整个检查。不要把 urls 与 check_keys 混用。未知的检查或无效的 URL 会使整个请求失败，且不会静音任何内容。已静音的项目会原样返回。最新审计的数量和得分会在最后刷新一次。返回静音列表。可分别用 site_audit_mutes_delete 撤销。需要 content.write。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/audit/mutes/bulk.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

为站点静音某个检查，或只针对某个 URL 静音。check_key 来自 site_audit_issues_list。省略 url 会在所有地方静音该检查，或传入完整 URL（如 https://example.com/old）只在该页面静音，URL 会按抓取器的方式规范化。最新审计的数量和得分会立即更新。对同一内容重复静音会返回已有的静音，而不是报错。要一次静音多个请使用 site_audit_mutes_bulk，要撤销请使用 site_audit_mutes_delete。需要 content.write。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/audit/mutes.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

移除一个静音，通过 site_audit_mutes_list 中的 id 查找，使该检查或 URL 重新计入审计得分。最新审计会立即重新计数。这只会移除静音，不会删除审计数据。返回已移除的静音。需要 content.write。

权限： content.write

curl -X DELETE https://privatusanalytics.com/sites/:site_id/audit/mutes/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出站点已静音的检查，按时间从新到旧排序。静音会在整个站点范围内（url 为 null）或针对单个 URL 隐藏某个检查，因此这些发现不会计入数量和得分，不过审计仍会记录它们。每行包含 id（静音 ID，用于 site_audit_mutes_delete）、site_id、check_key、title、url（站点范围的静音为 null）、muted_by（成员姓名，未知时为 null）和 created_at。可用 check_key 筛选。通过 page 和 per_page 分页（最大 100）。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/audit/mutes.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

为调用成员在某个站点上开启或关闭每周审计摘要邮件。这是个人偏好，不影响其他成员。enabled 为 true 时，会在此站点的审计之后向该成员发送摘要，false 则停止。返回 site_id、enabled 和 all_sites_enabled（成员在账户设置中关闭了所有站点的审计邮件时为 false，这会覆盖此设置）。任何拥有 analytics.read 的成员都可以更改自己的设置。

权限： analytics.read

curl -X PATCH https://privatusanalytics.com/sites/:site_id/audit/notifications.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

页面浏览器，列出某次审计的 URL（默认是最新完成的审计，也可传 audit_id）。kind 为 page（默认，HTML 文档）、resource（图片、脚本、样式表）或 external（指向其他站点的链接）。可按 state（queued、fetched、skipped、blocked、failed）、status_class（2xx、3xx、4xx 或 5xx）、indexable、in_sitemap、has_issues（仅统计未静音的问题）、depth（距起始页的点击数）和 query（URL 或标题中的文本）筛选。sort 为 pageviews（默认）、inlinks、depth、response_ms（最慢的在前）或 word_count（最少的在前）。每行包含 id（用于 site_audit_pages_get 的 UUID）、url、path、kind、state、status、depth、indexable、indexability_reason、title、word_count、response_ms、cache_status、inlinks、pageviews、in_sitemap 和 issues（数量）。通过 page 和 per_page 分页（最大 100）。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/audit/pages.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

审计为某个 URL 存储的全部内容，通过 id（来自 site_audit_pages_list 或 site_audit_issues_get 的 urls 的 UUID）查找。返回 id、audit_id、page（url、status、redirect_to、content_type、bytes、response_ms、title、meta_description、h1、canonical、robots_meta、indexable 和 indexability_reason、word_count、lang、hreflang、schema_types、社交标签、images_count、images_missing_alt、链接数量、link_score、in_sitemap、has_tracker、pageviews 和 search_clicks、fetched_at 等）、redirect_target_id（审计内其重定向到的页面，或 null）、issues（check_key、title、category、severity、detail、is_new、muted），以及 inlinks 和 outlinks（各最多 100 条，含 page_id、url、status、kind、anchor、nofollow、count）。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/audit/pages/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回站点的审计设置。字段包括 site_id、enabled（定时审计开启或关闭，默认开启）、include_subdomains、check_external_links、exclude_paths、ignored_params、extra_start_urls、next_run_at（下一次定时审计的到期时间，没有时为 null）、page_limit（当前套餐下每次审计的页面数，不限时为 null）和 interval_days（套餐下定时审计之间的天数）。从未更改过设置的站点会返回默认值。可用 site_audit_settings_update 更改。需要 sites.manage。

权限： sites.manage

curl https://privatusanalytics.com/sites/:site_id/audit/settings.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

更改站点的审计方式。只有您发送的输入会被更改。enabled 开启或关闭定时和手动审计（开启时会将下一次审计安排在一个套餐间隔之后）。include_subdomains 和 check_external_links 是布尔值。这三个列表会替换已存储的列表而不是合并，因此请发送完整列表。exclude_paths 是抓取器跳过的路径前缀，每个都必须以斜杠开头（最多 50 个）。ignored_params 是永远不会产生不同页面的查询参数名，如 utm_source 或 sessionid（最多 50 个，可含字母、数字、点、连字符、下划线）。extra_start_urls 是除首页外要抓取的完整 http 或 https URL（最多 20 个）。列表也可以作为文本发送，每行一项。返回更新后的设置。需要 sites.manage。

权限： sites.manage

curl -X PATCH https://privatusanalytics.com/sites/:site_id/audit/settings.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/audit/unsubscribe/:token.json \
  -H "Content-Type: application/json" -d '{…}'

停止站点正在运行或排队的审计。该审计会被标记为 canceled，未完成的抓取不会报告任何内容。已取消的审计不会占用 Free 套餐的每月额度。如果没有进行中的审计，则会因验证错误而失败。返回已取消的审计。需要 content.write。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/audit/cancel.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

逐项对比站点的两次审计。audit_id 是较新的审计，base_id 是较旧的审计。两者都有合理的默认值（最新完成的审计对比其之前完成的审计），如果您传入的顺序有误，工具会将它们对调。返回 audit 和 base（各为审计摘要，之前没有审计时 base 为 null）以及 checks，即每个 URL 发生变化的检查一个对象，含 check_key、title、category、severity、base_affected、affected、added 和 fixed（URL 数量），按错误优先排序。没有变化的检查会被省略。对于相邻的两次审计，added 和 fixed 是精确值，对于间隔较远的审计，它们是净变化。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/audit/compare.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

立即对站点开始一次新的抓取和 SEO 审计。它在后台抓取站点的公开页面，因此会立即返回，新审计的状态为 queued。请轮询 site_audit_get（live 字段）或 site_audit_history，直到状态为 complete。在以下情况会因验证错误而被拒绝：审计已在 site_audit_settings_update 中关闭，已有另一个审计在排队或运行，最近 24 小时内已发起过手动审计，以及在 Free 套餐上最近 30 天内运行过任何审计（失败和已取消的不计）。未验证且没有事件的站点还会被限制为每个域名每天一次审计。抓取的页面数受套餐限制（Free 为 100，Pro 为 1,000，Business 为 10,000）。请先在 site_audit_get 中检查 can_run。需要 content.write。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/audit.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出站点的审计，按时间从新到旧排序，每个含 id（aud_...）、status（queued、running、analyzing、complete、partial、failed 或 canceled）、trigger（first、scheduled 或 manual）、score（0 到 100，完成之前为 null）、score_band、page_limit、pages_crawled、urls_discovered、errors、warnings、notices、new_issues、fixed_issues、failure（失败时的原因，否则为 null）和各时间戳。可用 status 筛选。通过 page 和 per_page 分页（最大 100）。将这些 id 用于 site_audit_get、site_audit_compare 以及问题和页面工具。查看某次审计的当前状态请使用 site_audit_get。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/audit/history.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

SEO 站点审计概览，也是处理审计问题时最适合首先调用的接口。默认描述最新完成的审计，也可传入 audit_id（aud_...，来自 site_audit_history）查看较早的审计。结果包含 audit（已完成的审计，含 0 到 100 的 score、score_band、score_delta、errors、warnings 和 notices 的数量、pages_crawled、page_limit、capped、summary 和 robots 详情，没有已完成的审计时为 null）、live（正在运行的审计，或 null）、enabled 和 next_run_at（计划）、can_run 以及 run_blocked（live、disabled 或 too_soon）和 run_allowed_at（site_audit_run 再次被允许的时间）、changes（按严重程度统计的新增和已修复的 URL 数量）、trend（最近最多 30 个得分，含 id、finished_at、score）、top_issues（最多 10 项检查，按严重程度再按受影响页面的浏览量排序）和 email_enabled（您自己的摘要邮件偏好）。随后用 site_audit_issues_list 查看每个问题，用 site_audit_pages_list 查看 URL。需要 analytics.read。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/audit.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

将一组筛选条件保存为命名的细分，可通过 segment_id 在任何统计工具上重复使用。传入 name 和 filters（所有条件都必须匹配，{any: [...]} 分组在其中任一条件匹配时即匹配，维度名称和运算符见 filters 输入）。筛选条件会被检查，因此未知的维度或错误的值会返回 422，并为每一行给出消息。请先用 segments_preview 检查一组筛选条件匹配什么。shared 默认为 true，使细分对所有有权访问该站点的人可见，false 则仅您自己可见。返回细分，包含 id（seg_...）、site_id、name、description、filters、summary（通俗的英文描述）、shared、mine 和时间戳。需要 content.write 权限。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/segments.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一个已保存的细分。使用它的仪表板和链接会回退到全部流量。不会触及任何分析数据，也无法撤销。返回已删除的细分。ID（seg_...）来自 segments_list。需要 content.write 权限。

权限： content.write

curl -X DELETE https://privatusanalytics.com/sites/:site_id/segments/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出某个站点已保存的细分，按名称排序：包括共享的细分和您自己的私有细分。每个细分包含 id（seg_...）、site_id、name、description、filters、summary、shared、mine 和时间戳。将某个 id 作为 segment_id 传给任何统计工具（stats_aggregate、stats_breakdown、funnels_get 等）即可应用该细分的筛选条件。通过标准的 page 参数分页。添加细分请使用 segments_create。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/segments.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

检查一组筛选条件而不保存任何内容。返回 summary（通俗英文表述的筛选条件）、visitors（最近 30 天匹配的访客数，筛选条件无效时为 null）、period（始终为 30d）和 filters（将被存储的清理后的规范形式）。筛选条件的格式与 segments_create 相同，包括 {any: [...]} 分组，以及可选的国家或地区、渠道和目标的全称名称，它们会被转换为代码和 ID。无效的筛选条件会返回 422 并指明具体行。在 segments_create 之前用它试验筛选条件，查看其他时间段的数字请使用带 filters 的 stats_aggregate。

权限： analytics.read

curl -X POST https://privatusanalytics.com/sites/:site_id/segments/preview.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回一个已保存的细分：id（seg_...）、site_id、name、description、filters（存储的条件）、summary（通俗的英文描述，如 Visitors from the United States on mobile）、shared（对所有有权访问该站点的人可见）、mine（由您创建时为 true）和时间戳。您可以读取共享的细分和自己的私有细分。ID 来自 segments_list。若要统计一组筛选条件匹配多少访客，请使用 segments_preview。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/segments/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

重命名细分、替换其筛选条件或更改谁可以看到它。只有您发送的输入会被更改。发送 filters 会替换所有现有筛选条件，格式和检查与 segments_create 相同。shared 为 false 会使其仅创建者可见。发送空的 description 可将其清除。所有使用该细分的内容（例如带其 segment_id 的统计调用）会立即改变。返回细分。ID 来自 segments_list。需要 content.write 权限。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/segments/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出 Privatus Analytics 博客的文章，最新的在前，包含 slug、title、kicker、rubric（一句话摘要）、description、path 和日期，不含正文。要阅读某一篇，请使用 blog_get 并带上其 slug。通过 page 和 per_page 分页（最大 100）。公开，无需认证。

权限： public

curl https://privatusanalytics.com/blog.json

按 slug（来自 blog_list，即 /blog/<slug> 的最后一部分）返回一篇博客文章，包含其标题、Markdown 正文和渲染后的 HTML。文章以英文撰写。公开，无需认证。

权限： public

curl https://privatusanalytics.com/blog/:slug.json

已发布的产品更新，最新的在前。也可通过 /changelog.rss 以 RSS 订阅。

权限： public

curl https://privatusanalytics.com/changelog.json

浏览器客户端会以 `cf-turnstile-response` 发送 Cloudflare Turnstile 令牌。使用 API 令牌的请求无需发送。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/contact.json \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/newsletter/confirm.json \
  -H "Content-Type: application/json" -d '{…}'

浏览器客户端会以 `cf-turnstile-response` 发送 Cloudflare Turnstile 令牌。使用 API 令牌的请求无需发送。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/newsletter.json \
  -H "Content-Type: application/json" -d '{…}'

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/newsletter/unsubscribe.json \
  -H "Content-Type: application/json" -d '{…}'

与定价页面相同的数据：事件档位、各项套餐限额以及哪些计为事件。传入 events 可获取匹配的档位。

权限： public

curl https://privatusanalytics.com/pricing.json

数据库、Redis 和后台作业的健康状况，最多每 15 秒检查一次。

权限： public

curl https://privatusanalytics.com/status.json

免费计算器，用于估算使用 Cookie 同意的分析工具与无 Cookie 跟踪相比会漏掉多少流量。这是一个简单的模型，而不是实际测量。输入包括 monthly_visitors（大于 0 的整数）、consent_rate（接受横幅的访客百分比，0 到 100）和 adblock_share（拦截器阻止脚本的访客百分比，0 到 100，默认 25）。返回这些输入，外加 measured_with_consent（同意类工具能看到的访客）、missed（它看不到的访客）、missed_percent（保留一位小数）、measured_cookieless（无需横幅即可触达的访客）和 recovered_by_cookieless（相比同意类跟踪多出的访客）。所有访客数量均为整数。它不发起任何请求，也不使用任何账户数据。公开，无需身份验证。

权限： public

curl https://privatusanalytics.com/tools/consent-gap.json

获取一个公开页面并检查影响分析的响应标头。在跟踪数据缺失或来源看起来不对时使用。它会查看 Referrer-Policy、Content-Security-Policy 的 script-src 和 connect-src 指令（Privatus Analytics 是否可以加载和发送数据）、Permissions-Policy 以及 Set-Cookie 标头的数量。返回 url（经过最多 3 次重定向后的最终 URL）、status（HTTP 状态）和 findings，每项含 check、value（可为空）、level（ok、warn 或 info）和通俗易懂的说明。URL 必须是 http 或 https 且公开，私有和内部地址会被拒绝，只读取前 1 MB，获取在 5 秒后超时。每个客户端每分钟限 10 次调用。公开，无需身份验证。

权限： public

curl https://privatusanalytics.com/tools/header-checker.json

起草一段隐私政策文字，描述 Privatus Analytics 如何在客户的站点上收集数据（无 Cookie、不存储个人数据、位置仅精确到国家或地区）。这只是一个起点，不构成法律建议。输入包括 site_name（最多 120 个字符）、contact_email（可选，会添加一句联系方式）和 honors_gpc（默认 true，会添加一句说明遵循“请勿跟踪”和 Global Privacy Control）。返回 site_name、paragraphs（字符串数组）、text（以空行连接的段落，名称后面的括号中附有 Privatus Analytics 的网址）和 html（以 <p> 元素表示的段落，名称为普通链接）。文本使用请求所用的语言撰写，默认为英文。它不会对任何账户做出更改。公开，无需身份验证。

权限： public

curl https://privatusanalytics.com/tools/privacy-policy-generator.json

生成 SVG 图像格式的二维码，用于印刷或海报。可与 tools_utm_builder 生成的带 UTM 参数的链接搭配使用。输入包括 text（URL 或文本，最多 1,000 个字符）和 level（纠错级别 l、m、q 或 h，默认 m，级别越高越能承受损坏，但二维码越密）。返回 text、level、size（每边的模块数）和 svg（独立的 SVG 文档，白底黑码）。对所选级别而言过长的文本会被拒绝。若需要被跟踪的短链接的二维码，请改用 links_qr。公开，无需身份验证。

权限： public

curl https://privatusanalytics.com/tools/qr-code.json

获取一个公开页面，并列出它设置的 Cookie 和它引用的已知第三方跟踪器。在选择同意方案之前，用它快速检查页面加载了什么。这只是对 HTML 和响应标头的静态扫描，不会运行 JavaScript，因此由脚本设置的 Cookie 以及稍后由标签管理器加载的标签会被漏掉。返回 url（经过最多 3 次重定向后的最终 URL）、status、truncated（只读取了前 1 MB 时为 true）、cookies（name、domain、path、expires、secure、http_only 和 same_site，绝不返回值）、trackers（name、category、match 和 evidence，其中 category 为 advertising、analytics、session_recording、tag_manager、marketing 或 privacy_analytics）和 third_party_hosts（其他站点的主机名，已排序）。URL 必须是公开的 http 或 https，获取超时为 5 秒，每个客户端每分钟限 10 次调用。公开，无需身份验证。

权限： public

curl https://privatusanalytics.com/tools/tracker-scanner.json

构建带 UTM 参数的营销活动 URL，并标出常见错误。输入包括 url（必须是 http 或 https）、source、medium 和 campaign（均为必填），以及可选的 term 和 content。URL 上已有的 utm_ 参数会被替换，其他查询参数会保留。返回 url（生成的完整链接）、params（已添加的 utm_ 值，空值会被省略）和 warnings（对含有大写字母、空格，或看起来像电子邮件地址或长数字的值给出的字符串，这类内容绝不应出现在 URL 中）。请使用不含空格的小写值，以免同一个活动在报告中被拆分成多行。它不会保存任何内容。公开，无需身份验证。

权限： public

curl https://privatusanalytics.com/tools/utm-builder.json

浏览器客户端会以 `cf-turnstile-response` 发送 Cloudflare Turnstile 令牌。使用 API 令牌的请求无需发送。

权限： public · 仅限 HTTP（不是 MCP 工具）

curl -X POST https://privatusanalytics.com/waitlist.json \
  -H "Content-Type: application/json" -d '{…}'

佣金、因退款和拒付产生的追回以及冲正，最新的在前。金额以分为单位。

权限： member

curl https://privatusanalytics.com/account/affiliate/commissions.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

所选主题下注册框的嵌入代码（脚本和纯 iframe 两种）、预填表单的属性、脚本在您页面上触发的事件，以及注册框的数据：等待确认的注册、已确认的注册和付费客户。在您的联盟申请获批之前，available 为 false。

权限： member

curl https://privatusanalytics.com/account/affiliate/signup-box.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

您的联盟申请状态、推荐链接、您推荐的注册数和付费客户数，以及各币种的余额（保留中、可支付、已支付）。尚未申请时 status 为 none。

权限： member

curl https://privatusanalytics.com/account/affiliate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

记录某个营销活动在某个月的广告花费，使 campaigns_list 能显示单次获客成本和广告支出回报率。如果同一活动和月份的条目已存在，它会被替换而不是重复，因此调用两次也是安全的。campaign 是您的跟踪链接中出现的 utm_campaign 值，month 为 YYYY-MM（也接受 2026-09-15 这样的完整日期，并会归到当月 1 日），amount 是以主要货币单位表示的数字（1250.50，而不是最小单位）。currency 是可选的 3 位 ISO 代码，默认为站点货币。响应返回已存储的条目，其中 amount_minor 以最小单位表示。一次导入多行请使用 campaign_costs_import。需要 content.write。需要 Business 或 Enterprise 套餐（否则返回 402 plan_limit）。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/campaigns/costs.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

永久删除一条花费条目，通过 campaign_costs_list 中的 id 查找。此操作无法撤销，该活动在该月的 CPA 和 ROAS 会立即不再包含这笔花费。其他月份和其他活动不受影响。返回已删除的条目。需要 content.write。需要 Business 或 Enterprise 套餐（否则返回 402 plan_limit）。

权限： content.write

curl -X DELETE https://privatusanalytics.com/sites/:site_id/campaigns/costs/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

从 CSV 批量导入广告花费，是一次加载多个活动和月份的快捷方式。可在 csv 中发送 CSV 文本（最适合工具和 API 调用），或在 file 中上传文件（仅限 multipart）。第一行必须是包含 campaign、month 和 amount 的表头，另可有可选的 currency 列，例如 campaign,month,amount,currency 然后是 spring_sale,2026-09,1250.50,USD。month 为 YYYY-MM，amount 以主要货币单位表示，currency 默认为站点货币。各行按 campaign 和 month 更新或插入，因此重复导入同一文件不会产生重复。限制为 1 MB 和 5,000 行。有问题的行不会中止导入。响应包含 imported（已保存的数量）、failed（被拒绝的数量）和 errors（前 50 条消息，每条都指明其所在行，其中第 2 行是第一行数据）。缺少表头列、文件过大或 CSV 格式错误会导致整个请求失败。需要 content.write。需要 Business 或 Enterprise 套餐（否则返回 402 plan_limit）。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/campaigns/costs/import.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出为某个站点记录的广告花费条目，按月份从新到旧，再按活动名称排序。每行是某个活动在某个月的数据，包含 amount_minor（以最小货币单位表示的整数，125050 表示 1,250.50）、currency（ISO 4217，大写）、month（YYYY-MM）和条目 id（UUID，供 campaign_costs_update 和 campaign_costs_delete 使用）。传入 campaign 可只查看一个活动（对 utm_campaign 的值不区分大小写匹配）。通过 page 和 per_page 分页（最大 100）。花费会用于 campaigns_list 中的 CPA 和 ROAS，因此可在这里查看某个活动已有的花费。需要 analytics.read。需要 Business 或 Enterprise 套餐（否则返回 402 plan_limit）。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/campaigns/costs.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

修改一条已有的花费条目，通过 campaign_costs_list 中的 id 查找。只有您发送的输入会被更改，因此只发送 amount 即可更正数字。amount 以主要货币单位表示（1250.50）并按最小单位存储，month 为 YYYY-MM，currency 为 3 位 ISO 代码。将 campaign 或 month 改成另一条条目已有的组合时，会因验证错误而失败，而不是合并。若要在不知道 id 的情况下更正某个活动和月份的花费，请调用 campaign_costs_create，它会替换现有条目。需要 content.write。需要 Business 或 Enterprise 套餐（否则返回 402 plan_limit）。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/campaigns/costs/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

为落地页生成带 UTM 标记的 URL 并检查各值。不会保存任何内容，也不读取任何数据，因此可以放心重复调用。传入 destination（完整的 https:// URL），并按需传入 utm_source、utm_medium、utm_campaign、utm_content 和 utm_term，或选择一个预设（newsletter、social、paid_search 等），在您留空时自动填充 utm_source 和 utm_medium。返回 url（出错时为 null）、valid、destination、preset、清理后的 utm_* 值、issues（{field, level, message} 的列表，其中 level 为 error 会阻止生成 URL，warning 只是建议修正，例如改为小写）和 presets（可用的预设值）。各值会被清理为不含空格的小写形式。要找出您的流量中已存在的杂乱 UTM 值，请使用 campaigns_hygiene，要报告已运行的活动，请使用 campaigns_list。若要保留带短 URL 和点击次数的标记链接，请改用 links_create。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/campaigns/builder.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

找出某个时间段流量中杂乱的 UTM 值，以便您修正标记。返回 period、duplicates、style_issues 和 unknown_sources。duplicates 将仅在大小写、空格或标点上不同的 utm_source、utm_medium 或 utm_campaign 值分为一组（Facebook、facebook 和 face-book），每组格式为 {field, suggestion, variants: [{value, visits}]}，并建议访问最多的写法。style_issues 列出违反小写、无空格约定的值，格式为 {field, value, visits, suggestion}（最多 50 条）。unknown_sources 列出不是已识别渠道的 utm_source 值，格式为 {value, visits}（最多 50 条）。每个字段只扫描前 500 个值。计数单位是访问次数。建议仅供参考，不会更改任何内容。若要将多个变体合并为一个渠道，请使用 channel_rules_create。接受共享的 period 和 filters 输入。效果报告请使用 campaigns_list，创建规范的标记 URL 请使用 campaigns_builder。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/campaigns/hygiene.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

基于 utm_campaign 的营销活动效果报告，包含成本和广告支出回报率。返回 period、currency（站点货币）、goal_id 和 goal_name（其转化被统计的目标）、campaigns、totals 和 unconverted_costs。每个活动包含 visitors、visits、conversions、conversion_rate（0 到 100 的百分比，转化数除以访问数）、revenue 和 sources（按来源和媒介划分的行，指标相同）。存在成本时（来自 campaign_costs_list），活动还会有 cost、cpa（每次转化成本，没有转化时为 null）和 roas（收入除以成本，是 2.5 这样的比值，没有成本时为 null）。金额（revenue、cost、cpa）是以站点货币最小单位（分）表示的整数。成本按不区分大小写的方式与活动名称匹配，并按周期内每个月的天数按比例分摊。有成本但没有流量的活动仍会列出。最多 100 个活动，访问最多的在前。只包含带 utm_campaign 的访问。goal_id 默认为第一个启用的目标，因此要衡量特定目标请显式传入（ID 来自 goals_list）。整理名称请使用 campaigns_hygiene，单纯按流量拆分请使用 dimension 为 utm_campaign 的 stats_breakdown。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/campaigns.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

将带 UTM 标记的链接保存到站点的链接库（路径接受 site_id）。name（最多 120 个字符）和 destination（最长 2048 个字符的 http 或 https URL）为必填。utm 值会自动清理：转为小写、去除首尾空白并将空格变为下划线，看起来像个人数据的值（例如电子邮件地址）会被拒绝。最多保留 20 个标签，以逗号分隔的条目会被拆分，标签会转为小写并截断为 40 个字符。它只存储链接，本身不会跟踪任何内容。返回的 url 是添加了 UTM 参数的目标地址，目标地址中已有的 UTM 参数会被替换。需要二维码请使用 links_qr。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/campaigns/links.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

从链接库中移除一个已保存的链接。这只会删除保存的条目，您已分享的 URL 仍然有效，其访问仍会按营销活动统计。此操作无法撤销。id（lnk_...）来自 links_list。返回已删除的链接。

权限： content.write

curl -X DELETE https://privatusanalytics.com/sites/:site_id/campaigns/links/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

列出某个站点已保存的营销链接（带 UTM 标记的 URL，路径接受 site_id），按时间从新到旧排序并分页。每个链接包含 id（lnk_...）、name、destination、utm_source、utm_medium、utm_campaign、utm_content、utm_term、url（添加了 UTM 参数、可直接分享的目标地址）、tags、notes、created_at 和 updated_at。query 会搜索 name、destination 和 utm_campaign，tag 只保留带有该标签的链接。这是已保存的链接库，要查看活动的效果请使用 campaigns_list 或 dimension 为 utm_campaign 的 stats_breakdown。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/campaigns/links.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

返回已保存链接完整标记 URL 的二维码，用于印刷。响应包含 link_id、url（编码在二维码中的标记 URL）和 svg（以字符串形式给出的完整独立 SVG 文档，白底黑码）。size 是模块大小（像素），范围 2 到 20（默认 6），用于缩放图像。id（lnk_...）来自 links_list。只需要 URL 时请使用 links_get。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/campaigns/links/:id/qr.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

按 id 返回一个已保存的营销链接（lnk_...，来自 links_list）。响应包含 name、destination、utm_source、utm_medium、utm_campaign、utm_content、utm_term（未设置时均为 null）、url（完整的标记 URL）、tags、notes、created_at 和 updated_at。需要同一 URL 的可印刷二维码请使用 links_qr。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/campaigns/links/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

修改已保存的营销链接（id 来自 links_list）。只有您发送的输入会被更改。适用与 links_create 相同的清理和个人数据检查。发送 tags 会替换整个标签列表。对某个 utm 字段发送空字符串可将其清除。返回更新后的链接及其重新计算的 url。

权限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/campaigns/links/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

一次调用就包含整个表单：步骤、问题、跳转逻辑、授权措辞和语言。省略的内容会以该表单所用语言的合理默认值开始，slug 来自名称。链接是 https://privatus.page/f/<slug>。低评分路由和自定义 CSS 需要 Business 套餐（没有时为 402 plan_limit）。视频和音频回答在 Pro 及以上套餐中提供给提供者。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/forms.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

删除表单、其提交记录、奖励和私下反馈。它收集到的客户评价会保留。此操作无法撤销，因此由人工在页面上执行。API 需要 confirm（表单的名称或 id）。

权限： sites.manage · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/forms/:id/permanent.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

在恢复之前，它的链接会响应表单已关闭。回收站会在 30 天后清空。通过 MCP 时，该工具不会更改任何内容，而是响应应用中由人工操作的页面。

权限： content.write · 仅限 HTTP（不是 MCP 工具）

curl -X DELETE https://privatusanalytics.com/sites/:site_id/testimonials/forms/:id.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

复制除 slug、统计数据和奖励之外的所有设置。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/forms/:id/duplicate.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

当 trashed 为 true 时列出回收站中的表单，否则不包含它们。每个表单都带有其设置、奖励和已收到的提交数量。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/forms.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

二维码包含带 ?src=qr 的表单链接，因此扫码会被统计为独立的渠道。更改 slug 后，已打印的二维码仍然有效。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/forms/:id/qr.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

把表单连同其问题、提交和私下反馈原样移出回收站。它的链接（/f/<slug>）和嵌入重新接受回答。对不在回收站中的表单，服务器以 422 和代码 not_in_trash 响应。

权限： content.write

curl -X POST https://privatusanalytics.com/sites/:site_id/testimonials/forms/:id/restore.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN" \
  -H "Content-Type: application/json" -d '{…}'

返回链接、内联嵌入代码片段和弹窗嵌入代码片段。弹窗输入（trigger、label、position、accent）会改变弹窗代码片段。

权限： analytics.read

curl https://privatusanalytics.com/sites/:site_id/testimonials/forms/:id/share.json \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"

以 testimonial_forms_create 和 testimonial_forms_update 接受的形式返回整个表单，包含其 slug、链接、奖励和提交数量。回收站中的表单在这里找不到：请先恢复它。

权限： analytics.read