Analytics REST API
The Privatus Analytics REST API: add .json to any app URL and send a token. Conventions and a reference of every operation, generated from the code.
Every page and action in Privatus Analytics is also an API endpoint. There's no
separate /api/v1: add .json to a URL and send an API token.
sh
curl https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/stats/aggregate.json?period=7d \
-H "Authorization: Bearer $PRIVATUS_TOKEN"
json
{
"data": {
"period": { "from": "2026-09-23T00:00:00Z", "to": "2026-09-30T00:00:00Z" },
"metrics": {
"visitors": 1840, "visits": 2310, "pageviews": 5122,
"views_per_visit": 2.22, "bounce_rate": 41.3,
"visit_duration": 48000, "revenue": 129900
}
}
}
The reference below lists every operation with its method, path, permission, input schema and response schema. It's generated from the running code, as is the OpenAPI 3.1 document, so neither can drift from what the server does. The same operations are MCP tools.
Conventions#
| Base URL | https://privatusanalytics.com |
| Format | JSON. Add .json to the path (or send Accept: application/json) |
| Auth | Authorization: Bearer pat_… (Authentication) |
| Ids | Public ids with a prefix: ws_… workspaces, pa_… sites, seg_… segments, wh_… webhooks |
| Reads | GET with query parameters |
| Writes | POST, PATCH, DELETE with a JSON body of flat fields |
| Success | { "data": … }, plus "meta" for lists |
| Errors | { "error": { "code", "message", "details" } } (Errors) |
| Lists | page and per_page (max 100) (Pagination) |
| Times | ISO 8601 in UTC. Date parameters (from, to) are days in the site's timezone |
| Money | Minor units (cents) in the site currency, e.g. revenue: 129900 = 1,299.00 |
| Durations | Milliseconds |
Common tasks#
| Task | Operation |
|---|---|
| List workspaces | GET /workspaces.json |
| List sites | GET /workspaces/{workspace_id}/sites.json |
| Headline metrics | GET /sites/{site_id}/stats/aggregate.json |
| Chart data | GET /sites/{site_id}/stats/timeseries.json |
| Top pages, sources, countries… | GET /sites/{site_id}/breakdown/{dimension}.json |
| Everything on the Overview | GET /sites/{site_id}/overview.json |
| Live visitors | GET /sites/{site_id}/live.json |
| Add a note (e.g. a deploy) | POST /sites/{site_id}/notes.json |
See Stats endpoints and Examples.
In this section#
Authentication · Errors · Pagination · Rate limits · Filters · Stats endpoints · Examples · Webhooks · Changelog and deprecation
Sending data in is a different API: see Server-side ingest.
所有操作
驗證
傳送 Authorization: Bearer pat_…。請在工作區設定的 API token 中建立 token。驗證指南。
處處都是 JSON
在任何路徑後加上 .json。回應格式為 { "data": … }，錯誤格式為 { "error": { "code", "message" } }。錯誤。
MCP
使用相同的 token 將 JSON-RPC POST 到 https://privatusanalytics.com/mcp。下方每個操作都是一個工具。MCP 指南。
下載 openapi.json · 285 個操作
API token
POST
/workspaces/:workspace_id/api_tokens.json
建立 API token（token 僅顯示一次）
api_tokens_create
權限： member
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/api_tokens.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "用來辨識此 token 的名稱",
"examples": [
"CI deploys"
]
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"analytics.read",
"analytics.export",
"content.write",
"sites.manage",
"uptime.manage",
"members.manage",
"tokens.manage",
"billing.manage",
"workspace.manage"
]
},
"description": "權限（省略則為您的全部權限，空清單會被拒絕）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "限制為這些網站 id（pa_…）。留空 = 全部",
"default": []
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "到期時間（ISO 8601）。留空 = 永不過期"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
},
"description": "只接受來自這些 IP 或 CIDR 的請求",
"default": []
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"token": {
"anyOf": [
{
"type": "string",
"description": "token 本身：僅在建立時回傳"
},
{
"type": "null"
}
]
},
"token_prefix": {
"type": "string",
"description": "開頭的字元，用來辨識 token"
},
"owner": {
"type": "string",
"description": "擁有者成員的電子郵件"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "限制為這些網站（空 = 全部）"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
}
},
"oauth_client": {
"anyOf": [
{
"type": "string",
"description": "取得它的 MCP 用戶端"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "active、expired 或 revoked"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/api_tokens/:id.json
撤銷 API token
api_tokens_delete
權限： member
範例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/api_tokens/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"token": {
"anyOf": [
{
"type": "string",
"description": "token 本身：僅在建立時回傳"
},
{
"type": "null"
}
]
},
"token_prefix": {
"type": "string",
"description": "開頭的字元，用來辨識 token"
},
"owner": {
"type": "string",
"description": "擁有者成員的電子郵件"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "限制為這些網站（空 = 全部）"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
}
},
"oauth_client": {
"anyOf": [
{
"type": "string",
"description": "取得它的 MCP 用戶端"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "active、expired 或 revoked"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/api_tokens.json
列出 API token
api_tokens_list
權限： member
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/api_tokens.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"include_revoked": {
"type": "boolean",
"description": "同時列出已撤銷和已過期的 token",
"default": false
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"token": {
"anyOf": [
{
"type": "string",
"description": "token 本身：僅在建立時回傳"
},
{
"type": "null"
}
]
},
"token_prefix": {
"type": "string",
"description": "開頭的字元，用來辨識 token"
},
"owner": {
"type": "string",
"description": "擁有者成員的電子郵件"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "限制為這些網站（空 = 全部）"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
}
},
"oauth_client": {
"anyOf": [
{
"type": "string",
"description": "取得它的 MCP 用戶端"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "active、expired 或 revoked"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
SCIM
POST
/scim/v2/Users.json
佈建使用者
scim_users_create
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/scim/v2/Users.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"userName": {
"type": "string",
"description": "電子郵件地址"
},
"name": {
"type": "object",
"additionalProperties": true,
"description": "givenName、familyName、formatted",
"default": {}
},
"active": {
"type": "boolean",
"description": "工作區成員",
"default": true
}
},
"required": [
"userName"
]
}
回應資料
{
"type": "object"
}
DELETE
/scim/v2/Users/:id.json
取消佈建使用者
scim_users_delete
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X DELETE https://privatusanalytics.com/scim/v2/Users/:id.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object"
}
GET
/scim/v2/Users.json
列出已佈建的使用者
scim_users_list
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl https://privatusanalytics.com/scim/v2/Users.json輸入
{
"type": "object",
"properties": {
"scim_filter": {
"type": "string",
"description": "SCIM 篩選條件（查詢參數 `filter`），例如 userName eq \"[email protected]\""
},
"startIndex": {
"type": "integer",
"description": "第一筆結果的索引（從 1 開始）",
"default": 1
},
"count": {
"type": "integer",
"description": "每頁大小（最多 200）",
"default": 100
}
},
"required": []
}
回應資料
{
"type": "object"
}
GET
/scim/v2/Users/:id.json
取得已佈建的使用者
scim_users_get
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl https://privatusanalytics.com/scim/v2/Users/:id.json輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object"
}
PATCH
/scim/v2/Users/:id.json
更新使用者（PATCH active、name）
scim_users_update
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X PATCH https://privatusanalytics.com/scim/v2/Users/:id.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"Operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "SCIM PatchOp 操作"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"Operations",
"id"
]
}
回應資料
{
"type": "object"
}
SSO
POST
/workspaces/:workspace_id/sso/activate.json
啟用已測試的 SSO 設定
sso_activate
權限： workspace.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/activate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml 或 oidc"
},
"status": {
"type": "string",
"description": "draft、testing、tested 或 active"
},
"enforced": {
"type": "boolean",
"description": "SSO 是唯一的登入方式（擁有者除外）"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "已驗證的電子郵件網域"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
POST
/workspaces/:workspace_id/sso/deactivate.json
關閉 SSO（回到草稿）
sso_deactivate
權限： workspace.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/deactivate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml 或 oidc"
},
"status": {
"type": "string",
"description": "draft、testing、tested 或 active"
},
"enforced": {
"type": "boolean",
"description": "SSO 是唯一的登入方式（擁有者除外）"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "已驗證的電子郵件網域"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
POST
/workspaces/:workspace_id/sso/scim_token.json
產生新的 SCIM token（僅顯示一次）
sso_scim_token
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object"
}
GET
/workspaces/:workspace_id/sso.json
取得 SSO 設定
sso_get
權限： workspace.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/sso.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml 或 oidc"
},
"status": {
"type": "string",
"description": "draft、testing、tested 或 active"
},
"enforced": {
"type": "boolean",
"description": "SSO 是唯一的登入方式（擁有者除外）"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "已驗證的電子郵件網域"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
PATCH
/workspaces/:workspace_id/sso.json
建立或更新 SSO 設定
sso_update
權限： workspace.manage
範例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/sso.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml 或 oidc",
"enum": [
"saml",
"oidc"
]
},
"idp_sso_url": {
"type": "string",
"description": "SAML：IdP 單一登入 URL"
},
"idp_entity_id": {
"type": "string",
"description": "SAML：IdP entity id（issuer）"
},
"idp_cert": {
"type": "string",
"description": "SAML：IdP X.509 簽署憑證（PEM）"
},
"oidc_issuer": {
"type": "string",
"description": "OIDC：issuer URL（discovery）"
},
"oidc_client_id": {
"type": "string",
"description": "OIDC：client id"
},
"oidc_client_secret": {
"type": "string",
"description": "OIDC：client secret（唯寫）"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "使用此 SSO 的已驗證電子郵件網域"
},
"default_role": {
"type": "string",
"description": "由 JIT 或 SCIM 建立之成員的角色",
"enum": [
"admin",
"editor",
"analyst",
"viewer",
"billing"
]
},
"jit_provisioning": {
"type": "boolean",
"description": "在首次 SSO 登入時建立成員"
},
"enforced": {
"type": "boolean",
"description": "僅允許 SSO 登入（需要啟用中的設定）"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml 或 oidc"
},
"status": {
"type": "string",
"description": "draft、testing、tested 或 active"
},
"enforced": {
"type": "boolean",
"description": "SSO 是唯一的登入方式（擁有者除外）"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "已驗證的電子郵件網域"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
Uptime
POST
/sites/:site_id/uptime.json
為網站新增 uptime 檢查
uptime_checks_create
權限： uptime.manage
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "顯示名稱（預設為目標）"
},
"kind": {
"type": "string",
"description": "http（狀態碼）、keyword（內文包含）、tcp（host:port）或 dns（名稱可解析）",
"enum": [
"http",
"keyword",
"tcp",
"dns"
],
"default": "http"
},
"url": {
"type": "string",
"description": "http/keyword 檢查的網址",
"examples": [
"https://example.com/health"
]
},
"host": {
"type": "string",
"description": "tcp/dns 檢查的主機名稱"
},
"port": {
"type": "integer",
"description": "tcp 檢查的 TCP 連接埠"
},
"keyword": {
"type": "string",
"description": "回應內文必須包含的文字（keyword）"
},
"expected_status": {
"type": "integer",
"description": "預期的 HTTP 狀態碼",
"default": 200
},
"http_method": {
"type": "string",
"description": "HTTP 方法",
"enum": [
"GET",
"HEAD"
],
"default": "GET"
},
"interval_seconds": {
"type": "integer",
"description": "檢查之間的秒數（適用方案下限，預設 300 或下限）"
},
"timeout_seconds": {
"type": "integer",
"description": "探測逾時前的秒數（1-30）",
"default": 20
},
"public": {
"type": "boolean",
"description": "可顯示在公開狀態頁面",
"default": false
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "檢查 id（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "檢查所屬的網站"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可顯示在狀態頁面"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/uptime/checks/:id.json
刪除 uptime 檢查及其歷史記錄
uptime_checks_delete
權限： uptime.manage
範例
curl -X DELETE https://privatusanalytics.com/uptime/checks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "檢查 id（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "檢查所屬的網站"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可顯示在狀態頁面"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/uptime.json
列出網站的 uptime 檢查
uptime_checks_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "僅此狀態的檢查",
"enum": [
"up",
"down",
"pending",
"paused"
]
},
"query": {
"type": "string",
"description": "依名稱或目標篩選"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "檢查 id（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "檢查所屬的網站"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可顯示在狀態頁面"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/uptime/checks/:id/pause.json
暫停 uptime 檢查
uptime_checks_pause
權限： uptime.manage
範例
curl -X POST https://privatusanalytics.com/uptime/checks/:id/pause.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "檢查 id（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "檢查所屬的網站"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可顯示在狀態頁面"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/uptime/checks/:id/resume.json
恢復已暫停的 uptime 檢查
uptime_checks_resume
權限： uptime.manage
範例
curl -X POST https://privatusanalytics.com/uptime/checks/:id/resume.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "檢查 id（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "檢查所屬的網站"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可顯示在狀態頁面"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/uptime/checks/:id.json
取得 uptime 檢查：24 小時、7 天、30 天的 uptime、回應時間與事件
uptime_checks_get
權限： analytics.read
範例
curl https://privatusanalytics.com/uptime/checks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"range": {
"type": "string",
"description": "回應時間圖表的時間範圍",
"enum": [
"24h",
"7d",
"30d"
],
"default": "24h"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"check": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "檢查 id（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "檢查所屬的網站"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可顯示在狀態頁面"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
},
"uptime": {
"type": "object",
"description": "24 小時、7 天與 30 天的 uptime %"
},
"range": {
"type": "string",
"description": "response_times 的時間範圍"
},
"response_times": {
"type": "object",
"description": "每個區間的平均回應毫秒數：{unit, labels, series: {location: [ms…]}}"
},
"incidents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"started_at": {
"type": "string",
"format": "date-time"
},
"resolved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"duration_seconds": {
"type": "integer",
"description": "若仍未結束，則為目前為止的秒數"
},
"cause": {
"anyOf": [
{
"type": "string",
"description": "最常見的錯誤，例如 timeout 或 status_503"
},
{
"type": "null"
}
]
},
"failed_locations": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
PATCH
/uptime/checks/:id.json
變更 uptime 檢查
uptime_checks_update
權限： uptime.manage
範例
curl -X PATCH https://privatusanalytics.com/uptime/checks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "顯示名稱（預設為目標）"
},
"kind": {
"type": "string",
"description": "http（狀態碼）、keyword（內文包含）、tcp（host:port）或 dns（名稱可解析）",
"enum": [
"http",
"keyword",
"tcp",
"dns"
]
},
"url": {
"type": "string",
"description": "http/keyword 檢查的網址",
"examples": [
"https://example.com/health"
]
},
"host": {
"type": "string",
"description": "tcp/dns 檢查的主機名稱"
},
"port": {
"type": "integer",
"description": "tcp 檢查的 TCP 連接埠"
},
"keyword": {
"type": "string",
"description": "回應內文必須包含的文字（keyword）"
},
"expected_status": {
"type": "integer",
"description": "預期的 HTTP 狀態碼"
},
"http_method": {
"type": "string",
"description": "HTTP 方法",
"enum": [
"GET",
"HEAD"
]
},
"interval_seconds": {
"type": "integer",
"description": "檢查之間的秒數（適用方案下限，預設 300 或下限）"
},
"timeout_seconds": {
"type": "integer",
"description": "探測逾時前的秒數（1-30）"
},
"public": {
"type": "boolean",
"description": "可顯示在公開狀態頁面"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "檢查 id（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "檢查所屬的網站"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可顯示在狀態頁面"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/uptime/probes.json
探測的資料中心、User-Agent 與出口 IP 範圍（用於將我們的 uptime 探測加入允許清單）
uptime_probes_list
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl https://privatusanalytics.com/uptime/probes.json輸入
{
"type": "object",
"properties": {},
"required": []
}
回應資料
{
"type": "object"
}
POST
/uptime/probes/results.json
提交外部探測代理的結果（Bearer uptime probe token）
uptime_probes_results
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/uptime/probes/results.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"check_id": {
"type": "string"
},
"location": {
"type": "string"
},
"ok": {
"type": "boolean"
},
"status_code": {
"type": "integer"
},
"response_ms": {
"type": "integer"
},
"error": {
"type": "string"
},
"checked_at": {
"type": "string",
"format": "date-time"
}
}
},
"description": "探測結果：[{check_id, location, ok, status_code, response_ms, error, checked_at}]"
}
},
"required": [
"results"
]
}
回應資料
{
"type": "object"
}
POST
/workspaces/:workspace_id/uptime.json
新增工作區 uptime 檢查（不綁定網站）
workspace_uptime_checks_create
權限： uptime.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "顯示名稱（預設為目標）"
},
"kind": {
"type": "string",
"description": "http（狀態碼）、keyword（內文包含）、tcp（host:port）或 dns（名稱可解析）",
"enum": [
"http",
"keyword",
"tcp",
"dns"
],
"default": "http"
},
"url": {
"type": "string",
"description": "http/keyword 檢查的網址",
"examples": [
"https://example.com/health"
]
},
"host": {
"type": "string",
"description": "tcp/dns 檢查的主機名稱"
},
"port": {
"type": "integer",
"description": "tcp 檢查的 TCP 連接埠"
},
"keyword": {
"type": "string",
"description": "回應內文必須包含的文字（keyword）"
},
"expected_status": {
"type": "integer",
"description": "預期的 HTTP 狀態碼",
"default": 200
},
"http_method": {
"type": "string",
"description": "HTTP 方法",
"enum": [
"GET",
"HEAD"
],
"default": "GET"
},
"interval_seconds": {
"type": "integer",
"description": "檢查之間的秒數（適用方案下限，預設 300 或下限）"
},
"timeout_seconds": {
"type": "integer",
"description": "探測逾時前的秒數（1-30）",
"default": 20
},
"public": {
"type": "boolean",
"description": "可顯示在公開狀態頁面",
"default": false
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "檢查 id（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "檢查所屬的網站"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可顯示在狀態頁面"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/uptime.json
列出工作區中的所有 uptime 檢查
workspace_uptime_checks_list
權限： analytics.read
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "僅此狀態的檢查",
"enum": [
"up",
"down",
"pending",
"paused"
]
},
"query": {
"type": "string",
"description": "依名稱或目標篩選"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "檢查 id（upc_…）"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "檢查所屬的網站"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http、keyword、tcp 或 dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up、down、pending 或 paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "可顯示在狀態頁面"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
Webhook
GET
/workspaces/:workspace_id/webhooks/:webhook_id/deliveries.json
列出某個 webhook 的傳送記錄
webhook_deliveries_list
權限： workspace.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:webhook_id/deliveries.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "僅成功或失敗的傳送",
"enum": [
"succeeded",
"failed"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"webhook_id": {
"type": "string",
"description": "資源的 Webhook"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id",
"webhook_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "傳送 id，例如 whd_123"
},
"event": {
"type": "string"
},
"status": {
"type": "string",
"description": "pending、succeeded 或 failed"
},
"status_code": {
"anyOf": [
{
"type": "integer",
"description": "最後一次嘗試的 HTTP 狀態"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "最後一次嘗試的連線錯誤"
},
{
"type": "null"
}
]
},
"attempt": {
"type": "integer"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"payload": {
"type": "object"
},
"response_body": {
"anyOf": [
{
"type": "string",
"description": "前 2,000 個字元"
},
{
"type": "null"
}
]
},
"delivered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/workspaces/:workspace_id/webhooks/:webhook_id/deliveries/:id/redeliver.json
重新傳送
webhook_deliveries_redeliver
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"webhook_id": {
"type": "string",
"description": "資源的 Webhook"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"webhook_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "傳送 id，例如 whd_123"
},
"event": {
"type": "string"
},
"status": {
"type": "string",
"description": "pending、succeeded 或 failed"
},
"status_code": {
"anyOf": [
{
"type": "integer",
"description": "最後一次嘗試的 HTTP 狀態"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "最後一次嘗試的連線錯誤"
},
{
"type": "null"
}
]
},
"attempt": {
"type": "integer"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"payload": {
"type": "object"
},
"response_body": {
"anyOf": [
{
"type": "string",
"description": "前 2,000 個字元"
},
{
"type": "null"
}
]
},
"delivered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/webhooks.json
新增 webhook 端點
webhooks_create
權限： workspace.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/webhooks.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "接收 POST JSON 的 HTTPS 端點",
"examples": [
"https://example.com/hooks/privatus"
]
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"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"
]
},
"description": "要傳送的事件"
},
"enabled": {
"type": "boolean",
"description": "傳送",
"default": true
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"url",
"events",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook id，例如 wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active、failing 或 disabled"
},
"secret": {
"type": "string",
"description": "Privatus-Signature 的簽署密鑰"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/webhooks/:id.json
刪除 webhook
webhooks_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook id，例如 wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active、failing 或 disabled"
},
"secret": {
"type": "string",
"description": "Privatus-Signature 的簽署密鑰"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/webhooks.json
列出 webhook
webhooks_list
權限： workspace.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook id，例如 wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active、failing 或 disabled"
},
"secret": {
"type": "string",
"description": "Privatus-Signature 的簽署密鑰"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/workspaces/:workspace_id/webhooks/:id.json
取得 webhook
webhooks_get
權限： workspace.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook id，例如 wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active、failing 或 disabled"
},
"secret": {
"type": "string",
"description": "Privatus-Signature 的簽署密鑰"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/webhooks/:id/test.json
傳送測試
webhooks_test
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "傳送 id，例如 whd_123"
},
"event": {
"type": "string"
},
"status": {
"type": "string",
"description": "pending、succeeded 或 failed"
},
"status_code": {
"anyOf": [
{
"type": "integer",
"description": "最後一次嘗試的 HTTP 狀態"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "最後一次嘗試的連線錯誤"
},
{
"type": "null"
}
]
},
"attempt": {
"type": "integer"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"payload": {
"type": "object"
},
"response_body": {
"anyOf": [
{
"type": "string",
"description": "前 2,000 個字元"
},
{
"type": "null"
}
]
},
"delivered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/workspaces/:workspace_id/webhooks/:id.json
更新 webhook（事件、URL、啟用、輪換密鑰）
webhooks_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "HTTPS 端點"
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"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"
]
},
"description": "要傳送的事件"
},
"enabled": {
"type": "boolean",
"description": "傳送"
},
"rotate_secret": {
"type": "boolean",
"description": "取代簽署密鑰",
"default": false
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook id，例如 wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active、failing 或 disabled"
},
"secret": {
"type": "string",
"description": "Privatus-Signature 的簽署密鑰"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
事件
GET
/sites/:site_id/events/properties.json
列出過去 30 天內出現的事件屬性鍵
event_properties_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/events/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "僅此原始事件名稱上出現的鍵"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
PATCH
/sites/:site_id/events/properties.json
重新命名或隱藏事件屬性鍵
event_properties_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "儲存的屬性鍵，例如 plan"
},
"display_name": {
"type": "string",
"description": "改為顯示的標籤（留空則移除）"
},
"hidden": {
"type": "boolean",
"description": "在報告中隱藏此鍵"
},
"export_safe": {
"type": "boolean",
"description": "此鍵不含個人資料，因此會包含在原始匯出與資料倉儲同步中"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"key",
"site_id"
]
}
回應資料
{
"type": "object"
}
DELETE
/sites/:site_id/events.json
刪除事件及其歷史記錄（在背景執行，輸入名稱以確認）
events_delete
權限： sites.manage
範例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/events.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "要刪除的原始事件名稱"
},
"confirm": {
"type": "string",
"description": "再次輸入事件名稱以確認"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"confirm",
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/events.json
列出事件，含完成次數、造訪數、轉換率及首次與最後出現時間
events_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/events.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"search": {
"type": "string",
"description": "僅名稱包含此文字的事件"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
POST
/sites/:site_id/events/merge.json
將多個事件合併為一個顯示名稱
events_merge
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"names": {
"type": "array",
"items": {
"type": "string"
},
"description": "要合併的原始事件名稱"
},
"into": {
"type": "string",
"description": "合併後事件的顯示名稱",
"examples": [
"Signup"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"names",
"into",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "追蹤器傳送的原始事件名稱"
},
"display_name": {
"anyOf": [
{
"type": "string",
"description": "報告中顯示的名稱"
},
{
"type": "null"
}
]
},
"hidden": {
"type": "boolean",
"description": "在報告中隱藏"
},
"currency": {
"anyOf": [
{
"type": "string",
"description": "營收貨幣"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/events/detail.json
單一事件：圖表、屬性樞紐分析、數值屬性彙總、頁面與來源
events_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/events/detail.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"name": {
"type": "string",
"description": "顯示的事件名稱（重新命名後）",
"examples": [
"Signup"
]
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "最多 3 個用來樞紐分析的屬性鍵",
"default": []
},
"interval": {
"type": "string",
"description": "圖表區間大小",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"site_id"
]
}
回應資料
{
"type": "object"
}
PATCH
/sites/:site_id/events/settings.json
重新命名、隱藏或取消隱藏事件，或設定其貨幣
events_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "追蹤器傳送的原始事件名稱",
"examples": [
"signup_click"
]
},
"display_name": {
"type": "string",
"description": "改為顯示的名稱（留空則移除重新命名）"
},
"hidden": {
"type": "boolean",
"description": "在報告中隱藏（資料會保留）"
},
"currency": {
"type": "string",
"description": "此事件營收的貨幣（ISO 4217）"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "追蹤器傳送的原始事件名稱"
},
"display_name": {
"anyOf": [
{
"type": "string",
"description": "報告中顯示的名稱"
},
{
"type": "null"
}
]
},
"hidden": {
"type": "boolean",
"description": "在報告中隱藏"
},
"currency": {
"anyOf": [
{
"type": "string",
"description": "營收貨幣"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
備註
POST
/sites/:site_id/notes.json
為網站新增備註（發版 webhook 請使用來源 "deploy"）
notes_create
權限： content.write
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "備註的日期（網站時區）。預設為今天"
},
"end_date": {
"type": "string",
"format": "date",
"description": "日期範圍的最後一天"
},
"title": {
"type": "string",
"description": "顯示在圖表上的簡短標題",
"examples": [
"Launched new pricing"
]
},
"body": {
"type": "string",
"description": "詳細內容（Markdown）"
},
"url": {
"type": "string",
"description": "連結，例如 PR 或更新日誌"
},
"color": {
"type": "string",
"description": "標記顏色",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"source": {
"type": "string",
"description": "manual，或發版 webhook 用的 deploy",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
],
"default": "manual"
},
"version": {
"type": "string",
"description": "部署：發版版本或 commit，用於預設標題"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "備註 id，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站，工作區層級備註為 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/notes/:id.json
刪除備註
notes_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "備註 id，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站，工作區層級備註為 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/notes.json
列出網站的備註（包含工作區層級備註）
notes_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date",
"description": "僅此日期當天或之後的備註"
},
"to": {
"type": "string",
"format": "date",
"description": "僅此日期當天或之前的備註"
},
"source": {
"type": "string",
"description": "僅此來源的備註",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
]
},
"query": {
"type": "string",
"description": "搜尋標題、內容與連結"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "備註 id，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站，工作區層級備註為 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/notes/:id.json
取得備註
notes_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "備註 id，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站，工作區層級備註為 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/notes/:id.json
編輯備註
notes_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "備註的日期"
},
"end_date": {
"type": "string",
"format": "date",
"description": "日期範圍的最後一天"
},
"title": {
"type": "string",
"description": "顯示在圖表上的簡短標題"
},
"body": {
"type": "string",
"description": "詳細內容（Markdown）"
},
"url": {
"type": "string",
"description": "連結"
},
"color": {
"type": "string",
"description": "標記顏色",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "備註 id，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站，工作區層級備註為 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/notes.json
新增工作區層級備註（顯示在每個網站）
workspace_notes_create
權限： content.write
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "備註的日期（網站時區）。預設為今天"
},
"end_date": {
"type": "string",
"format": "date",
"description": "日期範圍的最後一天"
},
"title": {
"type": "string",
"description": "顯示在圖表上的簡短標題",
"examples": [
"Launched new pricing"
]
},
"body": {
"type": "string",
"description": "詳細內容（Markdown）"
},
"url": {
"type": "string",
"description": "連結，例如 PR 或更新日誌"
},
"color": {
"type": "string",
"description": "標記顏色",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"source": {
"type": "string",
"description": "manual，或發版 webhook 用的 deploy",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
],
"default": "manual"
},
"version": {
"type": "string",
"description": "部署：發版版本或 commit，用於預設標題"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "備註 id，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站，工作區層級備註為 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/notes/:id.json
刪除工作區備註
workspace_notes_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "備註 id，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站，工作區層級備註為 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/notes.json
列出工作區內的備註
workspace_notes_list
權限： analytics.read
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date",
"description": "僅此日期當天或之後的備註"
},
"to": {
"type": "string",
"format": "date",
"description": "僅此日期當天或之前的備註"
},
"source": {
"type": "string",
"description": "僅此來源的備註",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
]
},
"query": {
"type": "string",
"description": "搜尋標題、內容與連結"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "備註 id，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站，工作區層級備註為 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/workspaces/:workspace_id/notes/:id.json
編輯工作區備註
workspace_notes_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "備註的日期"
},
"end_date": {
"type": "string",
"format": "date",
"description": "日期範圍的最後一天"
},
"title": {
"type": "string",
"description": "顯示在圖表上的簡短標題"
},
"body": {
"type": "string",
"description": "詳細內容（Markdown）"
},
"url": {
"type": "string",
"description": "連結"
},
"color": {
"type": "string",
"description": "標記顏色",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "備註 id，例如 note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站，工作區層級備註為 null"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral、brand、blue、amber、red、violet"
},
"source": {
"type": "string",
"description": "manual、deploy、system、import、incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
儀表板
GET
/workspaces/:workspace_id/dashboards/:id/cards/:index.json
自訂儀表板單張卡片的資料
dashboards_card
權限： analytics.read
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id/cards/:index.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
},
"index": {
"type": "string",
"description": "資源的 Index"
}
},
"required": [
"workspace_id",
"id",
"index"
]
}
回應資料
{
"type": "object"
}
POST
/workspaces/:workspace_id/dashboards.json
建立自訂儀表板
dashboards_create
權限： content.write
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/dashboards.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "儀表板名稱",
"examples": [
"Client: Acme"
]
},
"cards": {
"type": "array",
"items": {},
"description": "依序的卡片（最多 40 張）：[{\"type\": \"metric|chart|breakdown|goal|live|funnel|uptime|vitals\", \"site_id\": \"pa_…\", \"title\": \"optional\", \"params\": {\"period\": \"30d\", \"metric\": \"visitors\", \"dimension\": \"page\", \"funnel_id\": \"fun_…\"}}]。該類型不使用的參數會被忽略",
"default": []
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "儀表板 id，例如 dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "依序的卡片：[{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/dashboards/:id.json
刪除自訂儀表板
dashboards_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "儀表板 id，例如 dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "依序的卡片：[{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/dashboards.json
列出自訂儀表板
dashboards_list
權限： analytics.read
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "儀表板 id，例如 dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "依序的卡片：[{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/workspaces/:workspace_id/dashboards/:id.json
取得自訂儀表板及其卡片
dashboards_get
權限： analytics.read
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "儀表板 id，例如 dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "依序的卡片：[{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/workspaces/:workspace_id/dashboards/:id.json
重新命名自訂儀表板或取代其卡片
dashboards_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "新名稱（留空則不變）"
},
"cards": {
"type": "array",
"items": {},
"description": "取代所有卡片。依序的卡片（最多 40 張）：[{\"type\": \"metric|chart|breakdown|goal|live|funnel|uptime|vitals\", \"site_id\": \"pa_…\", \"title\": \"optional\", \"params\": {\"period\": \"30d\", \"metric\": \"visitors\", \"dimension\": \"page\", \"funnel_id\": \"fun_…\"}}]。該類型不使用的參數會被忽略"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "儀表板 id，例如 dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "依序的卡片：[{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
分享
GET
/badge/:site_id.json
公開網站的訪客計數器徽章（SVG）
badges_get
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl https://privatusanalytics.com/badge/:site_id.json輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
分析
GET
/sites/:site_id/overview.json
網站概覽：指標、圖表數列、熱門面板、即時訪客與備註
stats_overview
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/overview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"interval": {
"type": "string",
"description": "圖表區間大小",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"panels": {
"type": "array",
"items": {
"type": "string"
},
"description": "要包含熱門值的維度",
"default": [
"channel",
"referrer",
"page",
"entry_page",
"country",
"device",
"browser",
"os",
"utm_campaign",
"event",
"goal"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/experiments.json
實驗報告：各版本的轉換率、相對對照組的提升幅度與顯著性（雙比例 z 檢定）
experiments_report
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/experiments.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"property": {
"type": "string",
"description": "存放版本的事件屬性，例如 variant",
"examples": [
"variant"
]
},
"goal_id": {
"type": "string",
"description": "計為轉換的目標（goal_…）"
},
"control": {
"type": "string",
"description": "對照版本（若存在則預設為 \"control\"，否則為造訪最多的版本）"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"property",
"goal_id",
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/insights.json
與前一期間相比的顯著變化，以日常語言呈現（變動最大的項目、目標轉換變化）
insights_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/insights.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "截至昨天的完整天數，與之前相同天數比較",
"enum": [
"7d",
"14d",
"28d",
"30d"
],
"default": "7d"
},
"limit": {
"type": "integer",
"description": "洞察數量上限（1 至 20）",
"default": 8
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/journeys.json
路徑：某頁面（或任何入口）之後的前 3 步熱門路徑，或某頁面或目標之前的路徑
journeys_explore
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/journeys.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"mode": {
"type": "string",
"description": "forward：起始頁面之後的頁面，reverse：通往結束頁面或目標的頁面",
"enum": [
"forward",
"reverse"
],
"default": "forward"
},
"path": {
"type": "string",
"description": "起始頁面（forward）或結束頁面（reverse）。留白表示任何入口（僅 forward）"
},
"goal_id": {
"type": "string",
"description": "reverse 模式：以此目標（goal_…）而非頁面作為終點"
},
"limit": {
"type": "integer",
"description": "每一步顯示的頁面數（最多 12）",
"default": 6
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/pages/detail.json
頁面詳情：單一路徑的指標、上一頁與下一頁、來源、Web Vitals、事件與點擊地圖
pages_detail
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/pages/detail.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"path": {
"type": "string",
"description": "頁面路徑，例如 /pricing",
"examples": [
"/pricing"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"path",
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/stats/aggregate.json
某期間的主要指標（含比較）
stats_aggregate
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/stats/aggregate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/breakdown/:dimension.json
某維度的熱門值（頁面、來源、國家…）
stats_breakdown
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/breakdown/:dimension.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"dimension": {
"type": "string",
"description": "資源的 Dimension"
},
"limit": {
"type": "integer",
"description": "每頁列數（最多 1000）",
"default": 10
},
"page": {
"type": "integer",
"description": "頁碼",
"default": 1
},
"sort": {
"type": "string",
"description": "排序指標",
"enum": [
"visitors",
"visits",
"pageviews",
"revenue"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"dimension",
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/stats/timeseries.json
圖表用的每個時間區間指標
stats_timeseries
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/stats/timeseries.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"interval": {
"type": "string",
"description": "區間大小。auto 會依範圍自動選擇",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
助理
POST
/sites/:site_id/ask.json
在新對話中提問（計入每月 AI 提問額度）
assistant_ask
權限： analytics.read
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/ask.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "用日常語言寫下您的第一個問題",
"examples": [
"How many visitors did we have last week?"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"question",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "對話 id，例如 ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "第一個問題（已縮短）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最後一則訊息的時間"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "此時間之後自動刪除（最後一則訊息後 30 天）"
},
"messages": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "對話內的訊息 id"
},
"role": {
"type": "string",
"description": "user（問題）或 assistant（答案）"
},
"content": {
"type": "string",
"description": "問題，或 Markdown 格式的答案"
},
"queries": {
"type": "array",
"items": {
"type": "object"
},
"description": "我如何得出：答案背後確切的 API 查詢，格式為 [{tool, input, status, error}]"
},
"chart": {
"anyOf": [
{
"type": "object",
"description": "答案的圖表：{type: line, labels, series, comparison, metric, format} 或 {type: table, columns, rows}"
},
{
"type": "null"
}
]
},
"goal_draft": {
"anyOf": [
{
"type": "object",
"description": "助理提議的目標，以 goals_create 確認"
},
{
"type": "null"
}
]
},
"input_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型輸入 token 數"
},
{
"type": "null"
}
]
},
"output_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型輸出 token 數"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"description": "問題與答案，最舊的在前"
}
}
}
DELETE
/sites/:site_id/ask/:id.json
刪除詢問對話及其訊息
assistant_conversations_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "對話 id，例如 ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "第一個問題（已縮短）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最後一則訊息的時間"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "此時間之後自動刪除（最後一則訊息後 30 天）"
}
}
}
GET
/sites/:site_id/ask.json
列出您在某網站的詢問對話
assistant_conversations_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/ask.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "對話 id，例如 ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "第一個問題（已縮短）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最後一則訊息的時間"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "此時間之後自動刪除（最後一則訊息後 30 天）"
}
}
}
}
GET
/sites/:site_id/ask/:id.json
詢問對話：問題、答案、其背後的查詢與圖表
assistant_conversations_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/ask/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "對話 id，例如 ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "第一個問題（已縮短）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "最後一則訊息的時間"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "此時間之後自動刪除（最後一則訊息後 30 天）"
},
"messages": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "對話內的訊息 id"
},
"role": {
"type": "string",
"description": "user（問題）或 assistant（答案）"
},
"content": {
"type": "string",
"description": "問題，或 Markdown 格式的答案"
},
"queries": {
"type": "array",
"items": {
"type": "object"
},
"description": "我如何得出：答案背後確切的 API 查詢，格式為 [{tool, input, status, error}]"
},
"chart": {
"anyOf": [
{
"type": "object",
"description": "答案的圖表：{type: line, labels, series, comparison, metric, format} 或 {type: table, columns, rows}"
},
{
"type": "null"
}
]
},
"goal_draft": {
"anyOf": [
{
"type": "object",
"description": "助理提議的目標，以 goals_create 確認"
},
{
"type": "null"
}
]
},
"input_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型輸入 token 數"
},
{
"type": "null"
}
]
},
"output_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型輸出 token 數"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"description": "問題與答案，最舊的在前"
}
}
}
POST
/sites/:site_id/ask/:ask_conversation_id/messages.json
在對話中追問（計入每月 AI 提問額度）。回傳答案。
assistant_ask_followup
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "用日常語言寫下您的問題",
"examples": [
"Which pages had the most visitors last week?"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"ask_conversation_id": {
"type": "string",
"description": "資源的 Ask conversation"
}
},
"required": [
"question",
"site_id",
"ask_conversation_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "對話內的訊息 id"
},
"role": {
"type": "string",
"description": "user（問題）或 assistant（答案）"
},
"content": {
"type": "string",
"description": "問題，或 Markdown 格式的答案"
},
"queries": {
"type": "array",
"items": {
"type": "object"
},
"description": "我如何得出：答案背後確切的 API 查詢，格式為 [{tool, input, status, error}]"
},
"chart": {
"anyOf": [
{
"type": "object",
"description": "答案的圖表：{type: line, labels, series, comparison, metric, format} 或 {type: table, columns, rows}"
},
{
"type": "null"
}
]
},
"goal_draft": {
"anyOf": [
{
"type": "object",
"description": "助理提議的目標，以 goals_create 確認"
},
{
"type": "null"
}
]
},
"input_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型輸入 token 數"
},
{
"type": "null"
}
]
},
"output_tokens": {
"anyOf": [
{
"type": "integer",
"description": "使用的模型輸出 token 數"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
匯入
GET
/sites/:site_id/imports/google/properties.json
列出可匯入的 Google Analytics 4 資源
imports_google_properties
權限： sites.manage
範例
curl https://privatusanalytics.com/sites/:site_id/imports/google/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
POST
/sites/:site_id/imports.json
開始匯入（GA4 資源或 CSV 上傳）
imports_create
權限： sites.manage
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/imports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "ga4（Google Analytics 4 API）或您上傳其 CSV 匯出檔的工具",
"enum": [
"ga4",
"universal_analytics",
"fathom",
"simple_analytics",
"plausible",
"matomo",
"umami",
"clicky"
]
},
"property_id": {
"type": "string",
"description": "GA4 資源，例如 properties/123（見 imports_google_properties）。ga4 必填",
"examples": [
"properties/123456789"
]
},
"date_from": {
"type": "string",
"format": "date",
"description": "要匯入的第一天。ga4 必填。對於沒有日期欄的 CSV 檔，每一列都記為這一天"
},
"date_to": {
"type": "string",
"format": "date",
"description": "要匯入的最後一天（ga4 預設為您第一個追蹤事件的前一天，或昨天）"
},
"file": {
"type": "string",
"format": "binary",
"description": "CSV 匯出檔（multipart 上傳，最大 50 MB）。CSV 來源必填"
},
"dimension": {
"type": "string",
"description": "CSV 各列所細分的內容（覆寫偵測結果，Matomo \"Label\" 匯出檔需要）",
"enum": [
"total",
"page",
"source",
"country",
"device",
"browser",
"os"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"source",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "匯入 id"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4、universal_analytics、fathom、simple_analytics、plausible、matomo、umami 或 clicky"
},
"status": {
"type": "string",
"description": "queued、running、complete 或 failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "匯入的第一天"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "匯入的最後一天"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "已儲存的每日列數"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "匯入失敗的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/imports/:id.json
刪除匯入及其所有已匯入資料
imports_delete
權限： sites.manage
範例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/imports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "匯入 id"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4、universal_analytics、fathom、simple_analytics、plausible、matomo、umami 或 clicky"
},
"status": {
"type": "string",
"description": "queued、running、complete 或 failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "匯入的第一天"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "匯入的最後一天"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "已儲存的每日列數"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "匯入失敗的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/imports.json
列出網站的匯入
imports_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/imports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "僅此狀態的匯入",
"enum": [
"queued",
"running",
"complete",
"failed"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "匯入 id"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4、universal_analytics、fathom、simple_analytics、plausible、matomo、umami 或 clicky"
},
"status": {
"type": "string",
"description": "queued、running、complete 或 failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "匯入的第一天"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "匯入的最後一天"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "已儲存的每日列數"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "匯入失敗的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/imports/:id.json
取得匯入及其狀態
imports_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/imports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "匯入 id"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4、universal_analytics、fathom、simple_analytics、plausible、matomo、umami 或 clicky"
},
"status": {
"type": "string",
"description": "queued、running、complete 或 failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "匯入的第一天"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "匯入的最後一天"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "已儲存的每日列數"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "匯入失敗的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
匯出
POST
/workspaces/:workspace_id/exports.json
將匯出加入佇列（在背景建立）
exports_create
權限： analytics.export
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/exports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "要匯出的網站（pa_…）",
"examples": [
"pa_7Q2K9XH3AB"
]
},
"kind": {
"type": "string",
"description": "aggregated：依時間區間與維度的指標。pageviews/events/raw：每個請求一列（Pro 以上）。imported：已匯入的每日統計。dashboard：概覽面板的 ZIP",
"enum": [
"aggregated",
"pageviews",
"events",
"imported",
"raw",
"dashboard"
],
"default": "aggregated"
},
"file_format": {
"type": "string",
"description": "csv、json 或 xlsx（aggregated、pageviews、events、imported），csv 或 ndjson（raw），zip（dashboard）",
"enum": [
"csv",
"json",
"xlsx",
"ndjson",
"zip"
],
"default": "csv"
},
"from": {
"type": "string",
"format": "date",
"description": "第一天，使用匯出時區",
"examples": [
"2026-09-01"
]
},
"to": {
"type": "string",
"format": "date",
"description": "最後一天（含）（最多 400 天，raw 為 93 天）",
"examples": [
"2026-09-28"
]
},
"timezone": {
"type": "string",
"description": "日期與分組使用的時區，例如 America/New_York（預設：網站時區）"
},
"grouping": {
"type": "string",
"description": "彙總匯出的時間區間",
"enum": [
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "day"
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "用來將彙總匯出分組的造訪維度（最多 6 個），例如 country、channel、entry_page。對於 imported 匯出：要包含的已匯入維度",
"default": []
},
"metrics": {
"type": "array",
"items": {
"type": "string"
},
"description": "彙總匯出的指標（預設全部）：visitors、visits、pageviews、bounce_rate、visit_duration、views_per_visit、revenue",
"default": []
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "pageviews/events/raw 匯出的欄位（預設為 visit_id、vital_value、selector 以外的全部欄位）：occurred_at, kind, name, visit_id, hostname, path, referrer_host, referrer_path, channel, utm_source, utm_medium, utm_campaign, utm_content, utm_term, ref, paid_click, country, language, device, browser, browser_major, os, os_major, screen_bucket, engaged_ms, scroll_depth, revenue_minor, currency, vital_value, selector, props",
"default": []
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件，格式與統計 API 相同：[[\"dimension\",\"operator\",\"value\"], …]",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"site_id",
"from",
"to",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "匯出 id，例如 exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "已匯出的網站（pa_…）"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated、pageviews、events、imported、raw 或 dashboard"
},
"format": {
"type": "string",
"description": "csv、json、xlsx、ndjson 或 zip"
},
"status": {
"type": "string",
"description": "queued、running、complete、failed 或 expired"
},
"params": {
"type": "object",
"description": "匯出定義（日期、時區、分組、維度、指標、欄位、篩選條件）"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "已寫入的列數"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "匯出失敗的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "檔案何時刪除"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "回傳短效簽署檔案連結的路徑（exports_download）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/exports/:id.json
刪除匯出及其檔案
exports_delete
權限： analytics.export
範例
curl -X DELETE https://privatusanalytics.com/exports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "匯出 id，例如 exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "已匯出的網站（pa_…）"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated、pageviews、events、imported、raw 或 dashboard"
},
"format": {
"type": "string",
"description": "csv、json、xlsx、ndjson 或 zip"
},
"status": {
"type": "string",
"description": "queued、running、complete、failed 或 expired"
},
"params": {
"type": "object",
"description": "匯出定義（日期、時區、分組、維度、指標、欄位、篩選條件）"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "已寫入的列數"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "匯出失敗的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "檔案何時刪除"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "回傳短效簽署檔案連結的路徑（exports_download）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/exports/:id/download.json
取得檔案的簽署連結（10 分鐘內有效）
exports_download
權限： analytics.export
範例
curl https://privatusanalytics.com/exports/:id/download.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object"
}
GET
/workspaces/:workspace_id/exports.json
列出匯出（工作佇列）
exports_list
權限： analytics.export
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/exports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "僅此網站（pa_…）的匯出"
},
"status": {
"type": "string",
"description": "僅此狀態的匯出",
"enum": [
"queued",
"running",
"complete",
"failed",
"expired"
]
},
"kind": {
"type": "string",
"description": "僅此類型的匯出",
"enum": [
"aggregated",
"pageviews",
"events",
"imported",
"raw",
"dashboard"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "匯出 id，例如 exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "已匯出的網站（pa_…）"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated、pageviews、events、imported、raw 或 dashboard"
},
"format": {
"type": "string",
"description": "csv、json、xlsx、ndjson 或 zip"
},
"status": {
"type": "string",
"description": "queued、running、complete、failed 或 expired"
},
"params": {
"type": "object",
"description": "匯出定義（日期、時區、分組、維度、指標、欄位、篩選條件）"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "已寫入的列數"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "匯出失敗的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "檔案何時刪除"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "回傳短效簽署檔案連結的路徑（exports_download）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/workspaces/:workspace_id/exports/preview.json
預覽匯出：前 20 列與預估列數
exports_preview
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "要匯出的網站（pa_…）",
"examples": [
"pa_7Q2K9XH3AB"
]
},
"kind": {
"type": "string",
"description": "aggregated：依時間區間與維度的指標。pageviews/events/raw：每個請求一列（Pro 以上）。imported：已匯入的每日統計。dashboard：概覽面板的 ZIP",
"enum": [
"aggregated",
"pageviews",
"events",
"imported",
"raw",
"dashboard"
],
"default": "aggregated"
},
"file_format": {
"type": "string",
"description": "csv、json 或 xlsx（aggregated、pageviews、events、imported），csv 或 ndjson（raw），zip（dashboard）",
"enum": [
"csv",
"json",
"xlsx",
"ndjson",
"zip"
],
"default": "csv"
},
"from": {
"type": "string",
"format": "date",
"description": "第一天，使用匯出時區",
"examples": [
"2026-09-01"
]
},
"to": {
"type": "string",
"format": "date",
"description": "最後一天（含）（最多 400 天，raw 為 93 天）",
"examples": [
"2026-09-28"
]
},
"timezone": {
"type": "string",
"description": "日期與分組使用的時區，例如 America/New_York（預設：網站時區）"
},
"grouping": {
"type": "string",
"description": "彙總匯出的時間區間",
"enum": [
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "day"
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "用來將彙總匯出分組的造訪維度（最多 6 個），例如 country、channel、entry_page。對於 imported 匯出：要包含的已匯入維度",
"default": []
},
"metrics": {
"type": "array",
"items": {
"type": "string"
},
"description": "彙總匯出的指標（預設全部）：visitors、visits、pageviews、bounce_rate、visit_duration、views_per_visit、revenue",
"default": []
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "pageviews/events/raw 匯出的欄位（預設為 visit_id、vital_value、selector 以外的全部欄位）：occurred_at, kind, name, visit_id, hostname, path, referrer_host, referrer_path, channel, utm_source, utm_medium, utm_campaign, utm_content, utm_term, ref, paid_click, country, language, device, browser, browser_major, os, os_major, screen_bucket, engaged_ms, scroll_depth, revenue_minor, currency, vital_value, selector, props",
"default": []
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件，格式與統計 API 相同：[[\"dimension\",\"operator\",\"value\"], …]",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"site_id",
"from",
"to",
"workspace_id"
]
}
回應資料
{
"type": "object"
}
GET
/exports/:id.json
取得匯出及其狀態
exports_get
權限： analytics.export
範例
curl https://privatusanalytics.com/exports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "匯出 id，例如 exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "已匯出的網站（pa_…）"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated、pageviews、events、imported、raw 或 dashboard"
},
"format": {
"type": "string",
"description": "csv、json、xlsx、ndjson 或 zip"
},
"status": {
"type": "string",
"description": "queued、running、complete、failed 或 expired"
},
"params": {
"type": "object",
"description": "匯出定義（日期、時區、分組、維度、指標、欄位、篩選條件）"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "已寫入的列數"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "匯出失敗的原因"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "檔案何時刪除"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "回傳短效簽署檔案連結的路徑（exports_download）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
區段
POST
/sites/:site_id/segments.json
將篩選條件儲存為區段
segments_create
權限： content.write
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/segments.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "區段名稱，例如「來自廣告的行動裝置訪客」",
"examples": [
"Mobile visitors from ads"
]
},
"description": {
"type": "string",
"description": "選填的備註，說明此區段的用途（最多 300 個字元）",
"examples": [
"People who might buy the Pro plan"
]
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件，必須全部符合。每個項目是一個條件 [\"dimension\", \"operator\", \"value\"]，或在數個條件中符合任一個即可時使用 {\"any\": [conditions]}。維度：page, entry_page, exit_page, hostname, channel, referrer, referrer_url, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, country（ISO 代碼，例如 US）, language, device（desktop, mobile, tablet, tv, other）, browser, browser_version, os, os_version, screen, goal（目標 id）, event（自訂事件名稱）以及 prop:<key>（自訂事件屬性）。運算子：is, is_not, contains, not_contains, starts_with, regex, not_regex, any_of 與 none_of（值為清單）, gt 與 lt（數字）, between（兩個數字的清單）。也接受區段表單的列：{\"dimension\", \"operator\", \"value\", \"property\"（用於 prop 維度）, \"join\": \"and\" 或 \"or\"（or 會將該列與前一列合併）}。範例：[[\"country\", \"is\", \"US\"], [\"device\", \"is\", \"mobile\"], {\"any\": [[\"page\", \"starts_with\", \"/pricing\"], [\"goal\", \"is\", \"goal_7Q2K9XH3AB\"]]}]",
"examples": [
[
[
"country",
"is",
"US"
],
[
"device",
"is",
"mobile"
],
{
"any": [
[
"page",
"starts_with",
"/pricing"
],
[
"goal",
"is",
"goal_7Q2K9XH3AB"
]
]
}
]
]
},
"shared": {
"type": "boolean",
"description": "所有有網站存取權的人都能看到（false：僅您自己）",
"default": true
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"filters",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "區段 id，例如 seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "此區段的用途，或 null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "採用統計篩選格式的篩選條件：必須全部符合的條件 [\"dimension\", \"operator\", \"value\"]，以及 {\"any\": [conditions]} 群組"
},
"summary": {
"type": "string",
"description": "以日常語言描述的篩選條件，例如「來自美國、使用行動裝置且瀏覽過 /pricing 的訪客」"
},
"shared": {
"type": "boolean",
"description": "所有有網站存取權的人都能看到"
},
"mine": {
"type": "boolean",
"description": "由您建立"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/segments/:id.json
刪除區段
segments_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "區段 id，例如 seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "此區段的用途，或 null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "採用統計篩選格式的篩選條件：必須全部符合的條件 [\"dimension\", \"operator\", \"value\"]，以及 {\"any\": [conditions]} 群組"
},
"summary": {
"type": "string",
"description": "以日常語言描述的篩選條件，例如「來自美國、使用行動裝置且瀏覽過 /pricing 的訪客」"
},
"shared": {
"type": "boolean",
"description": "所有有網站存取權的人都能看到"
},
"mine": {
"type": "boolean",
"description": "由您建立"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/segments.json
列出您可在網站上使用的區段
segments_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/segments.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "區段 id，例如 seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "此區段的用途，或 null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "採用統計篩選格式的篩選條件：必須全部符合的條件 [\"dimension\", \"operator\", \"value\"]，以及 {\"any\": [conditions]} 群組"
},
"summary": {
"type": "string",
"description": "以日常語言描述的篩選條件，例如「來自美國、使用行動裝置且瀏覽過 /pricing 的訪客」"
},
"shared": {
"type": "boolean",
"description": "所有有網站存取權的人都能看到"
},
"mine": {
"type": "boolean",
"description": "由您建立"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/sites/:site_id/segments/preview.json
以日常語言描述篩選條件，並計算過去 30 天內符合的訪客數
segments_preview
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"filters": {
"type": "array",
"items": {},
"description": "篩選條件，必須全部符合。每個項目是一個條件 [\"dimension\", \"operator\", \"value\"]，或在數個條件中符合任一個即可時使用 {\"any\": [conditions]}。維度：page, entry_page, exit_page, hostname, channel, referrer, referrer_url, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, country（ISO 代碼，例如 US）, language, device（desktop, mobile, tablet, tv, other）, browser, browser_version, os, os_version, screen, goal（目標 id）, event（自訂事件名稱）以及 prop:<key>（自訂事件屬性）。運算子：is, is_not, contains, not_contains, starts_with, regex, not_regex, any_of 與 none_of（值為清單）, gt 與 lt（數字）, between（兩個數字的清單）。也接受區段表單的列：{\"dimension\", \"operator\", \"value\", \"property\"（用於 prop 維度）, \"join\": \"and\" 或 \"or\"（or 會將該列與前一列合併）}。範例：[[\"country\", \"is\", \"US\"], [\"device\", \"is\", \"mobile\"], {\"any\": [[\"page\", \"starts_with\", \"/pricing\"], [\"goal\", \"is\", \"goal_7Q2K9XH3AB\"]]}]",
"examples": [
[
[
"country",
"is",
"US"
],
[
"device",
"is",
"mobile"
],
{
"any": [
[
"page",
"starts_with",
"/pricing"
],
[
"goal",
"is",
"goal_7Q2K9XH3AB"
]
]
}
]
],
"default": []
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/segments/:id.json
取得區段
segments_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/segments/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "區段 id，例如 seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "此區段的用途，或 null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "採用統計篩選格式的篩選條件：必須全部符合的條件 [\"dimension\", \"operator\", \"value\"]，以及 {\"any\": [conditions]} 群組"
},
"summary": {
"type": "string",
"description": "以日常語言描述的篩選條件，例如「來自美國、使用行動裝置且瀏覽過 /pricing 的訪客」"
},
"shared": {
"type": "boolean",
"description": "所有有網站存取權的人都能看到"
},
"mine": {
"type": "boolean",
"description": "由您建立"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/segments/:id.json
重新命名區段或變更其篩選條件或分享設定
segments_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "區段名稱"
},
"description": {
"type": "string",
"description": "選填的備註，說明此區段的用途（最多 300 個字元，留空即可清除）"
},
"filters": {
"type": "array",
"items": {},
"description": "用來取代的篩選條件，格式與建立時相同。篩選條件，必須全部符合。每個項目是一個條件 [\"dimension\", \"operator\", \"value\"]，或在數個條件中符合任一個即可時使用 {\"any\": [conditions]}。維度：page, entry_page, exit_page, hostname, channel, referrer, referrer_url, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, country（ISO 代碼，例如 US）, language, device（desktop, mobile, tablet, tv, other）, browser, browser_version, os, os_version, screen, goal（目標 id）, event（自訂事件名稱）以及 prop:<key>（自訂事件屬性）。運算子：is, is_not, contains, not_contains, starts_with, regex, not_regex, any_of 與 none_of（值為清單）, gt 與 lt（數字）, between（兩個數字的清單）。也接受區段表單的列：{\"dimension\", \"operator\", \"value\", \"property\"（用於 prop 維度）, \"join\": \"and\" 或 \"or\"（or 會將該列與前一列合併）}。範例：[[\"country\", \"is\", \"US\"], [\"device\", \"is\", \"mobile\"], {\"any\": [[\"page\", \"starts_with\", \"/pricing\"], [\"goal\", \"is\", \"goal_7Q2K9XH3AB\"]]}]",
"examples": [
[
[
"country",
"is",
"US"
],
[
"device",
"is",
"mobile"
],
{
"any": [
[
"page",
"starts_with",
"/pricing"
],
[
"goal",
"is",
"goal_7Q2K9XH3AB"
]
]
}
]
]
},
"shared": {
"type": "boolean",
"description": "網站上的所有人都能看到"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "區段 id，例如 seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "此區段的用途，或 null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "採用統計篩選格式的篩選條件：必須全部符合的條件 [\"dimension\", \"operator\", \"value\"]，以及 {\"any\": [conditions]} 群組"
},
"summary": {
"type": "string",
"description": "以日常語言描述的篩選條件，例如「來自美國、使用行動裝置且瀏覽過 /pricing 的訪客」"
},
"shared": {
"type": "boolean",
"description": "所有有網站存取權的人都能看到"
},
"mine": {
"type": "boolean",
"description": "由您建立"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
即時
GET
/sites/:site_id/live.json
即時訪客、活動串流，以及目前熱門的內容（過去 30 分鐘）
live_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/live.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"feed": {
"type": "string",
"description": "活動串流：all 請求、pageviews 或自訂事件",
"enum": [
"all",
"pageviews",
"events"
],
"default": "all"
},
"limit": {
"type": "integer",
"description": "活動串流的項目數（最多 100）",
"default": 50
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/live/wallboard.json
一個或多個網站的看板卡片（即時與今日）
live_wallboard
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/live/wallboard.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要輪播的網站 id（預設為此網站）",
"default": []
},
"rotate_seconds": {
"type": "integer",
"description": "每個網站停留在螢幕上的秒數（5-300）",
"default": 20
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/wallboard/:token.json
以看板 token 取得看板（無需登入）
live_public_wallboard
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl https://privatusanalytics.com/wallboard/:token.json輸入
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要輪播的網站 id（預設為此網站）",
"default": []
},
"rotate_seconds": {
"type": "integer",
"description": "每個網站停留在螢幕上的秒數（5-300）",
"default": 20
},
"token": {
"type": "string",
"description": "資源的 Token"
}
},
"required": [
"token"
]
}
回應資料
{
"type": "object"
}
POST
/sites/:site_id/live/wallboard/links.json
建立看板連結（唯讀，可撤銷）
wallboard_links_create
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "標籤，例如 Office TV"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要額外輪播的網站（此網站一定包含在內）",
"default": []
},
"rotate_seconds": {
"type": "integer",
"description": "輪播時每個網站的秒數（5-300）",
"default": 20
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "此時間之後失效"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "連結 id，例如 shr_7Q2K9XH3AB"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "在電視上開啟。不需要登入"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "輪播顯示的網站"
},
"rotate_seconds": {
"type": "integer"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/live/wallboard/links/:id.json
撤銷看板連結
wallboard_links_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "連結 id，例如 shr_7Q2K9XH3AB"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "在電視上開啟。不需要登入"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "輪播顯示的網站"
},
"rotate_seconds": {
"type": "integer"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/live/wallboard/links.json
列出網站的看板連結
wallboard_links_list
權限： sites.manage
範例
curl https://privatusanalytics.com/sites/:site_id/live/wallboard/links.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "連結 id，例如 shr_7Q2K9XH3AB"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "在電視上開啟。不需要登入"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "輪播顯示的網站"
},
"rotate_seconds": {
"type": "integer"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
工作區
GET
/workspaces/:workspace_id/white_label.json
取得白標品牌
white_label_get
權限： workspace.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/white_label.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"brand_name": {
"anyOf": [
{
"type": "string",
"description": "取代 Privatus Analytics 顯示的名稱"
},
{
"type": "null"
}
]
},
"brand_logo_url": {
"anyOf": [
{
"type": "string",
"description": "Logo 圖片網址"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string",
"description": "強調色"
},
{
"type": "null"
}
]
},
"hide_branding": {
"type": "boolean",
"description": "已隱藏 Privatus Analytics 品牌"
},
"available": {
"type": "boolean",
"description": "方案包含白標"
},
"active": {
"type": "boolean",
"description": "目前已套用該品牌"
}
}
}
PATCH
/workspaces/:workspace_id/white_label.json
設定分享儀表板與電子郵件報告使用的白標品牌（Business）
white_label_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"brand_name": {
"type": "string",
"description": "取代 Privatus Analytics 顯示的名稱（留白則移除）"
},
"brand_logo_url": {
"type": "string",
"description": "Logo 圖片的 https 網址（留白則移除）"
},
"brand_color": {
"type": "string",
"description": "強調色，例如 #06755b"
},
"hide_branding": {
"type": "boolean",
"description": "在分享儀表板與電子郵件報告中隱藏「Privatus Analytics」"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"brand_name": {
"anyOf": [
{
"type": "string",
"description": "取代 Privatus Analytics 顯示的名稱"
},
{
"type": "null"
}
]
},
"brand_logo_url": {
"anyOf": [
{
"type": "string",
"description": "Logo 圖片網址"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string",
"description": "強調色"
},
{
"type": "null"
}
]
},
"hide_branding": {
"type": "boolean",
"description": "已隱藏 Privatus Analytics 品牌"
},
"available": {
"type": "boolean",
"description": "方案包含白標"
},
"active": {
"type": "boolean",
"description": "目前已套用該品牌"
}
}
}
GET
/workspaces/:workspace_id/security.json
取得工作區安全設定
workspace_security_get
權限： workspace.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/security.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"enforce_2fa": {
"type": "boolean",
"description": "成員必須設定 2FA"
},
"login_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "允許的登入方式"
},
"session_ttl_hours": {
"anyOf": [
{
"type": "integer",
"description": "工作階段時效（null = 無）"
},
{
"type": "null"
}
]
},
"app_ip_allowlist": {
"type": "array",
"items": {
"type": "string"
},
"description": "允許的 IP/CIDR（空 = 不限）"
},
"support_access_until": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Privatus Analytics 支援人員可查看工作區直到"
},
{
"type": "null"
}
]
}
}
}
PATCH
/workspaces/:workspace_id/security.json
更新工作區安全設定（2FA、登入方式、工作階段時效、IP 允許清單、支援存取）
workspace_security_update
權限： workspace.manage
範例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/security.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"enforce_2fa": {
"type": "boolean",
"description": "要求成員設定 2FA"
},
"login_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"password",
"magic_link",
"passkey",
"google",
"github",
"sso"
]
},
"description": "允許的登入方式"
},
"session_ttl_hours": {
"type": "integer",
"description": "經過這麼多小時後將成員登出（0 = 無限制）"
},
"app_ip_allowlist": {
"type": "array",
"items": {
"type": "string"
},
"description": "僅允許這些 IP/CIDR 存取應用程式與 API（Business）。留空 = 不限"
},
"support_access": {
"type": "boolean",
"description": "讓 Privatus Analytics 支援人員查看工作區 7 天"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"enforce_2fa": {
"type": "boolean",
"description": "成員必須設定 2FA"
},
"login_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "允許的登入方式"
},
"session_ttl_hours": {
"anyOf": [
{
"type": "integer",
"description": "工作階段時效（null = 無）"
},
{
"type": "null"
}
]
},
"app_ip_allowlist": {
"type": "array",
"items": {
"type": "string"
},
"description": "允許的 IP/CIDR（空 = 不限）"
},
"support_access_until": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Privatus Analytics 支援人員可查看工作區直到"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces.json
建立工作區（您將成為擁有者）
workspaces_create
權限： member
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/workspaces.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "工作區名稱",
"examples": [
"Acme Inc"
]
},
"timezone": {
"type": "string",
"description": "預設報表時區（預設為使用者的時區）"
},
"currency": {
"type": "string",
"description": "預設貨幣（ISO 4217）",
"default": "USD"
},
"how_heard": {
"type": "string",
"description": "您如何得知我們"
}
},
"required": [
"name"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "預設報表時區"
},
"currency": {
"type": "string",
"description": "預設貨幣"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "方案包含的每月事件數"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "您在此工作區的角色"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:id.json
刪除工作區及其所有網站（僅限擁有者，會取消任何訂閱）
workspaces_delete
權限： workspace.manage
範例
curl -X DELETE https://privatusanalytics.com/workspaces/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"confirm": {
"type": "string",
"description": "輸入工作區名稱以確認"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"confirm",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "預設報表時區"
},
"currency": {
"type": "string",
"description": "預設貨幣"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "方案包含的每月事件數"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "您在此工作區的角色"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces.json
列出您的工作區
workspaces_list
權限： member
範例
curl https://privatusanalytics.com/workspaces.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": []
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "預設報表時區"
},
"currency": {
"type": "string",
"description": "預設貨幣"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "方案包含的每月事件數"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "您在此工作區的角色"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/workspaces/:id.json
取得工作區
workspaces_get
權限： member
範例
curl https://privatusanalytics.com/workspaces/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "預設報表時區"
},
"currency": {
"type": "string",
"description": "預設貨幣"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "方案包含的每月事件數"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "您在此工作區的角色"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/workspaces/:id.json
更新工作區設定
workspaces_update
權限： workspace.manage
範例
curl -X PATCH https://privatusanalytics.com/workspaces/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "工作區名稱"
},
"timezone": {
"type": "string",
"description": "預設報表時區"
},
"currency": {
"type": "string",
"description": "預設貨幣（ISO 4217）"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "預設報表時區"
},
"currency": {
"type": "string",
"description": "預設貨幣"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "方案包含的每月事件數"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "您在此工作區的角色"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
帳單
POST
/workspaces/:workspace_id/billing/badge.json
加入或退出徽章獎勵（免費方案）
billing_badge
權限： billing.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/badge.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "true 表示驗證徽章並獲得獎勵"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"enabled",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付費級距的每月事件數"
},
"allowance": {
"type": "integer",
"description": "每月事件數，包含任何徽章獎勵"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每個計費週期的美元金額"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "續訂或結束時間"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未套用到訂閱）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 與 Business 的折扣百分比（免費開源方案為 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免費事件數（僅限免費開源方案）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "組織、學校、專案或代理商名稱"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "網站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "證明連結或儲存庫網址"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 授權（開源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "給審核人員的備註"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申請未獲核准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申請時間"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "審核時間"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效時間"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "方案結束時間"
},
{
"type": "null"
}
]
}
},
"description": "最近一次的折扣方案申請，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已核准方案提供的 Pro 與 Business 折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章獎勵（免費方案）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所回報月份的第一天"
},
"events": {
"type": "integer",
"description": "計費事件（瀏覽量與自訂事件）"
},
"bots": {
"type": "integer",
"description": "已濾除的機器人請求（不計費）"
},
"allowance": {
"type": "integer",
"description": "包含的事件數，含徽章獎勵"
},
"percent": {
"type": "number",
"description": "事件數佔額度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "預估的月底事件數"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩餘天數"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（過去某月達到或超過額度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的瀏覽量與自訂事件"
},
"share": {
"type": "number",
"description": "佔工作區總量的百分比"
}
}
},
"description": "各網站的事件數"
},
"history": {
"type": "array",
"description": "先前的月份，由新到舊排列"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "儀表板被 Privatus Analytics 人員鎖定的起始時間"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被捨棄期間為 true（已達每月上限，或由人員暫停收集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "收集暫停的原因：limit（已達每月額度）或 staff。收集中時為 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "人員暫停收集的時間"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因達到上限而暫停的解除時間：下個月開始時（UTC），或升級時提前解除。其他情況為 null"
},
{
"type": "null"
}
]
}
},
"description": "本月至今"
}
}
}
POST
/workspaces/:workspace_id/billing/cancel.json
在計費期間結束時取消
billing_cancel
權限： billing.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/cancel.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "取消的主要原因（選填問卷）",
"enum": [
"too_expensive",
"missing_features",
"switching_tool",
"not_using",
"temporary",
"other"
]
},
"comment": {
"type": "string",
"description": "我們還能改進的地方"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付費級距的每月事件數"
},
"allowance": {
"type": "integer",
"description": "每月事件數，包含任何徽章獎勵"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每個計費週期的美元金額"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "續訂或結束時間"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未套用到訂閱）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 與 Business 的折扣百分比（免費開源方案為 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免費事件數（僅限免費開源方案）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "組織、學校、專案或代理商名稱"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "網站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "證明連結或儲存庫網址"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 授權（開源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "給審核人員的備註"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申請未獲核准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申請時間"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "審核時間"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效時間"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "方案結束時間"
},
{
"type": "null"
}
]
}
},
"description": "最近一次的折扣方案申請，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已核准方案提供的 Pro 與 Business 折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章獎勵（免費方案）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所回報月份的第一天"
},
"events": {
"type": "integer",
"description": "計費事件（瀏覽量與自訂事件）"
},
"bots": {
"type": "integer",
"description": "已濾除的機器人請求（不計費）"
},
"allowance": {
"type": "integer",
"description": "包含的事件數，含徽章獎勵"
},
"percent": {
"type": "number",
"description": "事件數佔額度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "預估的月底事件數"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩餘天數"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（過去某月達到或超過額度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的瀏覽量與自訂事件"
},
"share": {
"type": "number",
"description": "佔工作區總量的百分比"
}
}
},
"description": "各網站的事件數"
},
"history": {
"type": "array",
"description": "先前的月份，由新到舊排列"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "儀表板被 Privatus Analytics 人員鎖定的起始時間"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被捨棄期間為 true（已達每月上限，或由人員暫停收集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "收集暫停的原因：limit（已達每月額度）或 staff。收集中時為 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "人員暫停收集的時間"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因達到上限而暫停的解除時間：下個月開始時（UTC），或升級時提前解除。其他情況為 null"
},
{
"type": "null"
}
]
}
},
"description": "本月至今"
}
}
}
POST
/workspaces/:workspace_id/billing/change_plan.json
變更方案、級距或週期（按比例計費）
billing_change_plan
權限： billing.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/change_plan.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "要切換到的方案：pro 或 business",
"enum": [
"pro",
"business"
]
},
"events": {
"type": "integer",
"description": "該級距每月的事件數，來自 GET /plans",
"examples": [
1000000
]
},
"interval": {
"type": "string",
"description": "計費週期。年繳免費 2 個月",
"enum": [
"month",
"year"
],
"default": "month"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"plan",
"events",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付費級距的每月事件數"
},
"allowance": {
"type": "integer",
"description": "每月事件數，包含任何徽章獎勵"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每個計費週期的美元金額"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "續訂或結束時間"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未套用到訂閱）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 與 Business 的折扣百分比（免費開源方案為 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免費事件數（僅限免費開源方案）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "組織、學校、專案或代理商名稱"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "網站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "證明連結或儲存庫網址"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 授權（開源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "給審核人員的備註"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申請未獲核准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申請時間"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "審核時間"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效時間"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "方案結束時間"
},
{
"type": "null"
}
]
}
},
"description": "最近一次的折扣方案申請，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已核准方案提供的 Pro 與 Business 折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章獎勵（免費方案）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所回報月份的第一天"
},
"events": {
"type": "integer",
"description": "計費事件（瀏覽量與自訂事件）"
},
"bots": {
"type": "integer",
"description": "已濾除的機器人請求（不計費）"
},
"allowance": {
"type": "integer",
"description": "包含的事件數，含徽章獎勵"
},
"percent": {
"type": "number",
"description": "事件數佔額度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "預估的月底事件數"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩餘天數"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（過去某月達到或超過額度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的瀏覽量與自訂事件"
},
"share": {
"type": "number",
"description": "佔工作區總量的百分比"
}
}
},
"description": "各網站的事件數"
},
"history": {
"type": "array",
"description": "先前的月份，由新到舊排列"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "儀表板被 Privatus Analytics 人員鎖定的起始時間"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被捨棄期間為 true（已達每月上限，或由人員暫停收集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "收集暫停的原因：limit（已達每月額度）或 staff。收集中時為 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "人員暫停收集的時間"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因達到上限而暫停的解除時間：下個月開始時（UTC），或升級時提前解除。其他情況為 null"
},
{
"type": "null"
}
]
}
},
"description": "本月至今"
}
}
}
POST
/workspaces/:workspace_id/billing/checkout.json
開始付費方案的 Paddle 結帳
billing_checkout
權限： billing.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/checkout.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "要切換到的方案：pro 或 business",
"enum": [
"pro",
"business"
]
},
"events": {
"type": "integer",
"description": "該級距每月的事件數，來自 GET /plans",
"examples": [
1000000
]
},
"interval": {
"type": "string",
"description": "計費週期。年繳免費 2 個月",
"enum": [
"month",
"year"
],
"default": "month"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"plan",
"events",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Paddle 交易 id（txn_...）"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "託管結帳網址"
},
{
"type": "null"
}
]
},
"price_id": {
"type": "string"
},
"plan": {
"type": "string"
},
"events": {
"type": "integer"
},
"interval": {
"type": "string"
},
"amount": {
"type": "integer",
"description": "每個週期的美元金額"
},
"client_token": {
"anyOf": [
{
"type": "string",
"description": "Paddle.js 用戶端 token"
},
{
"type": "null"
}
]
},
"environment": {
"type": "string",
"description": "sandbox 或 production"
},
"custom_data": {
"type": "object",
"description": "傳給 Paddle 以連結訂閱"
},
"discount_id": {
"anyOf": [
{
"type": "string",
"description": "已核准方案的 Paddle 折扣 id，會套用到此次結帳"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/billing/discount.json
申請非營利、教育或開源折扣
billing_discount
權限： billing.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/discount.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source（5 折）、open_source_free（每月 100 萬個事件以內免費使用 Pro）或 agency（您擁有的每個工作區 8 折）",
"enum": [
"nonprofit",
"education",
"open_source",
"open_source_free",
"agency"
]
},
"organization_name": {
"type": "string",
"description": "組織、學校、專案或代理商的名稱"
},
"website": {
"type": "string",
"description": "其網站"
},
"proof_url": {
"type": "string",
"description": "證明連結。開源專案請填儲存庫網址"
},
"license": {
"type": "string",
"description": "專案的 OSI 授權（僅限開源）"
},
"note": {
"type": "string",
"description": "任何有助於審核的說明，最多 1,000 個字元"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"program",
"organization_name",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未套用到訂閱）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 與 Business 的折扣百分比（免費開源方案為 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免費事件數（僅限免費開源方案）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "組織、學校、專案或代理商名稱"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "網站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "證明連結或儲存庫網址"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 授權（開源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "給審核人員的備註"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申請未獲核准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申請時間"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "審核時間"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效時間"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "方案結束時間"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/billing/payment_method.json
取得更新付款方式的連結
billing_payment_method
權限： billing.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/payment_method.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "portal、payment_method 或 invoice"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "短效的 Paddle 網址"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/billing/portal.json
取得 Paddle 客戶入口網站連結
billing_portal
權限： billing.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/portal.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "portal、payment_method 或 invoice"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "短效的 Paddle 網址"
},
{
"type": "null"
}
]
}
}
}
GET
/workspaces/:workspace_id/billing/preview.json
預覽方案變更與按比例計費
billing_preview
權限： billing.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/preview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "要切換到的方案：pro 或 business",
"enum": [
"pro",
"business"
]
},
"events": {
"type": "integer",
"description": "該級距每月的事件數，來自 GET /plans",
"examples": [
1000000
]
},
"interval": {
"type": "string",
"description": "計費週期。年繳免費 2 個月",
"enum": [
"month",
"year"
],
"default": "month"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"plan",
"events",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"plan": {
"type": "string"
},
"events": {
"type": "integer"
},
"interval": {
"type": "string"
},
"price_id": {
"type": "string"
},
"amount": {
"type": "integer",
"description": "新價格，每個週期的美元金額"
},
"currency": {
"type": "string"
},
"charge_minor": {
"type": "integer",
"description": "現在收取的金額，以最小單位計"
},
"credit_minor": {
"type": "integer",
"description": "未使用時間的抵扣額，以最小單位計"
},
"result_action": {
"anyOf": [
{
"type": "string",
"description": "charge 或 credit"
},
{
"type": "null"
}
]
},
"result_minor": {
"type": "integer",
"description": "淨收費或抵扣額，以最小單位計"
},
"next_billed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "新方案無法涵蓋的用量或限制"
}
}
}
POST
/workspaces/:workspace_id/billing/resume.json
復原已排程的取消或恢復暫停
billing_resume
權限： billing.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/resume.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付費級距的每月事件數"
},
"allowance": {
"type": "integer",
"description": "每月事件數，包含任何徽章獎勵"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每個計費週期的美元金額"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "續訂或結束時間"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未套用到訂閱）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 與 Business 的折扣百分比（免費開源方案為 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免費事件數（僅限免費開源方案）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "組織、學校、專案或代理商名稱"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "網站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "證明連結或儲存庫網址"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 授權（開源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "給審核人員的備註"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申請未獲核准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申請時間"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "審核時間"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效時間"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "方案結束時間"
},
{
"type": "null"
}
]
}
},
"description": "最近一次的折扣方案申請，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已核准方案提供的 Pro 與 Business 折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章獎勵（免費方案）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所回報月份的第一天"
},
"events": {
"type": "integer",
"description": "計費事件（瀏覽量與自訂事件）"
},
"bots": {
"type": "integer",
"description": "已濾除的機器人請求（不計費）"
},
"allowance": {
"type": "integer",
"description": "包含的事件數，含徽章獎勵"
},
"percent": {
"type": "number",
"description": "事件數佔額度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "預估的月底事件數"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩餘天數"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（過去某月達到或超過額度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的瀏覽量與自訂事件"
},
"share": {
"type": "number",
"description": "佔工作區總量的百分比"
}
}
},
"description": "各網站的事件數"
},
"history": {
"type": "array",
"description": "先前的月份，由新到舊排列"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "儀表板被 Privatus Analytics 人員鎖定的起始時間"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被捨棄期間為 true（已達每月上限，或由人員暫停收集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "收集暫停的原因：limit（已達每月額度）或 staff。收集中時為 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "人員暫停收集的時間"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因達到上限而暫停的解除時間：下個月開始時（UTC），或升級時提前解除。其他情況為 null"
},
{
"type": "null"
}
]
}
},
"description": "本月至今"
}
}
}
GET
/workspaces/:workspace_id/billing.json
取得方案、訂閱與用量
billing_get
權限： billing.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/billing.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付費級距的每月事件數"
},
"allowance": {
"type": "integer",
"description": "每月事件數，包含任何徽章獎勵"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每個計費週期的美元金額"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "續訂或結束時間"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未套用到訂閱）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 與 Business 的折扣百分比（免費開源方案為 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免費事件數（僅限免費開源方案）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "組織、學校、專案或代理商名稱"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "網站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "證明連結或儲存庫網址"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 授權（開源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "給審核人員的備註"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申請未獲核准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申請時間"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "審核時間"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效時間"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "方案結束時間"
},
{
"type": "null"
}
]
}
},
"description": "最近一次的折扣方案申請，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已核准方案提供的 Pro 與 Business 折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章獎勵（免費方案）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所回報月份的第一天"
},
"events": {
"type": "integer",
"description": "計費事件（瀏覽量與自訂事件）"
},
"bots": {
"type": "integer",
"description": "已濾除的機器人請求（不計費）"
},
"allowance": {
"type": "integer",
"description": "包含的事件數，含徽章獎勵"
},
"percent": {
"type": "number",
"description": "事件數佔額度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "預估的月底事件數"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩餘天數"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（過去某月達到或超過額度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的瀏覽量與自訂事件"
},
"share": {
"type": "number",
"description": "佔工作區總量的百分比"
}
}
},
"description": "各網站的事件數"
},
"history": {
"type": "array",
"description": "先前的月份，由新到舊排列"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "儀表板被 Privatus Analytics 人員鎖定的起始時間"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被捨棄期間為 true（已達每月上限，或由人員暫停收集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "收集暫停的原因：limit（已達每月額度）或 staff。收集中時為 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "人員暫停收集的時間"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因達到上限而暫停的解除時間：下個月開始時（UTC），或升級時提前解除。其他情況為 null"
},
{
"type": "null"
}
]
}
},
"description": "本月至今"
}
}
}
PATCH
/workspaces/:workspace_id/billing.json
更新帳單電子郵件、稅籍編號與自動升級
billing_update
權限： billing.manage
範例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/billing.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"billing_emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "發票與帳單通知的額外地址（最多 5 個）"
},
"tax_id": {
"type": "string",
"description": "顯示在發票上的 VAT/GST/稅籍編號"
},
"auto_upgrade": {
"type": "boolean",
"description": "設為 true 時，達到每月上限會升到下一個級距並收取差額，而不是暫停收集。預設為關閉"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"plan_events": {
"type": "integer",
"description": "付費級距的每月事件數"
},
"allowance": {
"type": "integer",
"description": "每月事件數，包含任何徽章獎勵"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month 或 year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "每個計費週期的美元金額"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none、trialing、active、past_due、paused 或 canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "續訂或結束時間"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit、education、open_source、open_source_free 或 agency"
},
"status": {
"type": "string",
"description": "pending、approved（尚未套用到訂閱）、active、rejected 或 revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Pro 與 Business 的折扣百分比（免費開源方案為 null）"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "每月免費事件數（僅限免費開源方案）"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "組織、學校、專案或代理商名稱"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "網站"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "證明連結或儲存庫網址"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI 授權（開源）"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "給審核人員的備註"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "申請未獲核准的原因"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "申請時間"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "審核時間"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "折扣生效時間"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "方案結束時間"
},
{
"type": "null"
}
]
}
},
"description": "最近一次的折扣方案申請，或 null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "已核准方案提供的 Pro 與 Business 折扣百分比，或 null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "徽章獎勵（免費方案）"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所回報月份的第一天"
},
"events": {
"type": "integer",
"description": "計費事件（瀏覽量與自訂事件）"
},
"bots": {
"type": "integer",
"description": "已濾除的機器人請求（不計費）"
},
"allowance": {
"type": "integer",
"description": "包含的事件數，含徽章獎勵"
},
"percent": {
"type": "number",
"description": "事件數佔額度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "預估的月底事件數"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩餘天數"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（過去某月達到或超過額度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的瀏覽量與自訂事件"
},
"share": {
"type": "number",
"description": "佔工作區總量的百分比"
}
}
},
"description": "各網站的事件數"
},
"history": {
"type": "array",
"description": "先前的月份，由新到舊排列"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "儀表板被 Privatus Analytics 人員鎖定的起始時間"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被捨棄期間為 true（已達每月上限，或由人員暫停收集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "收集暫停的原因：limit（已達每月額度）或 staff。收集中時為 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "人員暫停收集的時間"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因達到上限而暫停的解除時間：下個月開始時（UTC），或升級時提前解除。其他情況為 null"
},
{
"type": "null"
}
]
}
},
"description": "本月至今"
}
}
}
GET
/workspaces/:workspace_id/billing/usage.json
取得本月用量、預測與各網站分配
billing_usage
權限： billing.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/usage.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "要回報之月份中的任一天（預設為本月）",
"examples": [
"2026-09-01"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "所回報月份的第一天"
},
"events": {
"type": "integer",
"description": "計費事件（瀏覽量與自訂事件）"
},
"bots": {
"type": "integer",
"description": "已濾除的機器人請求（不計費）"
},
"allowance": {
"type": "integer",
"description": "包含的事件數，含徽章獎勵"
},
"percent": {
"type": "number",
"description": "事件數佔額度的百分比"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "預估的月底事件數"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "本月剩餘天數"
},
"status": {
"type": "string",
"description": "ok、warning（80% 以上）、over（過去某月達到或超過額度）、locked 或 paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "本月的瀏覽量與自訂事件"
},
"share": {
"type": "number",
"description": "佔工作區總量的百分比"
}
}
},
"description": "各網站的事件數"
},
"history": {
"type": "array",
"description": "先前的月份，由新到舊排列"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "儀表板被 Privatus Analytics 人員鎖定的起始時間"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "新事件被捨棄期間為 true（已達每月上限，或由人員暫停收集）"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "收集暫停的原因：limit（已達每月額度）或 staff。收集中時為 null"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "人員暫停收集的時間"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "因達到上限而暫停的解除時間：下個月開始時（UTC），或升級時提前解除。其他情況為 null"
},
{
"type": "null"
}
]
}
}
}
GET
/workspaces/:workspace_id/billing/invoices.json
列出發票
billing_invoices_list
權限： billing.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/invoices.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Paddle 交易 id"
},
"invoice_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "paid、completed、payment_failed、..."
},
"amount_minor": {
"type": "integer",
"description": "以最小單位（分）計的總額"
},
"currency": {
"type": "string"
},
"billed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
}
}
}
GET
/workspaces/:workspace_id/billing/invoices/:id.json
取得發票的 PDF 連結
billing_invoices_get
權限： billing.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/invoices/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "portal、payment_method 或 invoice"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "短效的 Paddle 網址"
},
{
"type": "null"
}
]
}
}
}
帳號
GET
/account.json
取得您的個人資料與偏好設定
account_get
權限： member
範例
curl https://privatusanalytics.com/account.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {},
"required": []
}
回應資料
{
"type": "object",
"properties": {
"email": {
"type": "string"
},
"unconfirmed_email": {
"anyOf": [
{
"type": "string",
"description": "等待確認的新電子郵件"
},
{
"type": "null"
}
]
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"theme": {
"type": "string"
},
"default_landing": {
"type": "string"
},
"locale": {
"type": "string",
"description": "此帳號的應用程式語言代碼（預設為 en）"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"shortcuts_enabled": {
"type": "boolean"
},
"reduce_motion": {
"type": "boolean"
},
"product_emails": {
"type": "boolean"
},
"marketing_emails": {
"type": "boolean",
"description": "是否可寄送行銷電子郵件（自動化行銷活動）。取消訂閱後為 false"
},
"newsletter": {
"type": "boolean"
},
"two_factor": {
"type": "boolean"
},
"passkeys": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/account.json
更新您的個人資料與偏好設定
account_update
權限： member
範例
curl -X PATCH https://privatusanalytics.com/account.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "您的名稱"
},
"email": {
"type": "string",
"description": "新的電子郵件地址（會先以電子郵件確認）"
},
"theme": {
"type": "string",
"description": "色彩主題",
"enum": [
"system",
"light",
"dark"
]
},
"default_landing": {
"type": "string",
"description": "登入後的頁面：sites 或 last_site",
"enum": [
"sites",
"last_site"
]
},
"locale": {
"type": "string",
"description": "您登入時應用程式的語言，以語言代碼表示（en、de、fr 等）。公開頁面與 API 維持不變",
"enum": [
"en",
"de",
"es",
"fr",
"it",
"nl",
"pt",
"pl",
"sv",
"da",
"no",
"fi",
"ja",
"ko",
"zh-CN",
"zh-TW"
]
},
"timezone": {
"type": "string",
"description": "您的時區（IANA 名稱）"
},
"shortcuts_enabled": {
"type": "boolean",
"description": "鍵盤快速鍵"
},
"reduce_motion": {
"type": "boolean",
"description": "減少動畫"
},
"product_emails": {
"type": "boolean",
"description": "產品更新與小技巧電子郵件"
},
"marketing_emails": {
"type": "boolean",
"description": "行銷電子郵件，例如新手上路小技巧。取消訂閱後若要重新開啟，需使用已登入的瀏覽器"
},
"newsletter": {
"type": "boolean",
"description": "每月電子報"
}
},
"required": []
}
回應資料
{
"type": "object",
"properties": {
"email": {
"type": "string"
},
"unconfirmed_email": {
"anyOf": [
{
"type": "string",
"description": "等待確認的新電子郵件"
},
{
"type": "null"
}
]
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"theme": {
"type": "string"
},
"default_landing": {
"type": "string"
},
"locale": {
"type": "string",
"description": "此帳號的應用程式語言代碼（預設為 en）"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"shortcuts_enabled": {
"type": "boolean"
},
"reduce_motion": {
"type": "boolean"
},
"product_emails": {
"type": "boolean"
},
"marketing_emails": {
"type": "boolean",
"description": "是否可寄送行銷電子郵件（自動化行銷活動）。取消訂閱後為 false"
},
"newsletter": {
"type": "boolean"
},
"two_factor": {
"type": "boolean"
},
"passkeys": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
成員
POST
/workspaces/:workspace_id/invitations.json
透過電子郵件邀請成員
invitations_create
權限： members.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/invitations.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "要邀請的電子郵件地址"
},
"role": {
"type": "string",
"description": "新成員的角色（custom 需要 custom_role_id）",
"enum": [
"admin",
"editor",
"analyst",
"viewer",
"billing",
"custom"
],
"default": "viewer"
},
"custom_role_id": {
"type": "string",
"description": "自訂角色 id（Business）"
},
"all_sites": {
"type": "boolean",
"description": "存取所有網站，包含未來新增的",
"default": true
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 為 false 時的網站 id（pa_…）",
"default": []
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"emails",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"role": {
"type": "string"
},
"custom_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/invitations/:id.json
撤銷待處理的邀請
invitations_delete
權限： members.manage
範例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/invitations/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"role": {
"type": "string"
},
"custom_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/invitations.json
列出待處理的邀請
invitations_list
權限： members.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/invitations.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"role": {
"type": "string"
},
"custom_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
DELETE
/workspaces/:workspace_id/members/:id.json
移除成員（或離開工作區）
members_delete
權限： member
範例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/members/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成員 id（用來更新或移除成員）"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner、admin、editor、analyst、viewer、billing 或 custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "自訂角色名稱"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "存取所有網站"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 為 false 時的網站 id"
},
"two_factor": {
"type": "boolean",
"description": "已有 2FA 或通行金鑰"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "加入時間"
}
}
}
GET
/workspaces/:workspace_id/members.json
列出工作區成員
members_list
權限： member
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/members.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "依名稱或電子郵件篩選"
},
"role": {
"type": "string",
"description": "僅此角色的成員",
"enum": [
"owner",
"admin",
"editor",
"analyst",
"viewer",
"billing",
"custom"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成員 id（用來更新或移除成員）"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner、admin、editor、analyst、viewer、billing 或 custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "自訂角色名稱"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "存取所有網站"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 為 false 時的網站 id"
},
"two_factor": {
"type": "boolean",
"description": "已有 2FA 或通行金鑰"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "加入時間"
}
}
}
}
PATCH
/workspaces/:workspace_id/members/:id.json
變更成員的角色或網站存取權
members_update
權限： members.manage
範例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/members/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"role": {
"type": "string",
"description": "新角色（custom 需要 custom_role_id）",
"enum": [
"admin",
"editor",
"analyst",
"viewer",
"billing",
"custom"
]
},
"custom_role_id": {
"type": "string",
"description": "自訂角色 id（Business）"
},
"all_sites": {
"type": "boolean",
"description": "存取所有網站，包含未來新增的"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 為 false 時的網站 id（pa_…）"
},
"include_future_sites": {
"type": "boolean",
"description": "同時授予之後新增的網站"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成員 id（用來更新或移除成員）"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner、admin、editor、analyst、viewer、billing 或 custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "自訂角色名稱"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "存取所有網站"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 為 false 時的網站 id"
},
"two_factor": {
"type": "boolean",
"description": "已有 2FA 或通行金鑰"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "加入時間"
}
}
}
POST
/workspaces/:workspace_id/ownership_transfer.json
將工作區擁有權轉移給另一位成員（僅限擁有者，您將成為管理員）
ownership_transfers_create
權限： member
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/ownership_transfer.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"description": "新擁有者的成員 id"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"membership_id",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成員 id（用來更新或移除成員）"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner、admin、editor、analyst、viewer、billing 或 custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "自訂角色名稱"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "存取所有網站"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "all_sites 為 false 時的網站 id"
},
"two_factor": {
"type": "boolean",
"description": "已有 2FA 或通行金鑰"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "加入時間"
}
}
}
搜尋
GET
/sites/:site_id/search.json
搜尋報告：點擊、曝光、CTR、排名、熱門查詢與頁面、登陸頁與機會
search_report
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/search.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"provider": {
"type": "string",
"description": "google（Search Console）或 bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"limit": {
"type": "integer",
"description": "每個表格的列數（最多 100）",
"default": 25
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
POST
/sites/:site_id/search/connections.json
連接 Search Console 資源或 Bing 網站
search_connect
權限： sites.manage
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/search/connections.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"property": {
"type": "string",
"description": "Search Console 資源（例如 sc-domain:example.com）或 Bing 網站網址",
"examples": [
"sc-domain:example.com"
]
},
"bing_api_key": {
"type": "string",
"description": "您自己的 Bing Webmaster Tools API 金鑰（Settings > API access）。provider 為 bing 時必填。以加密方式儲存，絕不回傳。"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"property",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing"
},
"property": {
"type": "string",
"description": "Search Console 資源或 Bing 網站網址"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/search/connections/:provider.json
中斷 Search Console 或 Bing 的連接並刪除其資料
search_disconnect
權限： sites.manage
範例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/search/connections/:provider.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"provider": {
"type": "string",
"description": "資源的 Provider"
}
},
"required": [
"site_id",
"provider"
]
}
回應資料
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing"
},
"property": {
"type": "string",
"description": "Search Console 資源或 Bing 網站網址"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/search/properties.json
列出您可連接的資源（Search Console 需要從瀏覽器取得 Google 授權）
search_properties
權限： sites.manage
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/search/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"bing_api_key": {
"type": "string",
"description": "您自己的 Bing Webmaster Tools API 金鑰（Settings > API access）。provider 為 bing 時必填。僅用於列出它能看到的網站。"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
POST
/sites/:site_id/search/sync.json
立即匯入搜尋資料
search_sync
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google 或 bing"
},
"property": {
"type": "string",
"description": "Search Console 資源或 Bing 網站網址"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
收集
POST
/api/logs.json
傳送伺服器存取記錄以產生 AI 爬蟲報告（JSON {lines: [...]} 或 combined 記錄文字，以網站擷取金鑰作為 Bearer token）
crawler_logs_create
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/api/logs.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ts": {
"type": "string"
},
"path": {
"type": "string",
"default": "/"
},
"status": {
"type": "integer"
},
"user_agent": {
"type": "string",
"default": ""
}
}
},
"description": "記錄行：[{ts, path, status, user_agent}]（最多 1000）"
}
},
"required": [
"lines"
]
}
回應資料
{
"type": "object"
}
POST
/api/event.json
收集瀏覽器請求（由 /js/pa.js 使用）
ingest_event
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/api/event.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site": {
"type": "string",
"description": "網站 id（pa_…）"
},
"type": {
"type": "string",
"description": "請求類型",
"enum": [
"pageview",
"event",
"engagement",
"vital",
"click"
]
},
"url": {
"type": "string",
"description": "完整頁面網址"
},
"referrer": {
"type": "string",
"description": "document.referrer"
},
"name": {
"type": "string",
"description": "事件名稱（type=event）或 vital 名稱"
},
"props": {
"type": "object",
"additionalProperties": true,
"description": "事件屬性：最多 30 個字串、數字或布林值",
"default": {}
},
"screen_width": {
"type": "integer",
"description": "螢幕寬度（像素）"
},
"language": {
"type": "string",
"description": "navigator.language"
},
"engaged_ms": {
"type": "integer",
"description": "頁面可見時間（互動）"
},
"scroll_depth": {
"type": "integer",
"description": "最大捲動深度百分比（互動）"
},
"value": {
"type": "number",
"description": "Web Vital 值（type=vital）"
},
"selector": {
"type": "string",
"description": "被點擊元素的選擇器（type=click）"
},
"hash_mode": {
"type": "boolean",
"description": "保留 #fragment（使用 hash 路由的網站）",
"default": false
},
"dnt": {
"type": "boolean",
"description": "已開啟 Do Not Track",
"default": false
},
"gpc": {
"type": "boolean",
"description": "已開啟 Global Privacy Control",
"default": false
},
"interacted": {
"type": "boolean",
"description": "在頁面上看過可信任的輸入（指標、按鍵、觸控或滾輪）為 1，否則為 0。不含座標或時間"
},
"revenue": {
"type": "number",
"description": "以主要單位計的營收，例如 49.99"
},
"currency": {
"type": "string",
"description": "營收的 ISO 4217 貨幣"
}
},
"required": [
"site",
"type",
"url"
]
}
回應資料
{
"type": "object"
}
POST
/api/events.json
使用網站擷取金鑰收集伺服器端事件
ingest_events
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/api/events.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "最多 100 個事件"
}
},
"required": [
"events"
]
}
回應資料
{
"type": "object"
}
GET
/api/pixel.json
不使用 JavaScript 收集瀏覽量（1×1 GIF）
ingest_pixel
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl https://privatusanalytics.com/api/pixel.json輸入
{
"type": "object",
"properties": {},
"required": []
}
回應資料
{
"type": "object"
}
效能
GET
/sites/:site_id/performance.json
Web Vitals：p75 計分卡、每日趨勢，以及依頁面、裝置、瀏覽器和國家的細分
performance_report
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/performance.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"metric": {
"type": "string",
"description": "趨勢與細分所用的指標",
"enum": [
"LCP",
"INP",
"CLS",
"FCP",
"TTFB"
],
"default": "LCP"
},
"limit": {
"type": "integer",
"description": "每個細分的列數（最多 100）",
"default": 10
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
文件
GET
/docs/api.json
列出所有 API 操作與 MCP 工具
docs_api
權限： public
範例
curl https://privatusanalytics.com/docs/api.json輸入
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": []
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"tool_name": {
"type": "string",
"description": "MCP 工具名稱與 OpenAPI operationId"
},
"summary": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"group": {
"type": "string"
},
"verb": {
"type": "string",
"description": "HTTP 方法"
},
"path": {
"type": "string",
"description": "路徑範本。加上 .json 取得 JSON"
},
"permission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"input_schema": {
"type": "object",
"description": "輸入的 JSON Schema"
},
"response_schema": {
"type": "object",
"description": "`data` 的 JSON Schema"
}
}
}
}
GET
/docs.json
列出文件頁面
docs_list
權限： public
範例
curl https://privatusanalytics.com/docs.json輸入
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": []
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "頁面標題"
},
"description": {
"type": "string",
"description": "一句話摘要"
},
"path": {
"type": "string",
"description": "頁面路徑。加上 .md 取得 Markdown，或加上 .json 取得 JSON"
},
"section": {
"type": "string",
"description": "章節代稱，例如 tracker"
}
}
}
}
GET
/openapi.json
整個 API 的 OpenAPI 3.1 文件
docs_openapi
權限： public
範例
curl https://privatusanalytics.com/openapi.json輸入
{
"type": "object",
"properties": {},
"required": []
}
回應資料
{
"type": "object"
}
GET
/docs/search.json
搜尋文件
docs_search
權限： public
範例
curl https://privatusanalytics.com/docs/search.json輸入
{
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "搜尋文字。留空則回傳每個頁面。",
"examples": [
"content security policy"
]
},
"limit": {
"type": "integer",
"description": "最多結果數（預設：有 q 時為 20，沒有則為全部）"
}
},
"required": []
}
回應資料
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "頁面標題"
},
"path": {
"type": "string",
"description": "頁面路徑"
},
"section": {
"type": "string",
"description": "章節標題"
},
"headings": {
"type": "array",
"items": {
"type": "object"
},
"description": "頁面上的標題：{ id, text }"
},
"excerpt": {
"type": "string",
"description": "說明或開頭的句子"
},
"score": {
"anyOf": [
{
"type": "integer",
"description": "相關度（僅在以 q 搜尋時）"
},
{
"type": "null"
}
]
}
}
}
GET
/docs/:section/:page.json
閱讀文件頁面（Markdown 與 HTML）
docs_get
section 和 page 來自頁面路徑 /docs/<section>/<page>。章節總覽請使用 page "index"。
權限： public
範例
curl https://privatusanalytics.com/docs/:section/:page.json輸入
{
"type": "object",
"properties": {
"section": {
"type": "string",
"description": "資源的 Section"
},
"page": {
"type": "string",
"description": "資源的 Page"
}
},
"required": [
"section",
"page"
]
}
回應資料
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "頁面標題"
},
"description": {
"type": "string",
"description": "一句話摘要"
},
"path": {
"type": "string",
"description": "頁面路徑。加上 .md 取得 Markdown，或加上 .json 取得 JSON"
},
"section": {
"type": "string",
"description": "章節代稱，例如 tracker"
},
"headings": {
"type": "array",
"items": {
"type": "object"
},
"description": "頁面上的章節（id 與文字）"
},
"full_markdown": {
"type": "string",
"description": "以 Markdown 呈現的頁面（含標題）"
},
"html": {
"type": "string",
"description": "以 HTML 呈現的頁面內文"
}
}
}
方案
GET
/plans.json
列出方案、價格與限制
plans_list
權限： public
範例
curl https://privatusanalytics.com/plans.json輸入
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": []
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "free、pro、business 或 enterprise"
},
"events": {
"anyOf": [
{
"type": "integer",
"description": "每月包含的事件數（僅免費方案）"
},
{
"type": "null"
}
]
},
"badge_bonus": {
"anyOf": [
{
"type": "integer",
"description": "顯示徽章可額外獲得的每月事件數（免費方案）"
},
{
"type": "null"
}
]
},
"limits": {
"type": "object",
"description": "方案限制。Null 表示無限制"
},
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"events": {
"type": "integer",
"description": "包含的每月事件數"
},
"monthly": {
"type": "integer",
"description": "每月美元金額，按月計費"
},
"yearly": {
"type": "integer",
"description": "每年美元金額，按年計費（免費 2 個月）"
},
"monthly_price_id": {
"anyOf": [
{
"type": "string",
"description": "Paddle 價格 id（月繳）"
},
{
"type": "null"
}
]
},
"yearly_price_id": {
"anyOf": [
{
"type": "string",
"description": "Paddle 價格 id（年繳）"
},
{
"type": "null"
}
]
}
}
},
"description": "依每月事件數的價格階梯"
},
"contact_sales": {
"type": "boolean",
"description": "依合約報價"
}
}
}
}
流量規則
POST
/sites/:site_id/traffic_rules.json
新增流量規則
traffic_rules_create
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"list": {
"type": "string",
"description": "hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events",
"enum": [
"hostnames",
"paths",
"referrers",
"countries",
"ip_ranges",
"user_agents",
"events"
]
},
"pattern": {
"type": "string",
"description": "要比對的值。* 是萬用字元。ip_ranges 接受 IP 或 CIDR（v4/v6），countries 接受 ISO 代碼",
"examples": [
"/admin/*"
]
},
"label": {
"type": "string",
"description": "選填備註，例如 \"Office\""
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"list",
"pattern",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "規則 id"
},
"list": {
"type": "string",
"description": "hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events"
},
"pattern": {
"type": "string",
"description": "模式（* 萬用字元，ip_ranges 用 CIDR）"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block 或 allow（其清單的模式）"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/traffic_rules/:id.json
刪除流量規則
traffic_rules_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "規則 id"
},
"list": {
"type": "string",
"description": "hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events"
},
"pattern": {
"type": "string",
"description": "模式（* 萬用字元，ip_ranges 用 CIDR）"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block 或 allow（其清單的模式）"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/traffic_rules.json
列出流量規則
traffic_rules_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/traffic_rules.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"list": {
"type": "string",
"description": "僅此清單中的規則",
"enum": [
"hostnames",
"paths",
"referrers",
"countries",
"ip_ranges",
"user_agents",
"events"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "規則 id"
},
"list": {
"type": "string",
"description": "hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events"
},
"pattern": {
"type": "string",
"description": "模式（* 萬用字元，ip_ranges 用 CIDR）"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block 或 allow（其清單的模式）"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/traffic_rules/test.json
測試某個請求在網站目前的規則下是否會被計入
traffic_rules_test
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "頁面網址，例如 https://example.com/a"
},
"referrer": {
"type": "string",
"description": "來源網址或主機名稱"
},
"country": {
"type": "string",
"description": "ISO 國家代碼，例如 US"
},
"ip": {
"type": "string",
"description": "用來對照 ip_ranges 測試的 IP 位址（不會儲存）"
},
"user_agent": {
"type": "string",
"description": "User-Agent 字串（如同擷取時一樣，簡化為瀏覽器與主要版本）"
},
"event": {
"type": "string",
"description": "自訂事件名稱"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
PATCH
/sites/:site_id/traffic_rules/:id.json
變更流量規則
traffic_rules_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"pattern": {
"type": "string",
"description": "新的模式"
},
"label": {
"type": "string",
"description": "新的標籤"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "規則 id"
},
"list": {
"type": "string",
"description": "hostnames、paths、referrers、countries、ip_ranges、user_agents 或 events"
},
"pattern": {
"type": "string",
"description": "模式（* 萬用字元，ip_ranges 用 CIDR）"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block 或 allow（其清單的模式）"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
漏斗
POST
/sites/:site_id/funnels.json
建立漏斗
funnels_create
權限： content.write
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/funnels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "漏斗名稱",
"examples": [
"Signup flow"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "依序的步驟（2 到您方案的上限）：[{\"type\": \"page|event|goal\", \"value\": \"/pricing | Signup | goal_…\", \"match\": \"exact|prefix|glob|regex\" (page steps), \"name\": \"optional label\"}]"
},
"order_mode": {
"type": "string",
"description": "strict：依此順序的步驟，any：任意順序",
"enum": [
"strict",
"any"
],
"default": "strict"
},
"window": {
"type": "string",
"description": "轉換視窗：visit，或 day（在一次造訪內計算，造訪不會跨越 UTC 日）",
"enum": [
"visit",
"day"
],
"default": "visit"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"steps",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "漏斗 id，例如 fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "步驟：{type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "到達步驟 1 的造訪數"
},
"completed": {
"type": "integer",
"description": "到達最後一步的造訪數"
},
"conversion_rate": {
"type": "number",
"description": "完成 ÷ 進入，%"
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/funnels/:id.json
刪除漏斗
funnels_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "漏斗 id，例如 fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "步驟：{type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "到達步驟 1 的造訪數"
},
"completed": {
"type": "integer",
"description": "到達最後一步的造訪數"
},
"conversion_rate": {
"type": "number",
"description": "完成 ÷ 進入，%"
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/funnels.json
列出漏斗，含進入數、完成數與比率
funnels_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/funnels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"page": {
"type": "integer",
"description": "頁碼",
"default": 1
},
"per_page": {
"type": "integer",
"description": "每頁漏斗數（最多 100）",
"default": 25
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "漏斗 id，例如 fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "步驟：{type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "到達步驟 1 的造訪數"
},
"completed": {
"type": "integer",
"description": "到達最後一步的造訪數"
},
"conversion_rate": {
"type": "number",
"description": "完成 ÷ 進入，%"
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/funnels/:id.json
漏斗報告：各步驟人數、轉換、流失、步驟間耗時，以及訪客改去了哪裡
funnels_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/funnels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"breakdown": {
"type": "string",
"description": "依造訪維度拆分各步驟人數",
"enum": [
"channel",
"device",
"country",
"utm_campaign",
"utm_source",
"browser",
"os"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "期間的 from/to（UTC）"
},
"funnel": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "漏斗 id，例如 fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "步驟：{type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "到達步驟 1 的造訪數"
},
"completed": {
"type": "integer",
"description": "到達最後一步的造訪數"
},
"conversion_rate": {
"type": "number",
"description": "完成 ÷ 進入，%"
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"description": "漏斗定義"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day（day 在一次造訪內計算）"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "每個步驟：index、name、type、value、count、step_conversion_rate、overall_conversion_rate、dropoff、dropoff_rate、median_seconds_from_previous、next_pages [{value, count}]"
},
"overall_conversion_rate": {
"type": "number",
"description": "最後一步 ÷ 第一步，%"
},
"breakdown": {
"anyOf": [
{
"type": "object",
"description": "dimension、label 與列 [{value, counts, overall_conversion_rate}]"
},
{
"type": "null"
}
]
},
"comparison": {
"anyOf": [
{
"type": "object",
"description": "period、各步驟人數、overall_conversion_rate 與變化（%）"
},
{
"type": "null"
}
]
}
}
}
PATCH
/sites/:site_id/funnels/:id.json
更新漏斗
funnels_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "漏斗名稱",
"examples": [
"Signup flow"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "依序的步驟（2 到您方案的上限）：[{\"type\": \"page|event|goal\", \"value\": \"/pricing | Signup | goal_…\", \"match\": \"exact|prefix|glob|regex\" (page steps), \"name\": \"optional label\"}]"
},
"order_mode": {
"type": "string",
"description": "strict：依此順序的步驟，any：任意順序",
"enum": [
"strict",
"any"
]
},
"window": {
"type": "string",
"description": "轉換視窗：visit，或 day（在一次造訪內計算，造訪不會跨越 UTC 日）",
"enum": [
"visit",
"day"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "漏斗 id，例如 fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "步驟：{type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict 或 any"
},
"window": {
"type": "string",
"description": "visit 或 day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "到達步驟 1 的造訪數"
},
"completed": {
"type": "integer",
"description": "到達最後一步的造訪數"
},
"conversion_rate": {
"type": "number",
"description": "完成 ÷ 進入，%"
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
爬蟲
POST
/sites/:site_id/crawlers/connection.json
從 Cloudflare 區域同步 AI 爬蟲點擊（需要瀏覽器中的 Cloudflare 授權）
crawlers_cloudflare_connect
權限： sites.manage
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/crawlers/connection.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"zone_id": {
"type": "string",
"description": "Cloudflare 區域 id，來自 crawlers_cloudflare_zones",
"examples": [
"023e105f4ecef8ad9ca31a8372d0c353"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"zone_id",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"zone_id": {
"type": "string",
"description": "Cloudflare 區域 id"
},
"zone_name": {
"type": "string",
"description": "Cloudflare 區域名稱，例如 example.com"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次匯入爬蟲點擊的時間，首次匯入前為 null"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/crawlers/connection.json
中斷 Cloudflare 連線，並刪除其匯入的爬蟲點擊
crawlers_cloudflare_disconnect
權限： sites.manage
範例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/crawlers/connection.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"zone_id": {
"type": "string",
"description": "Cloudflare 區域 id"
},
"zone_name": {
"type": "string",
"description": "Cloudflare 區域名稱，例如 example.com"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次匯入爬蟲點擊的時間，首次匯入前為 null"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/crawlers/sync.json
立即從 Cloudflare 匯入爬蟲點擊
crawlers_cloudflare_sync
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"zone_id": {
"type": "string",
"description": "Cloudflare 區域 id"
},
"zone_name": {
"type": "string",
"description": "Cloudflare 區域名稱，例如 example.com"
},
"status": {
"type": "string",
"description": "active 或 error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次匯入爬蟲點擊的時間，首次匯入前為 null"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/crawlers/zones.json
列出您可連線的 Cloudflare 區域（需要瀏覽器中的 Cloudflare 授權）
crawlers_cloudflare_zones
權限： sites.manage
範例
curl https://privatusanalytics.com/sites/:site_id/crawlers/zones.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/crawlers.json
AI 爬蟲報告：各爬蟲隨時間的請求數、每個爬蟲的熱門路徑、依類別
crawlers_report
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/crawlers.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"category": {
"type": "string",
"description": "ai、search、seo、other 或 all",
"enum": [
"all",
"ai",
"search",
"seo",
"other"
],
"default": "ai"
},
"crawler": {
"type": "string",
"description": "僅此爬蟲，例如 GPTBot"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
狀態頁面
GET
/status/:slug/confirm/:token.json
從電子郵件中的連結確認訂閱
public_status_pages_confirm
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl https://privatusanalytics.com/status/:slug/confirm/:token.json輸入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "資源的 Token"
},
"slug": {
"type": "string",
"description": "資源的 Slug"
}
},
"required": [
"token",
"slug"
]
}
回應資料
{
"type": "object"
}
GET
/status/:slug.json
公開狀態頁面：目前狀態、90 天 uptime 長條、事件與貼文
public_status_pages_get
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl https://privatusanalytics.com/status/:slug.json輸入
{
"type": "object",
"properties": {
"slug": {
"type": "string",
"description": "資源的 Slug"
}
},
"required": [
"slug"
]
}
回應資料
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "operational、degraded 或 outage"
},
"checks": {
"type": "array",
"description": "每項：{name, status, uptime_90d, days: [{date, uptime, downtime_seconds}]}"
},
"posts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "貼文 id（spp_…）"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"incidents": {
"type": "array",
"description": "近期事件：{check, started_at, resolved_at, duration_seconds}"
}
}
}
POST
/status/:slug/subscribers.json
訂閱電子郵件地址（雙重確認）
public_status_pages_subscribe
瀏覽器用戶端會以 `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 '{…}'輸入
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "要通知的電子郵件地址",
"examples": [
"[email protected]"
]
},
"slug": {
"type": "string",
"description": "資源的 Slug"
}
},
"required": [
"email",
"slug"
]
}
回應資料
{
"type": "object"
}
POST
/status/:slug/unsubscribe/:token.json
使用電子郵件中的 token 取消訂閱
public_status_pages_unsubscribe
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/status/:slug/unsubscribe/:token.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "資源的 Token"
},
"slug": {
"type": "string",
"description": "資源的 Slug"
}
},
"required": [
"token",
"slug"
]
}
回應資料
{
"type": "object"
}
POST
/status_pages/:status_page_id/posts.json
發布事件更新（會寄電子郵件給訂閱者）
status_page_posts_create
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "標題，例如 \"Elevated error rates\""
},
"body": {
"type": "string",
"description": "更新文字（純文字）"
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"default": "investigating"
},
"posted_at": {
"type": "string",
"format": "date-time",
"description": "發生的時間（預設為現在）"
},
"notify": {
"type": "boolean",
"description": "寄電子郵件給已確認的訂閱者",
"default": true
},
"status_page_id": {
"type": "string",
"description": "資源的 Status page"
}
},
"required": [
"title",
"status_page_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "貼文 id（spp_…）"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/status_pages/:status_page_id/posts/:id.json
刪除狀態頁面貼文
status_page_posts_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"status_page_id": {
"type": "string",
"description": "資源的 Status page"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"status_page_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "貼文 id（spp_…）"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/status_pages/:status_page_id/posts.json
列出狀態頁面上的貼文
status_page_posts_list
權限： analytics.read
範例
curl https://privatusanalytics.com/status_pages/:status_page_id/posts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "僅此狀態的貼文",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"status_page_id": {
"type": "string",
"description": "資源的 Status page"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"status_page_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "貼文 id（spp_…）"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/status_pages/:status_page_id/posts/:id.json
編輯狀態頁面貼文
status_page_posts_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "標題"
},
"body": {
"type": "string",
"description": "更新文字（純文字）"
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"notify": {
"type": "boolean",
"description": "若狀態變更，寄電子郵件給已確認的訂閱者",
"default": true
},
"status_page_id": {
"type": "string",
"description": "資源的 Status page"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"status_page_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "貼文 id（spp_…）"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating、identified、monitoring 或 resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/status_pages/:status_page_id/subscribers/:id.json
移除訂閱者
status_page_subscribers_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"status_page_id": {
"type": "string",
"description": "資源的 Status page"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"status_page_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/status_pages/:status_page_id/subscribers.json
列出狀態頁面的訂閱者
status_page_subscribers_list
權限： uptime.manage
範例
curl https://privatusanalytics.com/status_pages/:status_page_id/subscribers.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"confirmed": {
"type": "boolean",
"description": "true：僅已確認，false：僅待確認"
},
"status_page_id": {
"type": "string",
"description": "資源的 Status page"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"status_page_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/workspaces/:workspace_id/status_pages.json
建立狀態頁面
status_pages_create
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "頁面標題，例如 \"Acme status\""
},
"slug": {
"type": "string",
"description": "公開網址代稱：/status/<slug>（預設取自名稱）"
},
"description": {
"type": "string",
"description": "標題下方的簡介文字"
},
"logo_url": {
"type": "string",
"description": "Logo 圖片的 HTTPS 網址"
},
"brand_color": {
"type": "string",
"description": "強調色，例如 #06755b"
},
"custom_domain": {
"type": "string",
"description": "自訂網域（CNAME 到我們的主機），例如 status.example.com。留空以移除"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要顯示的 uptime 檢查 id（upc_…）"
},
"published": {
"type": "boolean",
"description": "對公眾可見",
"default": true
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "狀態頁面 id（sp_…）"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "公開網址：/status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "顯示的 uptime 檢查 id"
},
"subscribers": {
"type": "integer",
"description": "已確認的訂閱者"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/status_pages/:id.json
刪除狀態頁面
status_pages_delete
權限： uptime.manage
範例
curl -X DELETE https://privatusanalytics.com/status_pages/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "狀態頁面 id（sp_…）"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "公開網址：/status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "顯示的 uptime 檢查 id"
},
"subscribers": {
"type": "integer",
"description": "已確認的訂閱者"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/status_pages.json
列出狀態頁面
status_pages_list
權限： analytics.read
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/status_pages.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "依名稱或代稱篩選"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "狀態頁面 id（sp_…）"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "公開網址：/status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "顯示的 uptime 檢查 id"
},
"subscribers": {
"type": "integer",
"description": "已確認的訂閱者"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/status_pages/:id.json
取得狀態頁面
status_pages_get
權限： analytics.read
範例
curl https://privatusanalytics.com/status_pages/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "狀態頁面 id（sp_…）"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "公開網址：/status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "顯示的 uptime 檢查 id"
},
"subscribers": {
"type": "integer",
"description": "已確認的訂閱者"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/status_pages/:id.json
變更狀態頁面
status_pages_update
權限： uptime.manage
範例
curl -X PATCH https://privatusanalytics.com/status_pages/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "頁面標題，例如 \"Acme status\""
},
"slug": {
"type": "string",
"description": "公開網址代稱：/status/<slug>（預設取自名稱）"
},
"description": {
"type": "string",
"description": "標題下方的簡介文字"
},
"logo_url": {
"type": "string",
"description": "Logo 圖片的 HTTPS 網址"
},
"brand_color": {
"type": "string",
"description": "強調色，例如 #06755b"
},
"custom_domain": {
"type": "string",
"description": "自訂網域（CNAME 到我們的主機），例如 status.example.com。留空以移除"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要顯示的 uptime 檢查 id（upc_…）"
},
"published": {
"type": "boolean",
"description": "對公眾可見"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "狀態頁面 id（sp_…）"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "公開網址：/status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "顯示的 uptime 檢查 id"
},
"subscribers": {
"type": "integer",
"description": "已確認的訂閱者"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
目標
POST
/sites/:site_id/goals/:id/archive.json
封存目標（報告中隱藏）
goals_archive
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目標 id，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路徑、網域或檔案模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主機名稱限制（頁面目標）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自訂事件名稱（事件目標）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件屬性條件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：捲動 %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：頁面停留秒數"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小單位計的固定價值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "符合的事件，含重複"
},
"conversions": {
"type": "integer",
"description": "至少有一次完成的造訪"
},
"conversion_rate": {
"type": "number",
"description": "轉換 ÷ 造訪（或依網站設定 ÷ 訪客），%"
},
"value": {
"type": "integer",
"description": "以網站貨幣最小單位計的目標價值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "轉換數相較前一期間的變化，%"
},
{
"type": "null"
}
]
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/goals.json
建立目標
goals_create
權限： content.write
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/goals.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "目標名稱",
"examples": [
"Signed up"
]
},
"kind": {
"type": "string",
"description": "page（造訪頁面）、event（自訂事件）、engagement（捲動或頁面停留時間）、outbound（點擊外部連結）或 download（檔案下載）",
"enum": [
"page",
"event",
"engagement",
"outbound",
"download"
]
},
"match_type": {
"type": "string",
"description": "pattern 如何比對路徑（page、engagement）、連結網域（outbound）或檔案（download）：exact、prefix、glob (*) 或 regex",
"enum": [
"exact",
"prefix",
"glob",
"regex"
],
"default": "exact"
},
"pattern": {
"type": "string",
"description": "路徑、網域或檔案模式，例如 /pricing、/blog/*、stripe.com 或 *.pdf"
},
"hostname": {
"type": "string",
"description": "僅計算此主機名稱上的頁面（頁面目標）"
},
"event_name": {
"type": "string",
"description": "自訂事件名稱（事件目標）"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "事件屬性條件：[{\"key\": \"plan\", \"operator\": \"is|is_not|contains|gt|lt\", \"value\": \"pro\"}]",
"default": []
},
"scroll_threshold": {
"type": "integer",
"description": "Engagement：要達到的捲動深度百分比"
},
"time_threshold_seconds": {
"type": "integer",
"description": "Engagement：頁面停留秒數"
},
"value_mode": {
"type": "string",
"description": "none、fixed（每次轉換的 fixed_value）或 revenue（事件營收）",
"enum": [
"none",
"fixed",
"revenue"
],
"default": "none"
},
"fixed_value": {
"type": "number",
"description": "每次轉換的固定價值，以網站貨幣計，例如 50.0"
},
"count_mode": {
"type": "string",
"description": "價值計算為 once_per_visit 或每次完成",
"enum": [
"once_per_visit",
"every"
],
"default": "once_per_visit"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"kind",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目標 id，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路徑、網域或檔案模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主機名稱限制（頁面目標）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自訂事件名稱（事件目標）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件屬性條件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：捲動 %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：頁面停留秒數"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小單位計的固定價值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "符合的事件，含重複"
},
"conversions": {
"type": "integer",
"description": "至少有一次完成的造訪"
},
"conversion_rate": {
"type": "number",
"description": "轉換 ÷ 造訪（或依網站設定 ÷ 訪客），%"
},
"value": {
"type": "integer",
"description": "以網站貨幣最小單位計的目標價值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "轉換數相較前一期間的變化，%"
},
{
"type": "null"
}
]
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/goals/:id.json
刪除目標（資料會保留）
goals_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目標 id，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路徑、網域或檔案模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主機名稱限制（頁面目標）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自訂事件名稱（事件目標）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件屬性條件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：捲動 %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：頁面停留秒數"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小單位計的固定價值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "符合的事件，含重複"
},
"conversions": {
"type": "integer",
"description": "至少有一次完成的造訪"
},
"conversion_rate": {
"type": "number",
"description": "轉換 ÷ 造訪（或依網站設定 ÷ 訪客），%"
},
"value": {
"type": "integer",
"description": "以網站貨幣最小單位計的目標價值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "轉換數相較前一期間的變化，%"
},
{
"type": "null"
}
]
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/goals/:id/duplicate.json
複製目標
goals_duplicate
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "副本的名稱"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目標 id，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路徑、網域或檔案模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主機名稱限制（頁面目標）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自訂事件名稱（事件目標）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件屬性條件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：捲動 %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：頁面停留秒數"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小單位計的固定價值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "符合的事件，含重複"
},
"conversions": {
"type": "integer",
"description": "至少有一次完成的造訪"
},
"conversion_rate": {
"type": "number",
"description": "轉換 ÷ 造訪（或依網站設定 ÷ 訪客），%"
},
"value": {
"type": "integer",
"description": "以網站貨幣最小單位計的目標價值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "轉換數相較前一期間的變化，%"
},
{
"type": "null"
}
]
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/goals.json
列出目標，含某期間的完成次數、轉換、比率與價值
goals_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/goals.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"status": {
"type": "string",
"description": "active、archived 或 all 目標",
"enum": [
"active",
"archived",
"all"
],
"default": "active"
},
"page": {
"type": "integer",
"description": "頁碼",
"default": 1
},
"per_page": {
"type": "integer",
"description": "每頁目標數（最多 100）",
"default": 25
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目標 id，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路徑、網域或檔案模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主機名稱限制（頁面目標）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自訂事件名稱（事件目標）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件屬性條件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：捲動 %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：頁面停留秒數"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小單位計的固定價值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "符合的事件，含重複"
},
"conversions": {
"type": "integer",
"description": "至少有一次完成的造訪"
},
"conversion_rate": {
"type": "number",
"description": "轉換 ÷ 造訪（或依網站設定 ÷ 訪客），%"
},
"value": {
"type": "integer",
"description": "以網站貨幣最小單位計的目標價值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "轉換數相較前一期間的變化，%"
},
{
"type": "null"
}
]
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/goals/:id.json
目標報告：指標、圖表、細分與轉換前的路徑
goals_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/goals/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"interval": {
"type": "string",
"description": "圖表區間大小",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "期間的 from/to（UTC）"
},
"goal": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目標 id，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路徑、網域或檔案模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主機名稱限制（頁面目標）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自訂事件名稱（事件目標）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件屬性條件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：捲動 %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：頁面停留秒數"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小單位計的固定價值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "符合的事件，含重複"
},
"conversions": {
"type": "integer",
"description": "至少有一次完成的造訪"
},
"conversion_rate": {
"type": "number",
"description": "轉換 ÷ 造訪（或依網站設定 ÷ 訪客），%"
},
"value": {
"type": "integer",
"description": "以網站貨幣最小單位計的目標價值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "轉換數相較前一期間的變化，%"
},
{
"type": "null"
}
]
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"description": "目標定義"
},
"metrics": {
"type": "object",
"description": "completions、conversions、conversion_rate（%）、value（最小單位）"
},
"comparison_period": {
"anyOf": [
{
"type": "object",
"description": "比較的 from/to"
},
{
"type": "null"
}
]
},
"comparison": {
"anyOf": [
{
"type": "object",
"description": "比較期間的指標"
},
{
"type": "null"
}
]
},
"change": {
"anyOf": [
{
"type": "object",
"description": "相較比較期間的變化，每個指標的 %"
},
{
"type": "null"
}
]
},
"interval": {
"type": "string",
"description": "圖表區間大小"
},
"series": {
"type": "array",
"items": {
"type": "object"
},
"description": "每個區間：date、completions、conversions、conversion_rate"
},
"breakdowns": {
"type": "object",
"description": "依轉換數排序，channel、utm_campaign、entry_page、country 與 device 的熱門值：value、completions、conversions、conversion_rate"
},
"journey": {
"anyOf": [
{
"type": "object",
"description": "converting_visits、median_seconds_to_convert、median_pages_before 與 pages_before（轉換的造訪在該次造訪中先前瀏覽過的頁面）"
},
{
"type": "null"
}
]
}
}
}
POST
/sites/:site_id/goals/:id/unarchive.json
還原已封存的目標
goals_unarchive
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目標 id，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路徑、網域或檔案模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主機名稱限制（頁面目標）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自訂事件名稱（事件目標）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件屬性條件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：捲動 %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：頁面停留秒數"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小單位計的固定價值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "符合的事件，含重複"
},
"conversions": {
"type": "integer",
"description": "至少有一次完成的造訪"
},
"conversion_rate": {
"type": "number",
"description": "轉換 ÷ 造訪（或依網站設定 ÷ 訪客），%"
},
"value": {
"type": "integer",
"description": "以網站貨幣最小單位計的目標價值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "轉換數相較前一期間的變化，%"
},
{
"type": "null"
}
]
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/goals/:id.json
更新目標
goals_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "目標名稱",
"examples": [
"Signed up"
]
},
"kind": {
"type": "string",
"description": "page（造訪頁面）、event（自訂事件）、engagement（捲動或頁面停留時間）、outbound（點擊外部連結）或 download（檔案下載）",
"enum": [
"page",
"event",
"engagement",
"outbound",
"download"
]
},
"match_type": {
"type": "string",
"description": "pattern 如何比對路徑（page、engagement）、連結網域（outbound）或檔案（download）：exact、prefix、glob (*) 或 regex",
"enum": [
"exact",
"prefix",
"glob",
"regex"
]
},
"pattern": {
"type": "string",
"description": "路徑、網域或檔案模式，例如 /pricing、/blog/*、stripe.com 或 *.pdf"
},
"hostname": {
"type": "string",
"description": "僅計算此主機名稱上的頁面（頁面目標）"
},
"event_name": {
"type": "string",
"description": "自訂事件名稱（事件目標）"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "事件屬性條件：[{\"key\": \"plan\", \"operator\": \"is|is_not|contains|gt|lt\", \"value\": \"pro\"}]"
},
"scroll_threshold": {
"type": "integer",
"description": "Engagement：要達到的捲動深度百分比"
},
"time_threshold_seconds": {
"type": "integer",
"description": "Engagement：頁面停留秒數"
},
"value_mode": {
"type": "string",
"description": "none、fixed（每次轉換的 fixed_value）或 revenue（事件營收）",
"enum": [
"none",
"fixed",
"revenue"
]
},
"fixed_value": {
"type": "number",
"description": "每次轉換的固定價值，以網站貨幣計，例如 50.0"
},
"count_mode": {
"type": "string",
"description": "價值計算為 once_per_visit 或每次完成",
"enum": [
"once_per_visit",
"every"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目標 id，例如 goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page、event、engagement、outbound 或 download"
},
"match_type": {
"type": "string",
"description": "exact、prefix、glob 或 regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "路徑、網域或檔案模式"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "主機名稱限制（頁面目標）"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "自訂事件名稱（事件目標）"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件屬性條件"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：捲動 %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement：頁面停留秒數"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none、fixed 或 revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "以最小單位計的固定價值"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit 或 every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "符合的事件，含重複"
},
"conversions": {
"type": "integer",
"description": "至少有一次完成的造訪"
},
"conversion_rate": {
"type": "number",
"description": "轉換 ÷ 造訪（或依網站設定 ÷ 訪客），%"
},
"value": {
"type": "integer",
"description": "以網站貨幣最小單位計的目標價值"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "轉換數相較前一期間的變化，%"
},
{
"type": "null"
}
]
}
},
"description": "期間統計（僅列表）"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
稽核記錄
GET
/workspaces/:workspace_id/audit_log.json
列出稽核記錄項目（加上 .csv 即可匯出）
audit_logs_get
權限： workspace.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/audit_log.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"actor": {
"type": "string",
"description": "僅此成員（電子郵件）的變更"
},
"item_type": {
"type": "string",
"description": "僅此類型的記錄，例如 Site"
},
"event": {
"type": "string",
"description": "僅此動作",
"enum": [
"create",
"update",
"destroy"
]
},
"from": {
"type": "string",
"format": "date",
"description": "起始日期（含）"
},
"to": {
"type": "string",
"format": "date",
"description": "結束日期（含）"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "時間"
},
"event": {
"type": "string",
"description": "create、update 或 destroy"
},
"item_type": {
"type": "string",
"description": "記錄類型，例如 Site"
},
"item_id": {
"type": "string",
"format": "uuid"
},
"target": {
"type": "string",
"description": "該記錄（已知時以名稱表示）"
},
"actor_email": {
"anyOf": [
{
"type": "string",
"description": "進行變更的成員"
},
{
"type": "null"
}
]
},
"actor_name": {
"type": "string"
},
"token_name": {
"anyOf": [
{
"type": "string",
"description": "使用的 API token（若有）"
},
{
"type": "null"
}
]
},
"changes": {
"type": "object",
"description": "變更的欄位：{ field: [before, after] }"
},
"ip": {
"anyOf": [
{
"type": "string",
"description": "成員的 IP 位址"
},
{
"type": "null"
}
]
}
}
}
}
管道規則
POST
/sites/:site_id/channel_rules.json
新增管道規則
channel_rules_create
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "要指派的管道名稱，例如 Partners"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "必須全部符合的條件：[{\"field\": \"utm_source\", \"operator\": \"is\", \"value\": \"newsletter\"}]。欄位：referrer_host、utm_source、utm_medium、utm_campaign、ref、path。運算子：is、contains、starts_with、regex。"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"channel",
"conditions",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "規則 id"
},
"channel": {
"type": "string",
"description": "所有條件符合時指派的管道"
},
"position": {
"type": "integer",
"description": "評估順序（第一個符合者優先）"
},
"conditions": {
"type": "array",
"description": "條件：field、operator、value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/channel_rules/:id.json
刪除管道規則
channel_rules_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "規則 id"
},
"channel": {
"type": "string",
"description": "所有條件符合時指派的管道"
},
"position": {
"type": "integer",
"description": "評估順序（第一個符合者優先）"
},
"conditions": {
"type": "array",
"description": "條件：field、operator、value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/channel_rules.json
依順序列出管道規則
channel_rules_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/channel_rules.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "規則 id"
},
"channel": {
"type": "string",
"description": "所有條件符合時指派的管道"
},
"position": {
"type": "integer",
"description": "評估順序（第一個符合者優先）"
},
"conditions": {
"type": "array",
"description": "條件：field、operator、value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/channel_rules/:id/move.json
上移或下移管道規則
channel_rules_move
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"direction": {
"type": "string",
"description": "規則要移動的方向",
"enum": [
"up",
"down",
"top",
"bottom"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"direction",
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "規則 id"
},
"channel": {
"type": "string",
"description": "所有條件符合時指派的管道"
},
"position": {
"type": "integer",
"description": "評估順序（第一個符合者優先）"
},
"conditions": {
"type": "array",
"description": "條件：field、operator、value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/channel_rules/preview.json
預覽範例來源網址與 UTM 標記所屬的管道
channel_rules_preview
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"referrer": {
"type": "string",
"description": "來源網址或主機名稱"
},
"utm_source": {
"type": "string",
"description": "utm_source 值"
},
"utm_medium": {
"type": "string",
"description": "utm_medium 值"
},
"utm_campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"ref": {
"type": "string",
"description": "ref / via / source 參數"
},
"path": {
"type": "string",
"description": "登陸頁路徑，例如 /pricing"
},
"paid_click": {
"type": "boolean",
"description": "網址帶有點擊 id，例如 gclid",
"default": false
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
PATCH
/sites/:site_id/channel_rules/:id.json
變更管道規則
channel_rules_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "要指派的管道名稱"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "必須全部符合的條件：[{\"field\": \"utm_source\", \"operator\": \"is\", \"value\": \"newsletter\"}]。欄位：referrer_host、utm_source、utm_medium、utm_campaign、ref、path。運算子：is、contains、starts_with、regex。"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "規則 id"
},
"channel": {
"type": "string",
"description": "所有條件符合時指派的管道"
},
"position": {
"type": "integer",
"description": "評估順序（第一個符合者優先）"
},
"conditions": {
"type": "array",
"description": "條件：field、operator、value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
網站
POST
/sites/:site_id/data_reset.json
刪除某日期範圍內的所有事件與造訪（在背景執行，無法復原）
sites_reset_data
權限： sites.manage
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/data_reset.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date",
"description": "要刪除的第一天（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "要刪除的最後一天（含）"
},
"confirm": {
"type": "string",
"description": "輸入網域以確認"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"from",
"to",
"confirm",
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/filter_stats.json
已過濾流量摘要：依原因與國家統計的機器人、流量規則或個資遮蔽（僅計數）
sites_filter_stats
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/filter_stats.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "bot（已過濾的機器人）、rule（流量規則）或 redaction（PII 清除器）",
"enum": [
"bot",
"rule",
"redaction"
],
"default": "bot"
},
"days": {
"type": "integer",
"description": "回溯的天數（1-395）",
"default": 30
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/access.json
列出成員及其是否能看到此網站
sites_access_list
權限： members.manage
範例
curl https://privatusanalytics.com/sites/:site_id/access.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"format": "uuid",
"description": "成員資格 id"
},
"email": {
"type": "string"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"access": {
"type": "boolean",
"description": "可以看到此網站"
},
"locked": {
"type": "boolean",
"description": "擁有者與管理員一律有存取權"
}
}
}
PATCH
/sites/:site_id/access.json
授予或移除單一成員對此網站的存取權
sites_access_update
權限： members.manage
範例
curl -X PATCH https://privatusanalytics.com/sites/:site_id/access.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"description": "來自 sites_access_list 的成員資格 id"
},
"access": {
"type": "boolean",
"description": "true 為授予存取權，false 為移除"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"membership_id",
"access",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"format": "uuid",
"description": "成員資格 id"
},
"email": {
"type": "string"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"access": {
"type": "boolean",
"description": "可以看到此網站"
},
"locked": {
"type": "boolean",
"description": "擁有者與管理員一律有存取權"
}
}
}
POST
/sites/:site_id/favorite.json
將網站加星號（在所有網站中置頂）
sites_favorite
權限： analytics.read
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/favorite.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "追蹤程式碼片段中使用的網站 id"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "伺服器擷取金鑰的開頭"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 追蹤程式碼片段"
},
"favorite": {
"type": "boolean",
"description": "已由您加星號"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/favorite.json
取消網站的星號
sites_unfavorite
權限： analytics.read
範例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/favorite.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "追蹤程式碼片段中使用的網站 id"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "伺服器擷取金鑰的開頭"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 追蹤程式碼片段"
},
"favorite": {
"type": "boolean",
"description": "已由您加星號"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/setup.json
網站的安裝狀態與程式碼片段
sites_setup_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/setup.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
POST
/transfers/:token/accept.json
接受網站轉移到您的其中一個工作區
site_transfers_accept
權限： public
範例
curl -X POST https://privatusanalytics.com/transfers/:token/accept.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "要將網站移入的工作區（ws_…）"
},
"token": {
"type": "string",
"description": "資源的 Token"
}
},
"required": [
"workspace_id",
"token"
]
}
回應資料
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "正在轉移的網站"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "目前的工作區名稱"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "接收的工作區"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "收件人電子郵件"
},
"status": {
"type": "string",
"description": "pending、accepted 或 canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/transfer.json
開始將網站轉移到另一個工作區（會寄電子郵件給收件人）
sites_transfer_start
權限： sites.manage
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/transfer.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "將接收網站者的電子郵件（對方會選擇自己的其中一個工作區）"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"email",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "正在轉移的網站"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "目前的工作區名稱"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "接收的工作區"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "收件人電子郵件"
},
"status": {
"type": "string",
"description": "pending、accepted 或 canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/transfer.json
取消待處理的網站轉移
sites_transfer_cancel
權限： sites.manage
範例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/transfer.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "正在轉移的網站"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "目前的工作區名稱"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "接收的工作區"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "收件人電子郵件"
},
"status": {
"type": "string",
"description": "pending、accepted 或 canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/transfers/:token.json
以電子郵件中的 token 取得待處理的轉移
site_transfers_get
權限： public
範例
curl https://privatusanalytics.com/transfers/:token.json輸入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "資源的 Token"
}
},
"required": [
"token"
]
}
回應資料
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "正在轉移的網站"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "目前的工作區名稱"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "接收的工作區"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "收件人電子郵件"
},
"status": {
"type": "string",
"description": "pending、accepted 或 canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/sites.json
新增網站
sites_create
權限： sites.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sites.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "主要網域，例如 example.com",
"examples": [
"example.com"
]
},
"name": {
"type": "string",
"description": "顯示名稱（預設為網域）"
},
"timezone": {
"type": "string",
"description": "報表時區"
},
"currency": {
"type": "string",
"description": "營收貨幣（ISO 4217）"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"domain",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "追蹤程式碼片段中使用的網站 id"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "伺服器擷取金鑰的開頭"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 追蹤程式碼片段"
},
"favorite": {
"type": "boolean",
"description": "已由您加星號"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:id.json
刪除網站（7 天後清除）
sites_delete
權限： sites.manage
範例
curl -X DELETE https://privatusanalytics.com/sites/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"confirm": {
"type": "string",
"description": "輸入網域以確認"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"confirm",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "追蹤程式碼片段中使用的網站 id"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "伺服器擷取金鑰的開頭"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 追蹤程式碼片段"
},
"favorite": {
"type": "boolean",
"description": "已由您加星號"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/sites.json
列出工作區中的網站
sites_list
權限： analytics.read
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/sites.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "依網域或名稱篩選"
},
"label": {
"type": "string",
"description": "僅有此標籤的網站"
},
"sort": {
"type": "string",
"description": "position（您的順序）、name，或過去 30 天的 visitors（最多的在前）",
"enum": [
"position",
"name",
"visitors"
],
"default": "position"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "追蹤程式碼片段中使用的網站 id"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "伺服器擷取金鑰的開頭"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 追蹤程式碼片段"
},
"favorite": {
"type": "boolean",
"description": "已由您加星號"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:id.json
取得網站及其所有設定
sites_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "追蹤程式碼片段中使用的網站 id"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "伺服器擷取金鑰的開頭"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 追蹤程式碼片段"
},
"favorite": {
"type": "boolean",
"description": "已由您加星號"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:id.json
更新網站設定
sites_update
權限： sites.manage
範例
curl -X PATCH https://privatusanalytics.com/sites/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "顯示名稱"
},
"domain": {
"type": "string",
"description": "主要網域"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "額外的主機名稱"
},
"multi_domain_mode": {
"type": "string",
"description": "combined：跨網域視為同一訪客",
"enum": [
"combined",
"separate"
]
},
"timezone": {
"type": "string",
"description": "報表時區"
},
"currency": {
"type": "string",
"description": "營收貨幣（ISO 4217）"
},
"week_start": {
"type": "integer",
"description": "0 = 星期日，1 = 星期一"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "用來為網站分組的標籤"
},
"honor_dnt": {
"type": "boolean",
"description": "略過傳送 DNT 的訪客"
},
"honor_gpc": {
"type": "boolean",
"description": "略過傳送 GPC 的訪客"
},
"pii_scrubber": {
"type": "boolean",
"description": "清除電子郵件、token、id"
},
"redaction_rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"pattern": {
"type": "string"
}
}
},
"description": "自訂清除用的正規表示式"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
},
"description": "要保留在路徑上的查詢參數"
},
"path_masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"replacement": {
"type": "string"
}
}
},
"description": "路徑遮罩規則，例如 /u/* -> /u/:id"
},
"retention_months": {
"type": "integer",
"description": "刪除比此更舊的資料"
},
"bot_filtering": {
"type": "boolean",
"description": "過濾機器人流量"
},
"traffic_rule_modes": {
"type": "object",
"additionalProperties": true,
"description": "每個流量規則清單為 block 或 allow"
},
"vitals_sample_rate": {
"type": "integer",
"description": "Web Vitals 取樣百分比"
},
"conversion_denominator": {
"type": "string",
"description": "轉換率以造訪或訪客為基準",
"enum": [
"visits",
"visitors"
]
},
"public_dashboard": {
"type": "boolean",
"description": "任何有連結的人都能查看統計"
},
"public_indexable": {
"type": "boolean",
"description": "讓搜尋引擎索引公開頁面"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "追蹤程式碼片段中使用的網站 id"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "伺服器擷取金鑰的開頭"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 追蹤程式碼片段"
},
"favorite": {
"type": "boolean",
"description": "已由您加星號"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
網站頁面
GET
/changelog.json
列出更新日誌項目
changelog_list
已發布的產品更新，最新的在前。也提供 RSS，位於 /changelog.rss。
權限： public
範例
curl https://privatusanalytics.com/changelog.json輸入
{
"type": "object",
"properties": {
"area": {
"type": "string",
"description": "僅此產品領域的項目",
"enum": [
"product",
"dashboard",
"tracker",
"privacy",
"api",
"integrations",
"billing",
"docs"
]
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": []
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "項目 id，例如 chg_7Q2K9XH3AB"
},
"title": {
"type": "string",
"description": "標題"
},
"area": {
"type": "string",
"description": "產品領域，例如 dashboard、tracker、api"
},
"body": {
"type": "string",
"description": "Markdown 內文"
},
"published_at": {
"type": "string",
"format": "date-time",
"description": "發布時間"
},
"url": {
"type": "string",
"description": "永久連結"
}
}
}
}
GET
/changelog/:id.json
取得更新日誌項目
changelog_get
權限： public
範例
curl https://privatusanalytics.com/changelog/:id.json輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "項目 id，例如 chg_7Q2K9XH3AB"
},
"title": {
"type": "string",
"description": "標題"
},
"area": {
"type": "string",
"description": "產品領域，例如 dashboard、tracker、api"
},
"body": {
"type": "string",
"description": "Markdown 內文"
},
"published_at": {
"type": "string",
"format": "date-time",
"description": "發布時間"
},
"url": {
"type": "string",
"description": "永久連結"
}
}
}
POST
/contact.json
傳送訊息給 Privatus Analytics 團隊
contact_create
瀏覽器用戶端會以 `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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "您的名稱",
"examples": [
"Ada Lovelace"
]
},
"email": {
"type": "string",
"description": "我們該回覆的地址",
"examples": [
"[email protected]"
]
},
"company": {
"type": "string",
"description": "公司或組織（選填）"
},
"topic": {
"type": "string",
"description": "訊息的主題",
"enum": [
"general",
"sales",
"support",
"privacy",
"security",
"partnerships",
"press"
],
"default": "general"
},
"message": {
"type": "string",
"description": "您的訊息（10 至 5,000 個字元）"
},
"website": {
"type": "string",
"description": "請留空。這是防範機器人的陷阱。填寫的提交內容會被捨棄"
}
},
"required": [
"name",
"email",
"message"
]
}
回應資料
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受時一律為 true"
},
"message": {
"type": "string",
"description": "接下來會發生什麼"
}
}
}
POST
/newsletter/confirm.json
確認電子報訂閱（簽署 token）
newsletter_confirm
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/newsletter/confirm.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "確認電子郵件中的簽署 token"
}
},
"required": [
"token"
]
}
回應資料
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受時一律為 true"
},
"message": {
"type": "string",
"description": "接下來會發生什麼"
}
}
}
POST
/newsletter.json
將電子郵件訂閱電子報
newsletter_subscribe
瀏覽器用戶端會以 `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 '{…}'輸入
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "要訂閱的電子郵件地址。確認連結會寄到此地址",
"examples": [
"[email protected]"
]
},
"website": {
"type": "string",
"description": "請留空。這是防範機器人的陷阱。填寫的提交內容會被捨棄"
}
},
"required": [
"email"
]
}
回應資料
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受時一律為 true"
},
"message": {
"type": "string",
"description": "接下來會發生什麼"
}
}
}
POST
/newsletter/unsubscribe.json
使用簽署連結 token 取消訂閱
newsletter_unsubscribe
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/newsletter/unsubscribe.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "取消訂閱連結中的簽署 token"
},
"list": {
"type": "string",
"description": "newsletter（預設：連結所屬的清單）或 marketing（所有行銷電子郵件）",
"enum": [
"newsletter",
"marketing"
]
}
},
"required": [
"token"
]
}
回應資料
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受時一律為 true"
},
"message": {
"type": "string",
"description": "接下來會發生什麼"
}
}
}
GET
/pricing.json
取得方案、價格與方案限制
pricing_get
與價格頁面相同的資料：事件級距、每項方案限制，以及哪些算作事件。傳入 events 即可取得對應的級距。
權限： public
範例
curl https://privatusanalytics.com/pricing.json輸入
{
"type": "object",
"properties": {
"events": {
"type": "integer",
"description": "預期每月的瀏覽量加自訂事件。以 `recommendation` 回傳對應的級距",
"examples": [
750000
]
},
"interval": {
"type": "string",
"description": "顯示價格所用的計費週期：month，或 year（月費的 10 倍）",
"enum": [
"month",
"year"
],
"default": "month"
}
},
"required": []
}
回應資料
{
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "所有價格的貨幣（USD）"
},
"tax_included": {
"type": "boolean",
"description": "永遠為 true。價格已含加值稅或銷售稅，顯示的價格就是實付的價格"
},
"interval": {
"type": "string",
"description": "month 或 year。價格對應此週期"
},
"annual_multiplier": {
"type": "integer",
"description": "年費 = 月費 x 此值（免費兩個月）"
},
"free_events": {
"type": "integer",
"description": "免費方案包含的每月事件數"
},
"badge_bonus": {
"type": "integer",
"description": "顯示選用徽章時額外的每月免費事件數"
},
"tiers": {
"type": "array",
"items": {
"type": "object"
},
"description": "事件階梯：該週期的 { events, pro, business } 價格（僅提供 Business 之處 pro 為 null），以及月費價格"
},
"plans": {
"type": "array",
"items": {
"type": "object"
},
"description": "方案，含 { id, name, from_price, limits }。limits 為 null 表示無限制"
},
"counted": {
"type": "array",
"items": {
"type": "string"
},
"description": "什麼算作計費事件"
},
"not_counted": {
"type": "array",
"items": {
"type": "string"
},
"description": "什麼絕不計入用量"
},
"recommendation": {
"anyOf": [
{
"type": "object",
"description": "針對 `events` 輸入的 { events, plan, tier_events, price }，若未提供用量則為 null"
},
{
"type": "null"
}
]
}
}
}
GET
/status.json
取得目前系統狀態
status_get
資料庫、Redis 與背景工作的健康狀態，最多每 15 秒檢查一次。
權限： public
範例
curl https://privatusanalytics.com/status.json輸入
{
"type": "object",
"properties": {
"fresh": {
"type": "boolean",
"description": "略過 15 秒快取並立即重新檢查",
"default": false
}
},
"required": []
}
回應資料
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "整體：operational、degraded 或 outage"
},
"checked_at": {
"type": "string",
"format": "date-time",
"description": "檢查執行的時間（最多快取 15 秒）"
},
"components": {
"type": "array",
"items": {
"type": "object"
},
"description": "每個元件：{ id, name, status, detail, latency_ms }，佇列另有 queue_latency_s 與 queue_depth"
}
}
}
GET
/tools/consent-gap.json
估算以同意為基礎的分析所遺漏的流量
tools_consent_gap
權限： public
範例
curl https://privatusanalytics.com/tools/consent-gap.json輸入
{
"type": "object",
"properties": {
"monthly_visitors": {
"type": "integer",
"description": "每月訪客數（來自您的伺服器記錄或目前的分析）",
"examples": [
50000
]
},
"consent_rate": {
"type": "number",
"description": "在您的橫幅上接受分析 cookie 的訪客百分比（0-100）",
"examples": [
55
]
},
"adblock_share": {
"type": "number",
"description": "其廣告攔截器會阻擋分析腳本的訪客百分比（0-100）",
"default": 25.0
}
},
"required": [
"monthly_visitors",
"consent_rate"
]
}
回應資料
{
"type": "object",
"properties": {
"monthly_visitors": {
"type": "integer",
"description": "輸入：每月訪客數"
},
"consent_rate": {
"type": "number",
"description": "輸入：接受分析 cookie 的百分比"
},
"adblock_share": {
"type": "number",
"description": "輸入：其攔截器會阻擋腳本的百分比"
},
"measured_with_consent": {
"type": "integer",
"description": "以同意為基礎的工具能測量到的訪客"
},
"missed": {
"type": "integer",
"description": "它遺漏的訪客"
},
"missed_percent": {
"type": "number",
"description": "遺漏的訪客比例，以百分比表示"
},
"measured_cookieless": {
"type": "integer",
"description": "不需要橫幅的無 cookie 工具在被相同比例攔截的情況下，可以衡量到的訪客數"
},
"recovered_by_cookieless": {
"type": "integer",
"description": "無 cookie 與以同意為基礎的估計之間的差異"
}
}
}
GET
/tools/header-checker.json
檢查頁面的 Referrer-Policy 與 CSP 是否適用於分析
tools_header_check
權限： public
範例
curl https://privatusanalytics.com/tools/header-checker.json輸入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "要檢查的公開頁面（http 或 https）",
"examples": [
"https://example.com"
]
}
},
"required": [
"url"
]
}
回應資料
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "重新導向後的最終網址"
},
"status": {
"type": "integer",
"description": "最終回應的 HTTP 狀態"
},
"findings": {
"type": "array",
"items": {
"type": "object"
},
"description": "檢查：{ check, value, level (ok, warn, info), note }"
}
}
}
GET
/tools/privacy-policy-generator.json
為 Privatus Analytics 草擬隱私權政策段落
tools_privacy_policy
權限： public
範例
curl https://privatusanalytics.com/tools/privacy-policy-generator.json輸入
{
"type": "object",
"properties": {
"site_name": {
"type": "string",
"description": "您的網站或公司名稱",
"examples": [
"Example Books"
]
},
"contact_email": {
"type": "string",
"description": "要提及的隱私聯絡人（選填）"
},
"honors_gpc": {
"type": "boolean",
"description": "是否遵守 Do Not Track 與 Global Privacy Control（預設）",
"default": true
}
},
"required": [
"site_name"
]
}
回應資料
{
"type": "object",
"properties": {
"site_name": {
"type": "string",
"description": "輸入：網站或公司名稱"
},
"paragraphs": {
"type": "array",
"items": {
"type": "string"
},
"description": "政策文字，每個項目一個段落"
},
"text": {
"type": "string",
"description": "以空行連接的段落"
}
}
}
GET
/tools/qr-code.json
產生 SVG 格式的 QR code
tools_qr_code
權限： public
範例
curl https://privatusanalytics.com/tools/qr-code.json輸入
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "要編碼的網址或文字（最多 1,000 個字元）",
"examples": [
"https://example.com/?utm_source=poster"
]
},
"level": {
"type": "string",
"description": "錯誤更正：l (7%)、m (15%)、q (25%)、h (30%)",
"enum": [
"l",
"m",
"q",
"h"
],
"default": "m"
}
},
"required": [
"text"
]
}
回應資料
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "已編碼的文字"
},
"level": {
"type": "string",
"description": "錯誤更正等級"
},
"size": {
"type": "integer",
"description": "每邊的模組數"
},
"svg": {
"type": "string",
"description": "獨立 SVG 文件"
}
}
}
GET
/tools/tracker-scanner.json
列出頁面上的 cookie 與已知追蹤器
tools_tracker_scan
權限： public
範例
curl https://privatusanalytics.com/tools/tracker-scanner.json輸入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "要掃描的公開頁面（http 或 https）",
"examples": [
"https://example.com"
]
}
},
"required": [
"url"
]
}
回應資料
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "重新導向後的最終網址"
},
"status": {
"type": "integer",
"description": "最終回應的 HTTP 狀態"
},
"truncated": {
"type": "boolean",
"description": "頁面超過 1 MB 且只掃描了前 1 MB 時為 true"
},
"cookies": {
"type": "array",
"items": {
"type": "object"
},
"description": "HTTP 回應設定的 cookie：{ name, domain, path, expires, secure, http_only, same_site }。絕不回傳值"
},
"trackers": {
"type": "array",
"items": {
"type": "object"
},
"description": "頁面引用的已知工具：{ name, category, match, evidence }"
},
"third_party_hosts": {
"type": "array",
"items": {
"type": "string"
},
"description": "頁面從中載入資源的其他網域"
}
}
}
GET
/tools/utm-builder.json
建立帶有 UTM 參數的行銷活動網址
tools_utm_builder
權限： public
範例
curl https://privatusanalytics.com/tools/utm-builder.json輸入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "登陸頁網址",
"examples": [
"https://example.com/pricing"
]
},
"source": {
"type": "string",
"description": "utm_source：流量的來源",
"examples": [
"newsletter"
]
},
"medium": {
"type": "string",
"description": "utm_medium：管道，例如 email、cpc、social",
"examples": [
"email"
]
},
"campaign": {
"type": "string",
"description": "utm_campaign：行銷活動名稱",
"examples": [
"fall_launch"
]
},
"term": {
"type": "string",
"description": "utm_term：付費搜尋關鍵字（選填）"
},
"content": {
"type": "string",
"description": "utm_content：哪個連結或素材（選填）"
}
},
"required": [
"url",
"source",
"medium",
"campaign"
]
}
回應資料
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "帶有 UTM 參數的登陸頁網址"
},
"params": {
"type": "object",
"description": "已加入的 UTM 參數"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "值得修正的問題（大小寫、空格、個人資料）"
}
}
}
POST
/waitlist.json
加入候補名單（歐洲代管）
waitlist_join
瀏覽器用戶端會以 `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 '{…}'輸入
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "要通知的電子郵件",
"examples": [
"[email protected]"
]
},
"list": {
"type": "string",
"description": "要加入哪個候補名單",
"enum": [
"eu_hosting"
],
"default": "eu_hosting"
},
"website": {
"type": "string",
"description": "請留空。這是防範機器人的陷阱。填寫的提交內容會被捨棄"
}
},
"required": [
"email"
]
}
回應資料
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受時一律為 true"
},
"message": {
"type": "string",
"description": "接下來會發生什麼"
}
}
}
聯盟行銷計畫
GET
/account/affiliate/commissions.json
列出您的聯盟行銷佣金
affiliate_commissions_list
佣金、退款與拒付的追回及其撤銷，由新到舊排列。金額以分為單位。
權限： member
範例
curl https://privatusanalytics.com/account/affiliate/commissions.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "只列出此狀態的佣金",
"enum": [
"pending",
"approved",
"paid",
"void"
]
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": []
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "佣金 id"
},
"kind": {
"type": "string",
"description": "commission、clawback（退款或拒付）或 reversal"
},
"status": {
"type": "string",
"description": "pending（保留中）、approved（可支付）、paid 或 void"
},
"amount_cents": {
"type": "integer",
"description": "您的分成，以分為單位（追回時為負數）"
},
"basis_cents": {
"type": "integer",
"description": "計算所依據的淨付款金額（不含稅），以分為單位"
},
"currency": {
"type": "string",
"description": "ISO 幣別代碼"
},
"earned_at": {
"type": "string",
"format": "date-time",
"description": "付款（或退款）發生的時間"
},
"approved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "變為可支付的時間"
},
{
"type": "null"
}
]
},
"paid_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "支付的時間"
},
{
"type": "null"
}
]
}
}
}
}
GET
/account/affiliate/signup-box.json
取得您的聯盟行銷註冊方塊程式碼與成效
affiliate_signup_box_get
所選佈景主題的註冊方塊嵌入程式碼（一段指令碼與純 iframe）、預先填入表單的屬性、指令碼在您頁面上觸發的事件，以及方塊的數字：等待確認的註冊、已確認的註冊與付費客戶。在您的聯盟行銷申請通過之前，available 為 false。
權限： member
範例
curl https://privatusanalytics.com/account/affiliate/signup-box.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"theme": {
"type": "string",
"description": "方塊的佈景主題：auto（配合訪客裝置）、light 或 dark",
"enum": [
"auto",
"light",
"dark"
],
"examples": [
"auto"
],
"default": "auto"
}
},
"required": []
}
回應資料
{
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "您是否有註冊方塊（僅限已通過的聯盟行銷夥伴）"
},
"theme": {
"type": "string",
"description": "程式碼所針對的佈景主題"
},
"frame_url": {
"anyOf": [
{
"type": "string",
"description": "方塊的位址，供純 iframe 使用"
},
{
"type": "null"
}
]
},
"script": {
"anyOf": [
{
"type": "string",
"description": "指令碼嵌入程式碼：一個元素與載入指令碼"
},
{
"type": "null"
}
]
},
"iframe": {
"anyOf": [
{
"type": "string",
"description": "純 iframe 嵌入程式碼"
},
{
"type": "null"
}
]
},
"prefill_attributes": {
"type": "array",
"description": "元素上的屬性，可為已登入的訪客預先填入表單"
},
"events": {
"type": "array",
"description": "指令碼在元素上觸發的 DOM 事件"
},
"waiting": {
"type": "integer",
"description": "寄出的連結尚未被開啟的註冊"
},
"signups": {
"type": "integer",
"description": "透過方塊完成的已確認註冊"
},
"customers": {
"type": "integer",
"description": "其中成為付費客戶的數量"
}
}
}
GET
/account/affiliate.json
取得您的聯盟行銷狀態、推薦連結與統計數據
affiliate_get
您的聯盟行銷申請狀態、推薦連結、您推薦的註冊數與付費客戶數，以及各幣別的餘額（保留中、可支付、已支付）。尚未申請時 status 為 none。
權限： member
範例
curl https://privatusanalytics.com/account/affiliate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {},
"required": []
}
回應資料
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "none（尚未申請）、pending、approved、rejected 或 suspended"
},
"code": {
"anyOf": [
{
"type": "string",
"description": "您的推薦碼"
},
{
"type": "null"
}
]
},
"referral_url": {
"anyOf": [
{
"type": "string",
"description": "要分享的連結（僅限已核准的聯盟夥伴）"
},
{
"type": "null"
}
]
},
"payout_method": {
"anyOf": [
{
"type": "string",
"description": "wise 或 credit"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "上次申請被拒絕的原因"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "您申請的時間"
},
{
"type": "null"
}
]
},
"approved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "申請獲得核准的時間"
},
{
"type": "null"
}
]
},
"credit_blocked": {
"anyOf": [
{
"type": "string",
"description": "帳戶抵用金等待中的原因：program（工作區正在折扣方案中）、no_subscription 或 no_workspace。沒有任何阻礙時為 null"
},
{
"type": "null"
}
]
},
"signups": {
"type": "integer",
"description": "透過您的連結或推薦碼建立的帳號"
},
"customers": {
"type": "integer",
"description": "已付款的被推薦工作區"
},
"balances": {
"type": "array",
"description": "各幣別：pending_cents（保留中）、approved_cents（可支付）與 paid_cents"
},
"payouts": {
"type": "array",
"description": "最近的付款，包含 amount_cents、currency、payout_method、status（applied：帳戶抵用金等待下次續訂，或 paid）、applied_at 與 paid_at"
},
"terms": {
"type": "object",
"description": "佣金百分比、月數、保留天數，以及以分為單位的 Wise 付款門檻"
}
}
}
行銷活動
POST
/sites/:site_id/campaigns/costs.json
設定行銷活動在某月的花費
campaign_costs_create
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"campaign": {
"type": "string",
"description": "此花費所屬的 utm_campaign 值",
"examples": [
"spring_sale"
]
},
"month": {
"type": "string",
"description": "月份，YYYY-MM",
"examples": [
"2026-09"
]
},
"amount": {
"type": "number",
"description": "以主要單位計的花費，例如 1250.50"
},
"currency": {
"type": "string",
"description": "ISO 4217 貨幣（預設為網站貨幣）"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"campaign",
"month",
"amount",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成本項目 id"
},
"campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"month": {
"type": "string",
"description": "月份，YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "以最小單位計的花費"
},
"currency": {
"type": "string",
"description": "金額的 ISO 4217 貨幣"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/campaigns/costs/:id.json
刪除行銷活動成本項目
campaign_costs_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成本項目 id"
},
"campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"month": {
"type": "string",
"description": "月份，YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "以最小單位計的花費"
},
"currency": {
"type": "string",
"description": "金額的 ISO 4217 貨幣"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/campaigns/costs/import.json
從 CSV 匯入行銷活動成本（campaign,month,amount[,currency]）
campaign_costs_import
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "CSV 檔案上傳（multipart 表單）"
},
"csv": {
"type": "string",
"description": "CSV 文字：campaign,month,amount[,currency]"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"imported": {
"type": "integer",
"description": "已儲存的列數"
},
"failed": {
"type": "integer",
"description": "略過的列數"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "列被略過的原因（前 50 筆）"
}
}
}
GET
/sites/:site_id/campaigns/costs.json
列出行銷活動成本項目
campaign_costs_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/campaigns/costs.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"campaign": {
"type": "string",
"description": "僅此行銷活動"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成本項目 id"
},
"campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"month": {
"type": "string",
"description": "月份，YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "以最小單位計的花費"
},
"currency": {
"type": "string",
"description": "金額的 ISO 4217 貨幣"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/sites/:site_id/campaigns/costs/:id.json
變更行銷活動成本項目
campaign_costs_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"month": {
"type": "string",
"description": "月份，YYYY-MM"
},
"amount": {
"type": "number",
"description": "以主要單位計的花費"
},
"currency": {
"type": "string",
"description": "ISO 4217 貨幣"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "成本項目 id"
},
"campaign": {
"type": "string",
"description": "utm_campaign 值"
},
"month": {
"type": "string",
"description": "月份，YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "以最小單位計的花費"
},
"currency": {
"type": "string",
"description": "金額的 ISO 4217 貨幣"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/campaigns/builder.json
建立並驗證帶有 UTM 標記的網址
campaigns_builder
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/campaigns/builder.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"destination": {
"type": "string",
"description": "登陸頁網址（https://…）",
"examples": [
"https://example.com/pricing"
]
},
"preset": {
"type": "string",
"description": "留白時，為管道填入 utm_source/utm_medium",
"enum": [
"newsletter",
"social",
"paid_search",
"paid_social",
"print",
"partner"
]
},
"utm_source": {
"type": "string",
"description": "流量的來源"
},
"utm_medium": {
"type": "string",
"description": "行銷媒介，例如 email、cpc"
},
"utm_campaign": {
"type": "string",
"description": "行銷活動名稱，例如 spring_sale"
},
"utm_content": {
"type": "string",
"description": "版本，例如 header_button"
},
"utm_term": {
"type": "string",
"description": "付費搜尋關鍵字"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"url": {
"anyOf": [
{
"type": "string",
"description": "帶標記的網址（有錯誤時為 null）"
},
{
"type": "null"
}
]
},
"valid": {
"type": "boolean",
"description": "沒有錯誤時為 true"
},
"destination": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preset": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_source": {
"anyOf": [
{
"type": "string",
"description": "已正規化的 utm_source"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string",
"description": "已正規化的 utm_medium"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string",
"description": "已正規化的 utm_campaign"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string",
"description": "已正規化的 utm_content"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string",
"description": "已正規化的 utm_term"
},
{
"type": "null"
}
]
},
"issues": {
"type": "array",
"items": {
"type": "object"
},
"description": "field、level（error 或 warning）與 message"
},
"presets": {
"type": "object",
"description": "管道預設：每個預設的 utm_source/utm_medium"
}
}
}
GET
/sites/:site_id/campaigns/hygiene.json
UTM 規範檢查：近似重複的值、樣式問題與不明來源
campaigns_hygiene
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/campaigns/hygiene.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "期間的 from/to（UTC）"
},
"duplicates": {
"type": "array",
"items": {
"type": "object"
},
"description": "近似重複的值：欄位、建議與變體 [{value, visits}]"
},
"style_issues": {
"type": "array",
"items": {
"type": "object"
},
"description": "不是小寫加底線的值：欄位、值、造訪數、建議"
},
"unknown_sources": {
"type": "array",
"items": {
"type": "object"
},
"description": "我們無法辨識的 utm_source 值：值、造訪數"
}
}
}
GET
/sites/:site_id/campaigns.json
行銷活動彙總，含轉換、營收、成本、CPA 與 ROAS
campaigns_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/campaigns.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "預設日期範圍。搭配 from/to 使用 custom",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "自訂範圍起點（網站時區）"
},
"to": {
"type": "string",
"format": "date",
"description": "自訂範圍終點（含）"
},
"compare": {
"type": "string",
"description": "比較期間",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "自訂比較起點"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "自訂比較終點"
},
"match_weekday": {
"type": "boolean",
"description": "對齊比較的星期幾",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "篩選條件：[[\"dimension\",\"operator\",\"value\"], …]。運算子：is、is_not、any_of、none_of、contains、not_contains、starts_with、regex、not_regex、gt、lt、between。以 {\"any\": [...]} 包住條件即為 OR。",
"default": []
},
"segment_id": {
"type": "string",
"description": "套用已儲存的區段（seg_…）"
},
"include_imported": {
"type": "boolean",
"description": "加入已匯入的歷史資料（第一個原生事件之前的日期，套用篩選條件或區段時會被忽略）",
"default": false
},
"goal_id": {
"type": "string",
"description": "要計算其轉換的目標（goal_…）。預設為第一個啟用中的目標"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "期間的 from/to（UTC）"
},
"currency": {
"type": "string",
"description": "營收與成本使用的網站貨幣"
},
"goal_id": {
"anyOf": [
{
"type": "string",
"description": "計為轉換的目標"
},
{
"type": "null"
}
]
},
"goal_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"campaigns": {
"type": "array",
"items": {
"type": "object"
},
"description": "每個 utm_campaign：visitors、visits、conversions、conversion_rate、revenue、cost、cpa（最小單位）、roas（營收 ÷ 成本）與來源 [{source, medium, visitors, visits, conversions, conversion_rate, revenue}]"
},
"totals": {
"type": "object",
"description": "所有列出之行銷活動的總和"
}
}
}
POST
/sites/:site_id/campaigns/links.json
將帶有 UTM 標記的連結儲存到連結庫
links_create
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "連結名稱",
"examples": [
"Spring newsletter"
]
},
"destination": {
"type": "string",
"description": "登陸頁網址（https://…）",
"examples": [
"https://example.com/pricing"
]
},
"utm_source": {
"type": "string",
"description": "utm_source 值（轉為小寫，空格變成底線）"
},
"utm_medium": {
"type": "string",
"description": "utm_medium 值（轉為小寫，空格變成底線）"
},
"utm_campaign": {
"type": "string",
"description": "utm_campaign 值（轉為小寫，空格變成底線）"
},
"utm_content": {
"type": "string",
"description": "utm_content 值（轉為小寫，空格變成底線）"
},
"utm_term": {
"type": "string",
"description": "utm_term 值（轉為小寫，空格變成底線）"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "標籤。以逗號分隔的值會被拆開",
"default": []
},
"notes": {
"type": "string",
"description": "自由文字備註"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"destination",
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "連結 id，例如 lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "登陸頁網址"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "要分享的完整帶標記網址"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/campaigns/links/:id.json
刪除已儲存的連結
links_delete
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "連結 id，例如 lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "登陸頁網址"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "要分享的完整帶標記網址"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/campaigns/links.json
列出已儲存的行銷活動連結
links_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/campaigns/links.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "搜尋名稱、目的地或行銷活動"
},
"tag": {
"type": "string",
"description": "僅有此標籤的連結"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "連結 id，例如 lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "登陸頁網址"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "要分享的完整帶標記網址"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/campaigns/links/:id/qr.json
已儲存連結的 QR code（SVG）
links_qr
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/campaigns/links/:id/qr.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"size": {
"type": "integer",
"description": "模組大小，單位為像素（2 至 20）",
"default": 6
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"link_id": {
"type": "string",
"description": "連結 id"
},
"url": {
"type": "string",
"description": "已編碼的（帶標記）網址"
},
"svg": {
"type": "string",
"description": "QR code 的獨立 SVG 文件"
}
}
}
GET
/sites/:site_id/campaigns/links/:id.json
取得已儲存的行銷活動連結
links_get
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/campaigns/links/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "連結 id，例如 lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "登陸頁網址"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "要分享的完整帶標記網址"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/campaigns/links/:id.json
變更已儲存的連結
links_update
權限： 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 '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "連結名稱",
"examples": [
"Spring newsletter"
]
},
"destination": {
"type": "string",
"description": "登陸頁網址（https://…）",
"examples": [
"https://example.com/pricing"
]
},
"utm_source": {
"type": "string",
"description": "utm_source 值（轉為小寫，空格變成底線）"
},
"utm_medium": {
"type": "string",
"description": "utm_medium 值（轉為小寫，空格變成底線）"
},
"utm_campaign": {
"type": "string",
"description": "utm_campaign 值（轉為小寫，空格變成底線）"
},
"utm_content": {
"type": "string",
"description": "utm_content 值（轉為小寫，空格變成底線）"
},
"utm_term": {
"type": "string",
"description": "utm_term 值（轉為小寫，空格變成底線）"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "標籤。以逗號分隔的值會被拆開"
},
"notes": {
"type": "string",
"description": "自由文字備註"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"site_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "連結 id，例如 lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "登陸頁網址"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "要分享的完整帶標記網址"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
角色
POST
/workspaces/:workspace_id/roles.json
建立自訂角色
roles_create
權限： members.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/roles.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "角色名稱",
"examples": [
"Client reviewer"
]
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"analytics.read",
"analytics.export",
"content.write",
"sites.manage",
"uptime.manage",
"members.manage",
"tokens.manage",
"billing.manage",
"workspace.manage"
]
},
"description": "此角色授予的權限"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"permissions",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "自訂角色 id（成員上的 custom_role_id）"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "授予的權限"
},
"members": {
"type": "integer",
"description": "擁有此角色的成員"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/roles/:id.json
刪除自訂角色（必須未被使用）
roles_delete
權限： members.manage
範例
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/roles/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "自訂角色 id（成員上的 custom_role_id）"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "授予的權限"
},
"members": {
"type": "integer",
"description": "擁有此角色的成員"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/roles.json
列出自訂角色
roles_list
權限： member
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/roles.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "自訂角色 id（成員上的 custom_role_id）"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "授予的權限"
},
"members": {
"type": "integer",
"description": "擁有此角色的成員"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/workspaces/:workspace_id/roles/:id.json
更新自訂角色
roles_update
權限： members.manage
範例
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/roles/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "角色名稱"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"analytics.read",
"analytics.export",
"content.write",
"sites.manage",
"uptime.manage",
"members.manage",
"tokens.manage",
"billing.manage",
"workspace.manage"
]
},
"description": "此角色授予的權限"
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"workspace_id",
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "自訂角色 id（成員上的 custom_role_id）"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "授予的權限"
},
"members": {
"type": "integer",
"description": "擁有此角色的成員"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
說明與意見回饋
POST
/help.json
向 Privatus Analytics 團隊傳送問題或意見回饋
support_message_send
訊息會以電子郵件寄給團隊，並附上您的帳號、工作區與方案資料。回覆與收據會寄到您的帳號電子郵件。每天最多 10 則訊息。
權限： member
範例
curl -X POST https://privatusanalytics.com/help.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "訊息主旨（最多 150 個字元）",
"examples": [
"Funnel shows no data"
]
},
"message": {
"type": "string",
"description": "您的問題或意見回饋（10 到 5,000 個字元）"
}
},
"required": [
"subject",
"message"
]
}
回應資料
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "提交被接受時一律為 true"
},
"message": {
"type": "string",
"description": "接下來會發生什麼"
}
}
}
警示
POST
/alerts/:id/acknowledge.json
確認最新事件
alerts_acknowledge
權限： analytics.read
範例
curl -X POST https://privatusanalytics.com/alerts/:id/acknowledge.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警示 id，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id（用量警示為 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 靈敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知管道 id"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/alerts.json
建立警示
alerts_create
權限： content.write
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/alerts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id（pa_…）。除了用量警示外皆為必填"
},
"metric": {
"type": "string",
"description": "threshold/anomaly：visitors、visits、pageviews、bounce_rate 或 conversion。vitals：lcp、inp、cls、fcp 或 ttfb"
},
"operator": {
"type": "string",
"description": "比較運算子（gt、gte、lt、lte）。anomaly：lt 只偵測下降，gt 只偵測飆升，留空則兩者皆是",
"enum": [
"gt",
"gte",
"lt",
"lte"
]
},
"threshold": {
"type": "number",
"description": "threshold：指標值，goal：完成次數，no_data：小時，usage：百分比，ssl：天數，vitals：毫秒（CLS：分數）"
},
"window_minutes": {
"type": "integer",
"description": "評估視窗，單位為分鐘（5 至 10080）"
},
"sensitivity": {
"type": "string",
"description": "anomaly：low、medium 或 high",
"enum": [
"low",
"medium",
"high"
]
},
"goal_id": {
"type": "string",
"description": "goal 與 conversion 警示：目標 id（goal_…）"
},
"uptime_check_id": {
"type": "string",
"description": "uptime/ssl：檢查 id（預設：網站的所有檢查）"
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知管道 id（nch_…）"
},
"enabled": {
"type": "boolean",
"description": "評估此警示"
},
"name": {
"type": "string",
"description": "警示名稱",
"examples": [
"Traffic dropped"
]
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"kind",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警示 id，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id（用量警示為 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 靈敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知管道 id"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/alerts/:id.json
刪除警示
alerts_delete
權限： content.write
範例
curl -X DELETE https://privatusanalytics.com/alerts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警示 id，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id（用量警示為 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 靈敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知管道 id"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/alerts/:id/history.json
警示的事件記錄
alerts_history
權限： analytics.read
範例
curl https://privatusanalytics.com/alerts/:id/history.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"open": {
"type": "boolean",
"description": "僅未解決的事件",
"default": false
},
"id": {
"type": "string",
"description": "資源的 Id"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"triggered_at": {
"type": "string",
"format": "date-time"
},
"resolved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"value": {
"anyOf": [
{
"type": "number",
"description": "觸發時測得的值"
},
{
"type": "null"
}
]
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"acknowledged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"acknowledged_by": {
"anyOf": [
{
"type": "string",
"description": "確認者的名稱"
},
{
"type": "null"
}
]
}
}
}
}
GET
/workspaces/:workspace_id/alerts.json
列出警示
alerts_list
權限： analytics.read
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/alerts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "僅此網站的警示（pa_…）"
},
"state": {
"type": "string",
"description": "僅 ok 或 triggered 的警示",
"enum": [
"ok",
"triggered"
]
},
"kind": {
"type": "string",
"description": "僅此類型",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警示 id，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id（用量警示為 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 靈敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知管道 id"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/alerts/:id/mute.json
靜音（或取消靜音）警示通知
alerts_mute
權限： content.write
範例
curl -X POST https://privatusanalytics.com/alerts/:id/mute.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"minutes": {
"type": "integer",
"description": "靜音的分鐘數（0 為取消靜音，最多 30 天）",
"default": 60
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警示 id，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id（用量警示為 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 靈敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知管道 id"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/alerts/:id.json
取得警示
alerts_get
權限： analytics.read
範例
curl https://privatusanalytics.com/alerts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警示 id，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id（用量警示為 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 靈敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知管道 id"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/alerts/:id.json
更新警示
alerts_update
權限： content.write
範例
curl -X PATCH https://privatusanalytics.com/alerts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id（pa_…）。除了用量警示外皆為必填"
},
"metric": {
"type": "string",
"description": "threshold/anomaly：visitors、visits、pageviews、bounce_rate 或 conversion。vitals：lcp、inp、cls、fcp 或 ttfb"
},
"operator": {
"type": "string",
"description": "比較運算子（gt、gte、lt、lte）。anomaly：lt 只偵測下降，gt 只偵測飆升，留空則兩者皆是",
"enum": [
"gt",
"gte",
"lt",
"lte"
]
},
"threshold": {
"type": "number",
"description": "threshold：指標值，goal：完成次數，no_data：小時，usage：百分比，ssl：天數，vitals：毫秒（CLS：分數）"
},
"window_minutes": {
"type": "integer",
"description": "評估視窗，單位為分鐘（5 至 10080）"
},
"sensitivity": {
"type": "string",
"description": "anomaly：low、medium 或 high",
"enum": [
"low",
"medium",
"high"
]
},
"goal_id": {
"type": "string",
"description": "goal 與 conversion 警示：目標 id（goal_…）"
},
"uptime_check_id": {
"type": "string",
"description": "uptime/ssl：檢查 id（預設：網站的所有檢查）"
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知管道 id（nch_…）"
},
"enabled": {
"type": "boolean",
"description": "評估此警示"
},
"name": {
"type": "string",
"description": "警示名稱"
},
"kind": {
"type": "string",
"description": "警示類型",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警示 id，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id（用量警示為 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 靈敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知管道 id"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/alerts.json
列出網站的警示
site_alerts_list
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/alerts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"state": {
"type": "string",
"description": "僅 ok 或 triggered 的警示",
"enum": [
"ok",
"triggered"
]
},
"kind": {
"type": "string",
"description": "僅此類型",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "警示 id，例如 alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "網站 id（用量警示為 null）"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold、anomaly、goal、no_data、usage、uptime、ssl 或 vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt、gte、lt 或 lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly 靈敏度"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "通知管道 id"
},
"state": {
"type": "string",
"description": "ok 或 triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
資料倉儲同步
POST
/workspaces/:workspace_id/warehouses.json
新增資料倉儲目的地
warehouse_destinations_create
權限： workspace.manage
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/warehouses.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "顯示名稱，例如 Data lake"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要傳送的網站（pa_…）。留空則傳送所有網站"
},
"bucket": {
"type": "string",
"description": "s3：儲存貯體名稱"
},
"region": {
"type": "string",
"description": "s3：區域，例如 us-east-1（R2 使用 auto）"
},
"prefix": {
"type": "string",
"description": "s3/azure：路徑前綴，例如 privatus/events"
},
"endpoint": {
"type": "string",
"description": "s3：S3 相容儲存空間的 https 端點（GCS interoperability、R2、MinIO）"
},
"access_key_id": {
"type": "string",
"description": "s3：access key id"
},
"secret_access_key": {
"type": "string",
"description": "s3：secret access key（唯寫）"
},
"service_account_json": {
"type": "string",
"description": "bigquery：具有 BigQuery Data Editor 的服務帳戶 JSON 金鑰（唯寫）"
},
"project_id": {
"type": "string",
"description": "bigquery：專案 id（預設：取自金鑰）"
},
"dataset": {
"type": "string",
"description": "bigquery：資料集 id"
},
"table": {
"type": "string",
"description": "bigquery/snowflake：資料表名稱（欄位：schema v1）"
},
"account": {
"type": "string",
"description": "snowflake：帳號識別碼，例如 xy12345.us-east-1 或 myorg-myaccount"
},
"user": {
"type": "string",
"description": "snowflake：使用金鑰組驗證的使用者"
},
"private_key": {
"type": "string",
"description": "snowflake：PEM RSA 私密金鑰（唯寫）"
},
"database": {
"type": "string",
"description": "snowflake：資料庫"
},
"schema": {
"type": "string",
"description": "snowflake：schema"
},
"warehouse": {
"type": "string",
"description": "snowflake：虛擬倉儲"
},
"role": {
"type": "string",
"description": "snowflake：角色（選填）"
},
"sas_url": {
"type": "string",
"description": "azure：具有建立與寫入權限的容器 SAS URL（唯寫）"
},
"kind": {
"type": "string",
"description": "s3（也適用 GCS/R2/MinIO）、bigquery、snowflake 或 azure",
"enum": [
"s3",
"bigquery",
"snowflake",
"azure"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"kind",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 id，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "資料的去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table，或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填寫的設定名稱（絕不回傳值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "已傳送的網站（pa_…）。留空表示所有網站"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，傳送前一個 UTC 日"
},
"schema_version": {
"type": "string",
"description": "傳送的列 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/warehouses/:id.json
刪除資料倉儲目的地
warehouse_destinations_delete
權限： workspace.manage
範例
curl -X DELETE https://privatusanalytics.com/warehouses/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 id，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "資料的去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table，或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填寫的設定名稱（絕不回傳值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "已傳送的網站（pa_…）。留空表示所有網站"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，傳送前一個 UTC 日"
},
"schema_version": {
"type": "string",
"description": "傳送的列 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/warehouses.json
列出資料倉儲目的地
warehouse_destinations_list
權限： workspace.manage
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/warehouses.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "僅此類型的目的地",
"enum": [
"s3",
"bigquery",
"snowflake",
"azure"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 id，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "資料的去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table，或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填寫的設定名稱（絕不回傳值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "已傳送的網站（pa_…）。留空表示所有網站"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，傳送前一個 UTC 日"
},
"schema_version": {
"type": "string",
"description": "傳送的列 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/warehouses/:id.json
取得資料倉儲目的地（不含密鑰）
warehouse_destinations_get
權限： workspace.manage
範例
curl https://privatusanalytics.com/warehouses/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 id，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "資料的去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table，或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填寫的設定名稱（絕不回傳值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "已傳送的網站（pa_…）。留空表示所有網站"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，傳送前一個 UTC 日"
},
"schema_version": {
"type": "string",
"description": "傳送的列 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/warehouses/:id/sync.json
立即將單日同步加入佇列
warehouse_destinations_sync
權限： workspace.manage
範例
curl -X POST https://privatusanalytics.com/warehouses/:id/sync.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "要傳送的 UTC 日期，例如 2026-09-28（預設：昨天）"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 id，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "資料的去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table，或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填寫的設定名稱（絕不回傳值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "已傳送的網站（pa_…）。留空表示所有網站"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，傳送前一個 UTC 日"
},
"schema_version": {
"type": "string",
"description": "傳送的列 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/warehouses/:id.json
更新資料倉儲目的地（留白的密鑰會保留）
warehouse_destinations_update
權限： workspace.manage
範例
curl -X PATCH https://privatusanalytics.com/warehouses/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "顯示名稱，例如 Data lake"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要傳送的網站（pa_…）。留空則傳送所有網站"
},
"bucket": {
"type": "string",
"description": "s3：儲存貯體名稱"
},
"region": {
"type": "string",
"description": "s3：區域，例如 us-east-1（R2 使用 auto）"
},
"prefix": {
"type": "string",
"description": "s3/azure：路徑前綴，例如 privatus/events"
},
"endpoint": {
"type": "string",
"description": "s3：S3 相容儲存空間的 https 端點（GCS interoperability、R2、MinIO）"
},
"access_key_id": {
"type": "string",
"description": "s3：access key id"
},
"secret_access_key": {
"type": "string",
"description": "s3：secret access key（唯寫）"
},
"service_account_json": {
"type": "string",
"description": "bigquery：具有 BigQuery Data Editor 的服務帳戶 JSON 金鑰（唯寫）"
},
"project_id": {
"type": "string",
"description": "bigquery：專案 id（預設：取自金鑰）"
},
"dataset": {
"type": "string",
"description": "bigquery：資料集 id"
},
"table": {
"type": "string",
"description": "bigquery/snowflake：資料表名稱（欄位：schema v1）"
},
"account": {
"type": "string",
"description": "snowflake：帳號識別碼，例如 xy12345.us-east-1 或 myorg-myaccount"
},
"user": {
"type": "string",
"description": "snowflake：使用金鑰組驗證的使用者"
},
"private_key": {
"type": "string",
"description": "snowflake：PEM RSA 私密金鑰（唯寫）"
},
"database": {
"type": "string",
"description": "snowflake：資料庫"
},
"schema": {
"type": "string",
"description": "snowflake：schema"
},
"warehouse": {
"type": "string",
"description": "snowflake：虛擬倉儲"
},
"role": {
"type": "string",
"description": "snowflake：角色（選填）"
},
"sas_url": {
"type": "string",
"description": "azure：具有建立與寫入權限的容器 SAS URL（唯寫）"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "目的地 id，例如 whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3、bigquery、snowflake 或 azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "資料的去向：s3://bucket/prefix、project.dataset.table、account/database.schema.table，或 Azure 容器"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "已填寫的設定名稱（絕不回傳值）"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "已傳送的網站（pa_…）。留空表示所有網站"
},
"schedule": {
"type": "string",
"description": "daily：02:00 UTC，傳送前一個 UTC 日"
},
"schema_version": {
"type": "string",
"description": "傳送的列 schema"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
追蹤
POST
/sites/:site_id/tracking/ingest_key.json
建立或輪換伺服器擷取金鑰（僅顯示一次）
tracking_ingest_key_rotate
權限： sites.manage
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/tracking/ingest_key.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id"
},
"key": {
"type": "string",
"description": "擷取金鑰。僅顯示一次，請立即儲存。以 Bearer token 傳送到 POST /api/events"
},
"prefix": {
"type": "string",
"description": "設定中顯示的金鑰前綴"
}
}
}
DELETE
/sites/:site_id/tracking/ingest_key.json
撤銷伺服器擷取金鑰
tracking_ingest_key_revoke
權限： sites.manage
範例
curl -X DELETE https://privatusanalytics.com/sites/:site_id/tracking/ingest_key.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "追蹤程式碼片段中使用的網站 id"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "伺服器擷取金鑰的開頭"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML 追蹤程式碼片段"
},
"favorite": {
"type": "boolean",
"description": "已由您加星號"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/tracking/verify.json
檢查網站是否已安裝追蹤器（script 標籤、網站 id、CSP 與 referrer 政策）
tracking_verify
權限： sites.manage
範例
curl -X POST https://privatusanalytics.com/sites/:site_id/tracking/verify.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "要檢查的頁面（預設為 https://<domain>/）"
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
GET
/sites/:site_id/tracking/snippet.json
依所選選項產生追蹤程式碼片段
tracking_snippet
權限： analytics.read
範例
curl https://privatusanalytics.com/sites/:site_id/tracking/snippet.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"modules": {
"type": "array",
"items": {
"type": "string"
},
"description": "選用模組：auto（外部連結、下載、表單、404）、engage（時間與捲動）、vitals（Web Vitals）、clicks",
"default": [
"engage"
]
},
"manual": {
"type": "boolean",
"description": "關閉自動瀏覽量",
"default": false
},
"spa": {
"type": "string",
"description": "單頁應用程式導覽追蹤",
"enum": [
"auto",
"history",
"hash",
"off"
],
"default": "auto"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "僅在這些主機名稱上追蹤",
"default": []
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "不追蹤的路徑 glob，例如 /admin/*",
"default": []
},
"query_params": {
"type": "array",
"items": {
"type": "string"
},
"description": "要額外保留的查詢參數，例如 page",
"default": []
},
"mask": {
"type": "array",
"items": {
"type": "string"
},
"description": "用戶端路徑遮罩，例如 /u/*->/u/:id",
"default": []
},
"site_id": {
"type": "string",
"description": "網站 id，例如 pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
回應資料
{
"type": "object"
}
通知管道
POST
/workspaces/:workspace_id/channels.json
新增通知管道
notification_channels_create
權限： content.write
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/channels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Webhook URL（slack、teams、discord、webhook），HTTPS"
},
"secret": {
"type": "string",
"description": "webhook：用於 X-Privatus-Signature 的 HMAC 密鑰"
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "email：收件人地址（最多 20 個）"
},
"routing_key": {
"type": "string",
"description": "pagerduty：Events API v2 整合金鑰"
},
"api_key": {
"type": "string",
"description": "opsgenie：API 整合金鑰"
},
"region": {
"type": "string",
"description": "opsgenie：帳號區域",
"enum": [
"us",
"eu"
]
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push",
"enum": [
"email",
"slack",
"teams",
"discord",
"webhook",
"pagerduty",
"opsgenie",
"push"
]
},
"name": {
"type": "string",
"description": "顯示名稱",
"examples": [
"#alerts"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"kind",
"name",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "管道 id，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/channels/:id.json
刪除通知管道
notification_channels_delete
權限： content.write
範例
curl -X DELETE https://privatusanalytics.com/channels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "管道 id，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/channels.json
列出通知管道
notification_channels_list
權限： analytics.read
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/channels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "僅此類型的管道",
"enum": [
"email",
"slack",
"teams",
"discord",
"webhook",
"pagerduty",
"opsgenie",
"push"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "管道 id，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/channels/:id/send_test.json
透過管道傳送測試訊息
notification_channels_send_test
權限： content.write
範例
curl -X POST https://privatusanalytics.com/channels/:id/send_test.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "管道 id，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/channels/:id.json
取得通知管道
notification_channels_get
權限： analytics.read
範例
curl https://privatusanalytics.com/channels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "管道 id，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/channels/:id.json
更新通知管道
notification_channels_update
權限： content.write
範例
curl -X PATCH https://privatusanalytics.com/channels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Webhook URL（slack、teams、discord、webhook），HTTPS"
},
"secret": {
"type": "string",
"description": "webhook：用於 X-Privatus-Signature 的 HMAC 密鑰"
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "email：收件人地址（最多 20 個）"
},
"routing_key": {
"type": "string",
"description": "pagerduty：Events API v2 整合金鑰"
},
"api_key": {
"type": "string",
"description": "opsgenie：API 整合金鑰"
},
"region": {
"type": "string",
"description": "opsgenie：帳號區域",
"enum": [
"us",
"eu"
]
},
"name": {
"type": "string",
"description": "顯示名稱"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "管道 id，例如 nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email、slack、teams、discord、webhook、pagerduty、opsgenie 或 push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "已遮蔽的目的地"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/push_subscription.json
註冊瀏覽器以接收推播通知
push_subscriptions_create
權限： member
範例
curl -X POST https://privatusanalytics.com/push_subscription.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"endpoint": {
"type": "string",
"description": "瀏覽器的 PushSubscription.endpoint"
},
"p256dh": {
"type": "string",
"description": "PushSubscription keys.p256dh（base64url）"
},
"auth": {
"type": "string",
"description": "PushSubscription keys.auth（base64url）"
}
},
"required": [
"endpoint",
"p256dh",
"auth"
]
}
回應資料
{
"type": "object",
"properties": {
"endpoint_host": {
"type": "string",
"description": "推播服務主機"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/push_subscription.json
移除瀏覽器推播註冊
push_subscriptions_delete
權限： member
範例
curl -X DELETE https://privatusanalytics.com/push_subscription.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"endpoint": {
"type": "string",
"description": "要移除的 PushSubscription.endpoint"
}
},
"required": [
"endpoint"
]
}
回應資料
{
"type": "object",
"properties": {
"endpoint_host": {
"type": "string",
"description": "推播服務主機"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
電子郵件報告
DELETE
/recipients/:id.json
從電子郵件報告中移除收件人
email_report_recipients_delete
權限： content.write
範例
curl -X DELETE https://privatusanalytics.com/recipients/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 id，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "電子郵件地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次寄出邀請的時間"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待處理邀請的到期時間"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "地址變為 active 的時間"
},
{
"type": "null"
}
]
}
}
}
GET
/reports/:report_id/recipients.json
列出電子郵件報告的收件人及其狀態
email_report_recipients_list
狀態：active（會收到報告）、pending（已邀請，尚未接受）、declined 或 unsubscribed。請透過報告的收件人清單新增或移除地址。
權限： analytics.read
範例
curl https://privatusanalytics.com/reports/:report_id/recipients.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "只列出此狀態的收件人",
"enum": [
"pending",
"active",
"declined",
"unsubscribed"
]
},
"report_id": {
"type": "string",
"description": "資源的 Report"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"report_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 id，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "電子郵件地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次寄出邀請的時間"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待處理邀請的到期時間"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "地址變為 active 的時間"
},
{
"type": "null"
}
]
}
}
}
}
POST
/recipients/:id/resend.json
重新寄送待處理的報告邀請
email_report_recipients_resend
以新的連結重新寄送邀請。每份報告的每個地址每 7 天可寄送一次。
權限： content.write
範例
curl -X POST https://privatusanalytics.com/recipients/:id/resend.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 id，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "電子郵件地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次寄出邀請的時間"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待處理邀請的到期時間"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "地址變為 active 的時間"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/reports.json
建立電子郵件報告
email_reports_create
權限： content.write
範例
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/reports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告包含的網站 id（pa_…）"
},
"frequency": {
"type": "string",
"description": "daily、weekly（在星期幾）或 monthly（每月 1 日）",
"enum": [
"daily",
"weekly",
"monthly"
]
},
"hour": {
"type": "integer",
"description": "傳送的時刻（0 至 23，工作區時區）"
},
"weekday": {
"type": "integer",
"description": "每週報告：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "電子郵件地址（不需要帳號）。可用逗號或換行分隔。工作區成員會立即加入。其他人會收到邀請，接受後才會收到報告。已退訂報告的地址會被拒絕"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "內容：kpis、chart、pages、sources、goals、campaigns、vitals、uptime"
},
"attach_pdf": {
"type": "boolean",
"description": "附上 PDF 版本"
},
"intro": {
"type": "string",
"description": "自訂簡介文字（最多 2000 字元）"
},
"enabled": {
"type": "boolean",
"description": "依排程傳送"
},
"name": {
"type": "string",
"description": "報告名稱",
"examples": [
"Weekly traffic"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "報告 id，例如 rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告中的網站 id"
},
"frequency": {
"type": "string",
"description": "daily、weekly 或 monthly"
},
"hour": {
"type": "integer",
"description": "傳送時刻（工作區時區）"
},
"weekday": {
"type": "integer",
"description": "每週：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告上的每個地址，不論狀態"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 id，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "電子郵件地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次寄出邀請的時間"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待處理邀請的到期時間"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "地址變為 active 的時間"
},
{
"type": "null"
}
]
}
}
},
"description": "每位收件人及其訂閱狀態（只有 active 的收件人會收到報告）"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "內容區塊"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/reports/:id/deliveries.json
電子郵件報告的寄送記錄
email_reports_deliveries
權限： analytics.read
範例
curl https://privatusanalytics.com/reports/:id/deliveries.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "僅此狀態的傳送",
"enum": [
"sent",
"test",
"failed",
"skipped"
]
},
"id": {
"type": "string",
"description": "資源的 Id"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "sent、test、failed 或 skipped"
},
"recipients_count": {
"type": "integer"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sent_at": {
"type": "string",
"format": "date-time"
}
}
}
}
DELETE
/reports/:id.json
刪除電子郵件報告
email_reports_delete
權限： content.write
範例
curl -X DELETE https://privatusanalytics.com/reports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "報告 id，例如 rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告中的網站 id"
},
"frequency": {
"type": "string",
"description": "daily、weekly 或 monthly"
},
"hour": {
"type": "integer",
"description": "傳送時刻（工作區時區）"
},
"weekday": {
"type": "integer",
"description": "每週：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告上的每個地址，不論狀態"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 id，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "電子郵件地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次寄出邀請的時間"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待處理邀請的到期時間"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "地址變為 active 的時間"
},
{
"type": "null"
}
]
}
}
},
"description": "每位收件人及其訂閱狀態（只有 active 的收件人會收到報告）"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "內容區塊"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/reports.json
列出電子郵件報告
email_reports_list
權限： analytics.read
範例
curl https://privatusanalytics.com/workspaces/:workspace_id/reports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"frequency": {
"type": "string",
"description": "僅此頻率的報告",
"enum": [
"daily",
"weekly",
"monthly"
]
},
"workspace_id": {
"type": "string",
"description": "工作區 id，例如 ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "頁碼（從 1 開始）"
},
"per_page": {
"type": "integer",
"description": "每頁結果數（最多 100）"
}
},
"required": [
"workspace_id"
]
}
回應資料
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "報告 id，例如 rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告中的網站 id"
},
"frequency": {
"type": "string",
"description": "daily、weekly 或 monthly"
},
"hour": {
"type": "integer",
"description": "傳送時刻（工作區時區）"
},
"weekday": {
"type": "integer",
"description": "每週：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告上的每個地址，不論狀態"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 id，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "電子郵件地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次寄出邀請的時間"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待處理邀請的到期時間"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "地址變為 active 的時間"
},
{
"type": "null"
}
]
}
}
},
"description": "每位收件人及其訂閱狀態（只有 active 的收件人會收到報告）"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "內容區塊"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/reports/:id/send_test.json
立即寄送電子郵件報告作為測試
email_reports_send_test
權限： content.write
範例
curl -X POST https://privatusanalytics.com/reports/:id/send_test.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"recipient": {
"type": "string",
"description": "在此傳送測試（預設：您的電子郵件）"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "sent、test、failed 或 skipped"
},
"recipients_count": {
"type": "integer"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sent_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/reports/:id.json
取得電子郵件報告
email_reports_get
權限： analytics.read
範例
curl https://privatusanalytics.com/reports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"輸入
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "報告 id，例如 rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告中的網站 id"
},
"frequency": {
"type": "string",
"description": "daily、weekly 或 monthly"
},
"hour": {
"type": "integer",
"description": "傳送時刻（工作區時區）"
},
"weekday": {
"type": "integer",
"description": "每週：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告上的每個地址，不論狀態"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 id，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "電子郵件地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次寄出邀請的時間"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待處理邀請的到期時間"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "地址變為 active 的時間"
},
{
"type": "null"
}
]
}
}
},
"description": "每位收件人及其訂閱狀態（只有 active 的收件人會收到報告）"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "內容區塊"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/reports/:id.json
更新電子郵件報告
email_reports_update
權限： content.write
範例
curl -X PATCH https://privatusanalytics.com/reports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告包含的網站 id（pa_…）"
},
"frequency": {
"type": "string",
"description": "daily、weekly（在星期幾）或 monthly（每月 1 日）",
"enum": [
"daily",
"weekly",
"monthly"
]
},
"hour": {
"type": "integer",
"description": "傳送的時刻（0 至 23，工作區時區）"
},
"weekday": {
"type": "integer",
"description": "每週報告：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "電子郵件地址（不需要帳號）。可用逗號或換行分隔。工作區成員會立即加入。其他人會收到邀請，接受後才會收到報告。已退訂報告的地址會被拒絕"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "內容：kpis、chart、pages、sources、goals、campaigns、vitals、uptime"
},
"attach_pdf": {
"type": "boolean",
"description": "附上 PDF 版本"
},
"intro": {
"type": "string",
"description": "自訂簡介文字（最多 2000 字元）"
},
"enabled": {
"type": "boolean",
"description": "依排程傳送"
},
"name": {
"type": "string",
"description": "報告名稱"
},
"id": {
"type": "string",
"description": "資源的 Id"
}
},
"required": [
"id"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "報告 id，例如 rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告中的網站 id"
},
"frequency": {
"type": "string",
"description": "daily、weekly 或 monthly"
},
"hour": {
"type": "integer",
"description": "傳送時刻（工作區時區）"
},
"weekday": {
"type": "integer",
"description": "每週：0 = 星期日 … 6 = 星期六"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "報告上的每個地址，不論狀態"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 id，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "電子郵件地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次寄出邀請的時間"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待處理邀請的到期時間"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "地址變為 active 的時間"
},
{
"type": "null"
}
]
}
}
},
"description": "每位收件人及其訂閱狀態（只有 active 的收件人會收到報告）"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "內容區塊"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/reports/invites/:token/accept.json
接受報告邀請
report_invites_accept
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/reports/invites/:token/accept.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "資源的 Token"
}
},
"required": [
"token"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 id，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "電子郵件地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次寄出邀請的時間"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待處理邀請的到期時間"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "地址變為 active 的時間"
},
{
"type": "null"
}
]
}
}
}
POST
/reports/invites/:token/decline.json
婉拒報告邀請
report_invites_decline
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/reports/invites/:token/decline.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "資源的 Token"
}
},
"required": [
"token"
]
}
回應資料
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "收件人 id，例如 rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "電子郵件地址"
},
"status": {
"type": "string",
"description": "active、pending、declined 或 unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "上次寄出邀請的時間"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "待處理邀請的到期時間"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "地址變為 active 的時間"
},
{
"type": "null"
}
]
}
}
}
POST
/reports/resubscribe/:token.json
在退訂後重新接收報告
report_resubscribes_confirm
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/reports/resubscribe/:token.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "資源的 Token"
}
},
"required": [
"token"
]
}
回應資料
{
"type": "object"
}
POST
/reports/unsubscribe/:token/resubscribe.json
寄送一個可重新接收報告的連結到某個地址
report_resubscribes_create
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/reports/unsubscribe/:token/resubscribe.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "資源的 Token"
}
},
"required": [
"token"
]
}
回應資料
{
"type": "object"
}
POST
/reports/unsubscribe/:token.json
取消某個地址的電子郵件報告訂閱
report_unsubscribes_create
權限： public
· 僅限 HTTP（不是 MCP 工具）
範例
curl -X POST https://privatusanalytics.com/reports/unsubscribe/:token.json \
-H "Content-Type: application/json" -d '{…}'輸入
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "資源的 Token"
}
},
"required": [
"token"
]
}
回應資料
{
"type": "object"
}