Analytics REST API

為呼叫此 API 的成員在工作區中建立 API token，並只在 token 欄位中回傳一次密鑰。請立即複製，之後無法再次讀取，遺失的 token 必須撤銷後重新建立。token 只能縮小其成員的權限範圍。省略 permissions 時，預設為該成員自己的所有權限（明確傳入空清單會被拒絕，要求您沒有的權限則會產生錯誤）。site_ids 接受公開網站 ID (pa_...)，並將 token 限制在這些網站，若為空，token 可用於其成員能存取的每個網站（或沿用發出此呼叫之 token 的網站清單）。expires_at 為選填的 ISO 8601 時間，必須在未來且最多 3 年內，省略則代表 token 永不過期。allowed_ips 將 token 限制在這些 IP 或 CIDR 範圍內。發出此呼叫的 token 需要 tokens.manage 權限。要求雙重驗證的工作區會拒絕為沒有自己第二驗證因素的成員建立 token。回傳的欄位與 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 token。使用該 token 的請求此後都會失敗，已撤銷的 token 無法復原，請改為建立新的 token。token 紀錄會以 revoked 狀態保留在清單中（使用 api_tokens_list 搭配 include_revoked 即可看到），再次撤銷已撤銷的 token 不會有任何變化。請從 api_tokens_list 取得 id (uuid)。您可以撤銷自己的 token，撤銷他人的 token 則需要 tokens.manage 權限，並涵蓋該 token 所涉及的每個網站。呼叫此操作的 token 需要 tokens.manage 權限。回傳已撤銷的 token，不含其密鑰。

權限： 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 token，最新的在前並分頁。沒有 tokens.manage 權限時只能看到自己的 token，有此權限則可看到所有成員的 token。除非 include_revoked 為 true，否則已撤銷與已過期的 token 會被隱藏。每個項目包含 id (uuid，供 api_tokens_delete 使用)、name、token_prefix (開頭的幾個字元，用來辨識 token)、owner (成員的電子郵件)、permissions (如 analytics.read 的名稱)、site_ids (公開網站 ID pa_...，空陣列代表擁有者可存取的每個網站)、allowed_ips、oauth_client (透過 OAuth 發出 token 時為所連結應用程式的名稱，否則為 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 '{…}'

新增與單一網站綁定的運作時間檢查。若是不屬於任何網站的檢查，請使用 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 (名稱、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 (單位為 hour 或 day，labels 為 ISO 8601 時間，series 為各地點的平均回應時間，單位毫秒，缺漏處為 null) 與 incidents (最近 50 筆，含 started_at、仍未結案時為 null 的 resolved_at、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 (名稱、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"

列出傳送給單一 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 端點及其整份傳遞記錄。此操作無法復原，待處理的重試會停止。若想改為暫停，請使用 webhooks_update 並設定 enabled 為 false。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 可只看單一原始事件名稱上出現的鍵。這裡絕不會回傳屬性值，請使用 stats_breakdown 搭配 dimension prop:<key>，或使用 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，因為資料列會在背景分批移除，所以在完成之前數字會持續變動。事件也會立即被隱藏，且刪除動作會記錄在稽核紀錄中。瀏覽量不受影響。如果只想停止顯示某個事件，請使用 events_update 並設定 hidden 為 true，這樣會保留資料。需要 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}。若要復原，請針對某個名稱以空的 display_name 呼叫 events_update。需要 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 提供數值型屬性的 sum、average 與其他數字。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 '{…}'

為單一網站的圖表新增註解，例如產品發布、行銷活動或版本釋出。若是要顯示在每個網站上的註解，請改用 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 (版本釋出或 commit) 組成的文字，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 '{…}'

列出網站圖表上顯示的註解 (notes)，日期最新的在前並分頁。它會回傳網站自己的註解，加上適用於每個網站的整個工作區註解。可用 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 '{…}'

回傳自訂儀表板單一卡片的即時資料。儀表板是卡片的清單（卡片清單請見 dashboards_get），且每張卡片各自載入，因此請針對每張卡片呼叫一次，並以 index 傳入其位置（從 0 起算）。回傳 index、type、title、site_id、site_name、params、status 與 data。status 為 ok、not_available (卡片沒有可顯示的內容，例如沒有漏斗的網站上的漏斗卡片，或沒有檢查項目的運作時間卡片) 或 no_access (卡片屬於您的 token 或角色無法開啟的網站，此時 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。其他 params 會被捨棄。period 必須是 30d 這類預設值（不能是 custom），metric 則為 visitors、visits、pageviews、views_per_visit、bounce_rate 或 visit_duration 之一。每張卡片都必須指向您的 token 能存取的網站，且僅限部分網站的 token 必須至少包含一張卡片。回傳儀表板，包含 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 相同。僅限部分網站的 token 只會看到包含其網站卡片的儀表板，其他網站的卡片會被清空為 {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} 的卡片屬於您無法開啟的網站。請原封不動送回以保留它，它無法被編輯，且該網站的最後一張卡片無法被移除。僅限部分網站的 token 不能讓儀表板變成空的。回傳更新後的儀表板。需要 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 selector 表示（標籤、id 和最多兩個 class，最多四層），若網站為它命名，則以 [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 時會加上 comparison_period、comparison、change 與 comparison_series，與 stats_aggregate 和 stats_timeseries 相同。單位與那些工具一致：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"

探索造訪中最常見的三步驟頁面路徑。在 forward 模式（預設）下，會顯示 path 所指定起始頁面之後的路徑，若 path 為空白則顯示任何進入點之後的路徑。在 reverse 模式下，會顯示通往結束頁面 (path) 或目標 (goal_id，會自動切換為 reverse) 的路徑。reverse 需要 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 包含每項 Web Vital 的 p75 值與評等。events 是在該頁面觸發的自訂事件，clicks 是被點擊最多的元素選擇器，goals 是在該頁面完成的目標，notes 是提及該頁面的註解。使用 stats_breakdown 搭配 dimension page 可為頁面排名，使用 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 可為參照網站排名，使用 stats_breakdown 搭配 dimension referrer 可取得簡單清單。

權限： 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，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"

在單一網站上開啟新的詢問對話，並使用該網站的分析資料回答其第一個問題。用於以白話文詢問網站的問題。若要延續既有對話請使用 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 (可為空的建議目標)、token 數量與 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 '{…}'

立即永久刪除單一詢問對話及其所有訊息。此操作無法復原。對話 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 '{…}'

列出已登入成員在單一網站上的詢問對話，最近更新的在前。絕不會顯示其他成員的對話。用於尋找供 assistant_conversations_get、assistant_ask_followup 或 assistant_conversations_delete 使用的對話 ID。每個項目包含 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"

回傳單一詢問對話及其完整訊息歷史。對話 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"

在既有的詢問對話中提出追問，讓助理保留先前的問答作為上下文。若要開啟新對話請改用 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 '{…}'

移除呼叫成員在此網站的工作區中儲存的 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 (僅限 format 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 失敗，當匯出仍在排隊或執行中，或已失敗時則以驗證錯誤失敗（錯誤訊息會說明原因）。只要匯出本身尚未過期，就可以再次呼叫以取得新的連結。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"

將一組篩選條件儲存為具名的區隔，可透過 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 等)，即可套用該區隔的篩選條件。透過標準的分頁參數分頁。使用 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 (白話文描述，例如使用行動裝置、來自美國的訪客)、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 '{…}'

網站此刻正在發生的事。回傳 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 個，且僅限您的 token 能開啟的網站)，否則會使用路徑中的網站。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"

為網站建立無 Cookie 的網站內問卷。在 status 為 active 之前它不會收集任何內容，因此請先建立為 draft，或傳入 status active 立即開始。必填為 name (內部使用，訪客看不到，最多 120 個字元) 與 questions (依序 1 到 5 列)。每個問題是物件，含 key (選填，由小寫字母、數字與底線組成的穩定 id，省略時自動產生)、kind (text、choice、multi、rating、nps 或 yes_no)、prompt (必填，最多 200 個字元)、required (布林值)、choices (最多 10 個選項的清單，僅用於 choice 與 multi) 與 scale (3、5、7 或 10，僅用於 rating，預設 5)。NPS 一律使用 0 到 10。目標對象設定為 trigger_kind (immediate、delay、scroll、exit 或 manual)，搭配 delay_seconds (0 到 600，預設 10，僅用於 delay) 與 scroll_percent (1 到 100，預設 50，僅用於 scroll)、paths (含 match_type exact、prefix 或 glob 與 pattern 的列，空白代表每個頁面)、devices (desktop、mobile、tablet，空白代表全部)、position (bottom_right、bottom_left 或 center)、sample_rate (訪客的 1 到 100 百分比)、thank_you (最多 200 個字元)、starts_on 與 ends_on (YYYY-MM-DD)。問卷不能詢問電子郵件地址，且文字答案會被清除個人資料。Free 方案每個工作區允許 1 份問卷以及每月有限的回應數，付費方案無限制。需要 content.write 權限。回傳問卷，含 id (svy_...)。以 surveys_get 讀取答案。

權限： content.write

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

永久刪除問卷及其所有回應與答案。此操作無法復原，結果會遺失。如果只想停止收集，請改用 surveys_pause。id 來自 surveys_list，且 site_id 為必填。需要 content.write 權限。回傳被刪除的問卷。

權限： content.write · 僅限 HTTP（不是 MCP 工具）

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

列出網站的問卷，最新的在前，含其設定與回應數。可用 status (draft、active、paused 或 all，預設 all) 篩選。以 page 與 per_page (預設 25，最大 100) 分頁。每份問卷包含 id (svy_...)、name、status、questions、目標對象設定、starts_on、ends_on、created_at、updated_at 與 stats (responses、completed 與 this_month 計數)。單一問卷的答案與結果請使用 surveys_get。

權限： analytics.read

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

暫停問卷，使其立即不再向訪客顯示。已收集的回應會保留並顯示在 surveys_get 中，且 surveys_start 可恢復它。如果只想停止收集，請用它取代 surveys_delete。id 來自 surveys_list，且 site_id 為必填。需要 content.write 權限。回傳 status 為 paused 的問卷。

權限： content.write

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

回傳單一問卷在某個期間的結果報表，而不只是其設定 (設定與計數請使用 surveys_list)。選擇 period 預設值 (預設 30d)，或 period 為 custom 並搭配 from 與 to。回應包含 survey (其設定)、period (from 與 to 為 ISO 8601 時間)、responses (至少回答一個問題的人)、completed (回答最後一個問題的人)、questions (每個問題一筆，含 key、kind、prompt 與 answers 計數，另依 kind 附上細節) 以及 pages、devices 與 countries (各最多 10 列 value 與 count)。依 kind 的細節為：text 提供 texts (最多 100 則最新的文字答案，含 text 與 at)，choice、multi 與 yes_no 提供 choices (value、count、一位小數的百分比 share、offered)，rating 提供 average (沒有答案時為 null)、scale 與 distribution，nps 提供 score (NPS，範圍 -100 到 100，沒有答案時為 null)、promoters (9 與 10)、passives (7 與 8)、detractors (0 到 6) 與 distribution。使用 surveys_themes 摘要文字答案。

權限： analytics.read

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

將問卷設為 active，讓訪客可以看到。只有在目前日期介於 starts_on 與 ends_on 之間 (若有設定)、頁面符合其 paths 與 devices，且方案的每月回應額度尚未用完時才會出現。適用於 draft 或 paused 的問卷。id 來自 surveys_list，且 site_id 為必填。需要 content.write 權限。回傳 status 為 active 的問卷。以 surveys_pause 再次停止。

權限： content.write

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

使用 AI 將單一自由文字問題的文字答案歸納為主題。僅限 Business 方案。在 surveys_get 顯示有足夠答案的文字問題之後使用，並傳入 question_key (來自 surveys_get、kind 為 text 的問題的 key)。它至少需要 5 則文字答案，並使用最近的 300 則。結果最多列出 12 個主題，每個含 label、count、sentiment (positive、neutral 或 negative) 與 example (具代表性的答案，可為 null)，另有 answers (已摘要的答案數) 與 generated_at。每次新的產生會使用工作區每月 AI 額度中的一次提問，若失敗則會退還。結果會依答案快取，因此在沒有新答案時再次呼叫不會有任何費用。如果方案不包含此功能、額度已用完、未設定 AI 或答案太少，則會以驗證錯誤失敗。

權限： analytics.read

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

變更問卷。只有您傳送的輸入會變更。輸入與限制與 surveys_create 相同，status 為 draft、active 或 paused。傳送 questions 時整份清單會被取代，因此請包含您想保留的每個問題，並保留每個既有的 key 以保留已收集的答案 (以相同的 key 重新修改 prompt 的文字不會拆分結果)。您省略的問題會不再出現在結果中。目標對象設定的變更會立即對訪客生效。id 來自 surveys_list，且 site_id 為必填。需要 content.write 權限。回傳更新後的問卷。

權限： content.write

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

位於 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 '{…}'

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 個，一次執行，全部成功或全部不執行），或傳送 filters 搭配 confirm_count（整個結果）。超過 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 '{…}'

為網站建立 A/B 或分流網址測試。它會存成草稿，在有人於應用程式中啟動之前，不會把任何訪客導向他處。必填項目為 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 與分流網址測試，最新的在前。可用 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 '{…}'

貼上的 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 與 owner 角色。回傳工作區。

權限： 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 token 或 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 是 IANA 名稱，如 Europe/Berlin，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 '{…}'

讓 Free 工作區加入或退出 Privatus Analytics 標章加碼方案，該方案會提高每月事件額度。將 enabled 設為 true 即可加入。系統接著會在背景檢查工作區的網站上是否有標章並加以驗證，這可能需要一點時間，因此之後請讀取 billing_get 並查看 badge.verified_at。將 enabled 設為 false 即可退出，這會清除檢查與驗證日期並移除加碼額度。在 Pro 或 Business 工作區加入會被拒絕，因為付費方案沒有加碼額度。回傳工作區的帳務物件，與 billing_get 相同。需要 billing.manage。

權限： billing.manage · 僅限 HTTP（不是 MCP 工具）

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

在目前付費期間結束時取消付費訂閱。不會退款，方案會維持有效到 current_period_ends_at，之後工作區會改為 Free 方案。在此之前可使用 billing_resume 撤銷。當工作區沒有訂閱或已排定取消時會失敗。選填的 reason (列舉值之一) 與 comment 是離開時的問卷。comment 若有提供，會以該成員的意見回饋訊息寄給 Privatus Analytics 團隊，且不會被儲存。回傳 cancel_at_period_end 為 true 的帳務物件。需要 billing.manage。

權限： billing.manage · 僅限 HTTP（不是 MCP 工具）

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

將既有訂閱改為另一個方案、事件級距或計費週期。這會產生費用。變更會立即生效，並由 Paddle 按比例計算，因此會立刻對已存檔的付款方式收取費用或給予抵扣。請先以相同輸入執行 billing_preview 查看確切金額。如果工作區沒有訂閱（請改用 billing_checkout）、目標與目前的方案、級距和週期相同，或該方案與事件組合沒有價格，則會失敗。events 的值必須是 plans_list 中的級距之一。回傳更新後的帳務物件。需要 billing.manage。

權限： billing.manage · 僅限 HTTP（不是 MCP 工具）

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

為尚無訂閱的工作區啟動 Paddle 結帳，並回傳託管的結帳 URL。在有人於瀏覽器中完成結帳之前不會收取任何費用，因此請將 url 交給對方。若工作區已有訂閱，請改用 billing_change_plan。輸入為 plan (pro 或 business)、events (來自 plans_list 的每月事件數級距) 與 interval (month 或 year，預設 month)。價格已含 VAT 或銷售稅。已核准的折扣方案會自動套用，並回報於 discount_id。回傳 transaction_id、url (可為空)、price_id、plan、events、interval、amount (該週期的整數美元)、client_token 與 environment (sandbox 或 production，供 Paddle 覆蓋層使用)、custom_data 與 discount_id (可為空)。如果工作區已有訂閱則會失敗。需要 billing.manage。

權限： billing.manage · 僅限 HTTP（不是 MCP 工具）

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

為工作區申請折扣方案。這會送出申請供人員審核並寄信給 Privatus Analytics 團隊，本身不會直接給予折扣。方案包括 nonprofit、education、open_source (5 折)、open_source_free (免費 Pro，每月最多 1M 事件) 與 agency (您擁有的每個工作區享 8 折)。每個工作區只允許一份未結案的申請 (pending、approved 或 active)，被拒絕或撤銷後可以再次申請。license 只會為兩個開源方案保留。回傳申請內容，包含 program、status、percent、comp_events (可為空)、organization_name、website、proof_url、license、note、rejection_reason、created_at、reviewed_at、applied_at 與 revoked_at (可為空的時間戳記)。之後可在 billing_get 的 discount 欄位查看進度。需要 billing.manage。

權限： billing.manage · 僅限 HTTP（不是 MCP 工具）

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

回傳一個 Paddle 連結，讓人可以更新訂閱的付款方式。呼叫本身不會變更任何內容。請將 url 交給對方在瀏覽器中開啟。結果包含 kind (payment_method) 與 url。工作區沒有有效訂閱時會失敗。發票、地址與其他所有帳務細節請使用 billing_portal。需要 billing.manage。

權限： billing.manage · 僅限 HTTP（不是 MCP 工具）

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

回傳 Paddle 客戶入口網站的連結，讓人可以查看發票、付款方式與地址。呼叫本身不會變更任何內容。請將 url 交給對方在瀏覽器中開啟。結果包含 kind (portal) 與 url。如果工作區還沒有 Paddle 客戶（從未結帳），或該客戶與呼叫者無法存取的其他工作區共用，就會失敗，因為入口網站會揭露該客戶的所有資料。若只需要信用卡，請使用 billing_payment_method。需要 billing.manage。

權限： billing.manage · 僅限 HTTP（不是 MCP 工具）

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

顯示現在將訂閱改為另一個方案、級距或週期的費用，且不會變更任何內容。請務必先以相同的 plan、events 與 interval 輸入執行此操作，再執行 billing_change_plan。如果工作區沒有訂閱，或目標與目前的價格相同，則會失敗。回傳 plan、events、interval、price_id、amount (該週期的整數美元定價)、currency、charge_minor (現在會收取的金額)、credit_minor (未使用時間的抵扣額) 與 result_minor (淨額)，皆以幣別最小單位表示，另有 result_action (charge 或 credit，可為空)、next_billed_at (可為空) 與 warnings (字串，例如上個月的用量超過新級距，或新方案會超出網站或成員數等方案限制)。需要 billing.manage。

權限： billing.manage

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

撤銷已排定的取消，或恢復已暫停的訂閱，讓方案持續續訂。請在 billing_cancel 之後、current_period_ends_at 之前使用。已暫停的訂閱會立即恢復。如果沒有已排定的取消且訂閱未暫停，則會失敗。回傳更新後的帳務物件。需要 billing.manage。

權限： billing.manage · 僅限 HTTP（不是 MCP 工具）

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

回傳工作區的方案與帳務狀態。在變更任何帳務內容之前，以及想知道訂閱是有效還是即將取消時使用。欄位包含 workspace_id、plan (free、pro、business 或 enterprise)、plan_events (已購買的每月事件數級距)、allowance (實際允許的每月事件數，包含任何標章加碼)、billing_interval (month 或 year，可為空)、price (該週期的整數美元，可為空)、subscription_status、current_period_ends_at、cancel_at_period_end (已排定取消時為 true)、canceled_at、auto_upgrade、discount (最新的折扣申請，可為空)、discount_percent、billing_emails (陣列)、tax_id、badge (opted_in、verified_at、checked_at 與加碼額度大小) 以及 usage (與 billing_usage 回傳的物件相同)。需要 billing.manage。發票在 billing_invoices_list 中，逐月的用量檢視則是 billing_usage。

權限： billing.manage

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

更新工作區的帳務設定。只有您傳送的輸入會變更。billing_emails 是最多 5 個額外地址的陣列，用於接收發票與帳務通知，並會取代整份清單。tax_id 會儲存在工作區上，不會加入發票，因此也必須在結帳時輸入。auto_upgrade 預設為 false。為 true 時，達到每月事件上限會將工作區移到下一個級距並收取差額，而不是暫停收集。在收集已因上限而暫停時開啟它，會立即升級並收費，同時寄出確認信，如果 Paddle 拒絕升級則不會儲存任何內容。回傳帳務物件，與 billing_get 相同。需要 billing.manage。

權限： billing.manage · 僅限 HTTP（不是 MCP 工具）

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

回傳工作區某個月份的事件用量。用來確認工作區距離每月硬性上限還有多近。輸入為 month (該月份中的任何一天，預設為當月)。只有瀏覽量與自訂事件會計入。欄位包含 month、events、bots (機器人的彙總數量，不計費)、allowance、percent (0 到 100 以上，一位小數)、forecast 與 forecast_percent (線性推算至月底的預測，過去的月份為 null)、days_left、status (ok、達 80% 的 warning、達 100% 的 over、paused 或 locked)、sites (每個網站的 site_id、domain、name、events 與占比百分比，最大的在前)、history (先前的月份，含 month 與 events)、access_locked_at、collection_paused (正在丟棄新事件時為 true)、pause_reason (limit 或 staff，可為空)、collection_paused_at 與 resumes_at (因上限而暫停時為下個月 1 日)。需要 billing.manage。

權限： billing.manage

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

列出工作區的帳務交易，最新的在前。每個項目包含 id (搭配 billing_invoices_get 使用)、invoice_number (可為空)、status、amount_minor (以幣別最小單位表示的整數，因此 900 代表 9.00)、currency (ISO 代碼，如 USD) 與 billed_at (可為空的 ISO 8601)。以 page 與 per_page (最大 100) 分頁。它只列出交易。若要取得 PDF 請呼叫 billing_invoices_get，若要更新信用卡請使用 billing_payment_method。需要 billing.manage。

權限： billing.manage

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

回傳單一已計費交易的 PDF 發票連結。發票 id 請從 billing_invoices_list 取得（即 id 欄位，為 Paddle 交易 ID）。結果包含 kind (invoice) 與 url，這是來自 Paddle 的 PDF 連結，因此請在呼叫後盡快擷取或分享。如果該 id 不屬於此工作區，或 Paddle 沒有對應的發票，則會失敗。需要 billing.manage。

權限： billing.manage

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

回傳已登入成員自己的個人資料與偏好設定。可用來在以 account_update 變更之前先讀取設定。此操作針對的是個人，而非工作區。工作區方案與發票請見 billing_get。欄位包含 email、unconfirmed_email (電子郵件變更等待確認時會設定，否則為 null)、name (可為空)、theme (system、light 或 dark)、default_landing (sites 或 last_site)、locale (已登入應用程式的語言代碼)、timezone (IANA 名稱，可為空)、shortcuts_enabled、reduce_motion、product_emails、site_audit_emails、marketing_emails、newsletter (皆為布林值，true 代表已訂閱)、two_factor (布林值)、passkeys (已註冊的通行密鑰數量) 以及 created_at (ISO 8601)。僅透過工作區身分提供者開啟的工作階段只會看到 email 與顯示設定。

權限： member

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

更新已登入成員自己的個人資料、顯示偏好與電子郵件訂閱。只有您傳送的輸入會變更，其餘維持原樣。變更 email 不會立即生效。系統會向新地址寄送確認信（有頻率限制），在確認之前 unconfirmed_email 會顯示待確認的地址。API token 無法變更電子郵件地址，也無法在退訂後重新開啟 marketing_emails，這兩項都需要已登入的瀏覽器。允許關閉 marketing_emails。由工作區身分提供者開啟的工作階段只能變更顯示設定 (theme、default_landing、locale、timezone、shortcuts_enabled、reduce_motion)。回傳更新後的帳號，格式與 account_get 相同。此操作不會刪除帳號，也無法變更工作區設定。

權限： member

curl -X PATCH https://privatusanalytics.com/account.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 '{…}'

透過電子郵件邀請一位或多位成員加入工作區，並向每位寄出邀請信，內含有效期 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 token 會被撤銷，任何 SCIM 連結也會被移除。其筆記與過去的稽核項目會保留。擁有者無法被移除或離開，請先以 ownership_transfers_create 轉移擁有權。移除他人需要 members.manage，且您無法移除權限或網站比您更多的成員。離開不需要權限，但權限或網站受限的 token 無法用來離開。之後可以用 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 方案上搭配 roles_list 中 custom_role_id 的 custom)。擁有者的角色無法在此變更，請改用 ownership_transfers_create，且您無法編輯自己的成員資格，或層級高於您的成員。若要限制網站，請將 all_sites 設為 false 並搭配 site_ids (公開網站 ID pa_...)，再加上 include_future_sites 為 true 可一併授予之後建立的網站。將 all_sites 設為 true 可授予每個網站的存取權。對目前擁有所有網站的成員傳送 site_ids 清單卻沒有 all_sites 為 false，會產生錯誤。您無法授予比自己擁有更多的權限或網站。需要 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，這很難復原，因為只有新的擁有者才能轉回來。只有目前的擁有者可以呼叫，且 token 不得受限於特定網站或權限。membership_id 是新擁有者在 members_list 中的成員資格 uuid (不是使用者 ID 或電子郵件)，且對方必須已是成員，若不是請先邀請。新擁有者會取得 owner 角色與所有網站的存取權，且 owner 角色無法透過 members_update 授予。Free 工作區不能轉給已擁有另一個 Free 工作區的人。帳務會留在工作區。呼叫此操作的 token 需要 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（預設）會將所有已連接的搜尋引擎合併，position 依 impressions 加權，國家與裝置僅來自 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（百分比而非分數，兩位小數）與 position（平均排名，1 為最佳，未知時為 null），針對 query、page、country 與 device 的 breakdowns（value 加上相同四項指標的列）、landing_pages（熱門頁面，含 visits、以百分比表示的 bounce_rate 與 conversion_rate，以及 conversions）以及 opportunities（impressions 至少 100 且 CTR 低於 2% 的 low_ctr_queries，以及平均排名在 8 到 20 之間的 striking_distance 頁面）。國家值依服務提供者的回報而定。訪客資料請使用 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 '{…}'

權限： 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

來自真實訪客的 Web Vitals 報表。回傳 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}，最差且最繁忙的在前。以大寫字母指定 LCP、INP、CLS、FCP 或 TTFB 其中之一作為 metric (預設 LCP)。sample_rate 是回報 vitals 的造訪占比，因此計數是樣本數，並非所有造訪。接受共用的 period、compare、filters 與 segment 輸入。單一頁面的 vitals 請使用 pages_detail。

權限： analytics.read

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

回傳每個 API 操作的完整目錄，同時也是每個 MCP 工具。用來探索有哪些工具或端點，以及它們確切需要什麼。每個項目包含 tool_name、summary、description (可為空)、group、verb (HTTP 方法)、path (含佔位符的範本)、permission (成員或 token 所需的權限，公開工具為 null)、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>。章節總覽請使用 page "index"。

權限： public

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

列出公開方案 (free、pro、business 與 enterprise) 及其限制與價格級距，讓您能為 billing_checkout、billing_preview 與 billing_change_plan 挑選有效的值。每個方案包含 name、events (包含的每月事件數，分級或客製方案為 null)、badge_bonus (來自標章的額外每月事件數，僅限 Free，否則為 null)、limits (方案限制的物件，如網站、成員席位、歷史保留月數、每個網站的目標、AI 提問，以及每小時 API 請求數)、tiers (各含每月事件數，以及以整數美元表示的月費與年費，已含 VAT 或銷售稅) 與 contact_sales (客製方案為 true)。meta 物件會加上 currency、年費的說明、counted (哪些算作計費事件) 與 not_counted。若要查看單一工作區自己的方案，請使用 billing_get。公開，無需驗證。

權限： public

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

回報網站蜜罐頁面上的點擊。蜜罐頁面是只能透過隱藏連結到達的頁面，並依應用程式中進階機器人偵測頁面的說明設置。這些點擊來自機器人，因此絕不會算作瀏覽量或造訪，也不會出現在 stats_overview 或 stats_breakdown 中。以 period (7d、30d (預設)、90d 或 12mo) 選擇範圍。點擊會保留 12 個月。結果包含 period、from (範圍的起點)、has_data (在第一次點擊之前為 false)、totals (hits、不重複頁面、automated (追蹤程式碼偵測到自動化瀏覽器的點擊) 以及 no_interaction (沒有指標、按鍵或觸控輸入的點擊))、pages (最多 50 列，含 path、hits 與 last_hit_at)、reasons (依標準機器人篩選結果分類的點擊數：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"

將一個模式加入網站的封鎖或允許清單之一。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 指定。只有您傳送的輸入會變更。清單無法變更，若要移到另一個清單，請刪除後重新建立規則。模式必須對其清單保持有效 (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 '{…}'

建立漏斗，也就是造訪所經過的一連串步驟，並以每次造訪為單位衡量。傳入 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 token 以及從 Cloudflare 匯入的每一筆爬蟲點擊，且無法復原。來自傳送的伺服器記錄的點擊會保留。該 token 仍存在於您的 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 (每個類別的點擊數，忽略 category 篩選)、crawlers (最多 50 列，含 crawler、category、hits、paths)、series (每天的標籤與前 8 名爬蟲的每日點擊數)、top_paths (前 8 名爬蟲各自最常被擷取的 10 個路徑)、has_data (在出現任何點擊之前為 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 token。使用 API token 的請求則不需要。

權限： 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，不帶前綴)。需要 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 '{…}'

將此表單獎勵的標題、文字、代碼和開關狀態，複製到 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 '{…}'

封存目標。已封存的目標會從報表中隱藏，不計入方案的目標數量上限，並保留其定義，因此之後可以用 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 包含依轉換數排名的前 10 名，涵蓋 channel、utm_campaign、entry_page、country 與 device，各為 {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 '{…}'

私人意見回饋是指在開啟低評分導向的表單上（Business 方案以上），評分為 1 到 3 的回覆。它絕不是見證，絕不公開，也絕不計數。

權限： 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"

以備註結案，並讓見證繼續顯示在原處。不會刪除任何內容，也不會寄信給提出請求的人。備註為必填。已決定的請求會以 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"

回傳工作區的稽核紀錄，這是一份最新的在前、分頁的紀錄，記載誰變更了什麼（設定、成員、網站、目標、token 等）。需要 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 token，瀏覽器工作階段則為 null)、changes (將每個變更欄位對應到 [前, 後] 組合的物件，已移除密鑰)，以及 ip (成員或 API 用戶端使用的位址，未知時為 null)。同一份紀錄的 CSV 匯出僅能在應用程式中使用。

權限： workspace.manage

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

在清單末尾新增自訂管道規則，因此它會在所有既有規則之後執行，而內建分類只在沒有規則符合時才適用。channel 是要指派的名稱（最多 32 個字元，例如 Partners）。conditions 是非空的物件清單，包含 field (referrer_host、utm_source、utm_medium、utm_campaign、ref 或 path)、operator (is、contains、starts_with 或 regex) 與 value。所有條件都必須符合，規則才會套用，且比對不分大小寫。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 '{…}'

依評估順序（位置 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 '{…}'

不可逆地刪除網站在某個日期範圍內的瀏覽量、自訂事件與造訪，且無法復原。用來清除測試流量或移除有問題的期間。它不會刪除網站、其目標或設定 (網站請使用 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、設定、目標與資料，但各成員的存取授權會被清除，其分享連結會移到新的工作區。如果邀請已不再待處理或已過期、目的地已達其方案的網站上限，或已有相同網域的有效網站，則會失敗。移動無法復原，除非轉回去。呼叫此操作的 token 必須屬於目的地工作區並具有 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 token。回傳 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 '{…}'

停止網站正在執行或排隊中的稽核。該稽核會被標記為已取消，未完成的爬取不會回報任何內容。已取消的稽核不會用掉 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、錯誤、警告與提示的計數、pages_crawled、page_limit、capped、摘要與 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"

列出 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

已發布的產品更新，最新的在前。也提供 RSS，位於 /changelog.rss。

權限： public

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

瀏覽器用戶端會以 `cf-turnstile-response` 傳送 Cloudflare Turnstile token。使用 API token 的請求則不需要。

權限： 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 token。使用 API token 的請求則不需要。

權限： 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，會加上一句說明已遵守 Do Not Track 與 Global Privacy Control)。回傳 site_name、paragraphs (字串陣列)、text (以空白行連接的段落，名稱後的括號內附上 Privatus Analytics 的網址) 與 html (以 <p> 元素呈現的段落，名稱為一般連結)。文字以請求的語言撰寫，預設為英文。它不會變更任何帳號。公開，無需驗證。

權限： public

curl https://privatusanalytics.com/tools/privacy-policy-generator.json

產生 QR 碼的 SVG 圖片，供列印或海報使用。可搭配 tools_utm_builder 產生、帶有 UTM 參數的連結。輸入為 text (URL 或文字，最多 1,000 個字元) 與 level (錯誤更正等級 l、m、q 或 h，預設 m，越高越能承受損壞，但需要更密集的碼)。回傳 text、level、size (每邊的模組數) 與 svg (獨立的 SVG 文件，白底黑碼)。對所選等級而言過長的文字會被拒絕。若要為追蹤的短連結產生 QR 碼，請改用 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 token。使用 API token 的請求則不需要。

權限： 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"

針對一個工作區（路徑帶入 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 仍支援的最舊行動 App 版本）。行動 App 在開啟工作區時讀取一次，這樣就能將方案不含的報表顯示為未包含，而不必再去請求。需要 analytics.read。

權限： analytics.read · 僅限 HTTP（不是 MCP 工具）

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

移除目前呼叫的行動 App 登入的推播註冊，裝置就不會再收到推播。登入本身會保留，App 可以再次註冊。登出（以更新權杖 POST /oauth/revoke）也會移除註冊。只有行動 App 的權杖可以呼叫。

權限： member · 僅限 HTTP（不是 MCP 工具）

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

回傳目前呼叫的行動 App 登入所屬的裝置：registered（App 註冊推播權杖前為 false）、platform、locale、timezone、app_version、kinds（所有推播類型）、muted_kinds 和 muted_site_ids（使用者關閉的項目）。只有行動 App 的權杖可以呼叫。

權限： member · 僅限 HTTP（不是 MCP 工具）

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

為目前呼叫的行動 App 登入所屬的裝置註冊推播通知，或變更其接收的內容。只有你傳送的輸入會變更。第一次呼叫需要 platform 和 push_token。裝置會收到以下推播：uptime（檢查失敗或恢復）、alert（警示觸發或解除）、site_audit（網站稽核完成）、experiment（實驗有結果或已結束）和 usage（每月額度即將用完或已用完），涵蓋其成員可開啟的每個網站，且適用於所有方案。muted_kinds 和 muted_site_ids 用來關閉類型和網站，兩者都會取代整份清單。註冊另一個 App 登入已持有的推播權杖時，該權杖會移到這個登入。只有行動 App 的權杖可以呼叫。這是此類權杖可執行的兩項寫入操作之一。

權限： member · 僅限 HTTP（不是 MCP 工具）

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

記錄單一行銷活動在單一月份的廣告支出，讓 campaigns_list 能顯示單次獲客成本與廣告投資報酬率。如果相同行銷活動與月份的項目已存在，會被取代而不是重複，因此重複呼叫兩次也是安全的。campaign 是您追蹤連結中出現的 utm_campaign 值，month 為 YYYY-MM (也接受 2026-09-15 這類完整日期，並會對齊到該月的第一天)，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，大寫)、格式為 YYYY-MM 的 month，以及項目 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 (可用的預設值)。值會被清理為不含空格的小寫。使用 campaigns_hygiene 可找出您的流量中已存在的雜亂 UTM 值，使用 campaigns_list 可回報已執行過的行銷活動。若想保留附有短網址與點擊計數的標記連結，請改用 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 清理名稱，使用 stats_breakdown 搭配 dimension utm_campaign 取得單純的流量拆分。

權限： 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 參數的 destination，destination 中已有的 UTM 參數會被取代。QR 碼請使用 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 參數、可直接分享的 destination)、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 的 QR 碼，供列印使用。回應包含 link_id、url (編碼在 QR 碼中的標記 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 的可列印 QR 碼，請使用 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

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

變更步驟、問題或同意聲明用語會提高表單的版本，每筆同意紀錄都會儲存該版本。變更 slug 後，舊連結仍會重新導向。請把 questions 作為完整清單傳送。

權限： content.write

curl -X PATCH https://privatusanalytics.com/sites/:site_id/testimonials/forms/: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"

針對指定期間建立 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"

平台會從連結偵測。執行找到的內容會在審核步驟（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"

一次清除所有顏色、字型、半徑、評分樣式、標誌和自訂 CSS，每個表單、小工具和牆也會隨之改變。此動作無法復原，因此會將助理導向「品牌套件」頁面，而不是直接執行。

權限： 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 '{…}'

每次執行最多 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。帶有 text_too_long 的 422 表示文字放不下：請使用 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 '{…}'

此動作無法復原。單一項目時，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 '{…}'

有兩種方式。要上傳，請傳送 filename、content_type 和 byte_size：回應會包含 upload，其中有用來 PUT 檔案的 url、隨附傳送的標頭，以及大型檔案可逐一傳送的分段。接著呼叫 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"

個人檢視只需要 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 '{…}'

最新的在前。每筆紀錄都會說明執行了什麼、由誰執行、變更與略過了多少以及原因，以及可復原到何時。

權限： 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 '{…}'

每個詞彙都附有包含它的見證數量、占比、這些見證的平均評分，以及最近 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 '{…}'

一次最多 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 連接的欄位、運算子和值所組成的資料列。回應會包含數量和以簡明英文描述的規則，因此一次呼叫就能把一句話變成會自動更新的收藏集。請先用 testimonial_collections_preview 試試規則。類型之後不會變更。

權限： 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 會取代智慧收藏集的每條規則。類型是固定的。

權限： 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 '{…}'

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 '{…}'

請先呼叫 testimonial_translations_estimate。這會將所選見證的內容、標題和重點句傳送到 Google Cloud Translation（絕不包含姓名、電子郵件或公司），並會以電子郵件通知成員是由助理啟動的。翻譯在背景進行，已儲存的列絕不會再次擷取。達到本月的字元配額時，其餘部分會儲存為等候中，並於 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 '{…}'

一個網站最多可有 20 個啟用中的屬性。鍵一旦建立就固定不變，因為表單連結、規則和 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 是鍵。被智慧收藏集或自動標記規則使用的屬性，在它們仍在使用時無法刪除。封存是停用屬性的日常做法。

權限： 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 '{…}'

每個屬性都會說明其鍵、類型和選項、有多少見證有值（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 '{…}'

見證的自訂網域由 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 '{…}'

只有團隊尚未開始處理的請求（status 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 '{…}'

牆或表單上每個主機名稱的請求，最新的在前，附有其狀態。主機名稱要在 status 為 active 後才會生效。所有方案皆適用，因此先前的請求仍可閱讀。

權限： analytics.read

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

試算表匯入的步驟 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 '{…}'

預設語言、提供的語言、新核准的見證是否自動翻譯、方案是否包含翻譯、翻譯是否已設定，以及本月已使用和剩餘的字元數。

權限： 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，並會以電子郵件通知成員是由助理變更了這項設定。

權限： 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 天後的一封後續郵件、以網站名稱作為寄件者，以及以您作為回覆地址。每位收件人會儲存為 queued，或附上原因儲存為 skipped。

權限： 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"

從停止的地方繼續。停止期間到期的後續郵件會從現在重新計時，因此不會一次全部寄出。這會寄信給工作區以外的人，因此會以電子郵件通知成員是由助理恢復的。

權限： 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 日恢復寄送。這會寄信給工作區以外的人，因此會以電子郵件通知成員是由助理寄出的。

權限： 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 '{…}'