API 概覽

使用 Framedash REST API 來取得與分析遙測資料。

基礎 URL

服務	URL
Web API (Projects, Maps, Content, Query, Analytics, Alerts, Data)	`https://app.framedash.dev/api`
Ingest API (Event Ingestion)	`https://ingest.framedash.dev`

驗證

/api/v1 下的 REST API 接受 API 金鑰或 OAuth 2.1 Bearer 權杖兩者之一。若一個請求同時傳送兩者，則 X-API-Key 標頭優先。大多數整合使用 API 金鑰，透過 X-API-Key 標頭傳送：

X-API-Key: fd_your_api_key_here

可以在儀表板中每個專案的「API 金鑰」頁面建立 API 金鑰。新的金鑰使用 fd_ 前綴，授權由儲存的 scope 決定，而不是由前綴決定。

在 Free 方案下，每個專案最多可擁有 2 個有效的 API 金鑰，且金鑰值僅在建立時顯示一次。達到上限時，請先停用一個不用的金鑰，再建立新的金鑰。

URL 路徑未依專案限定範圍的端點（如 /v1/content 下的內容註冊表）還需要提供指定目標專案的 X-Project-Id 標頭：

X-Project-Id: your-project-uuid

API 金鑰預設

預設	Scope	用途
Ingest	`events:write`	僅用於 SDK 事件擷取
Read-only	`analytics:read`	儀表板、狀態、分析讀取、CLI 讀取，以及 raw SQL 以外的 MCP 工具
Read & Write	`analytics:read`, `resources:write`	讀取以及地圖、內容、警示變更
Full	`analytics:read`, `resources:write`, `data:admin`	raw SQL 查詢、資料匯出、玩家刪除

驗證金鑰

GET /v1/whoami 會驗證任意有效的 API 金鑰並回傳該金鑰的非敏感中繼資料，且不要求特定 scope。即使金鑰無法存取任何讀取端點（如僅攜帶 events:write 的 Ingest 金鑰），也能藉此確認金鑰是否可用。此處只接受 X-API-Key 標頭，不接受 OAuth Bearer 權杖。

curl https://app.framedash.dev/api/v1/whoami \
  -H "X-API-Key: fd_your_api_key_here"

回應會依 scope 分級。攜帶讀取或管理類 scope（analytics:read、resources:write 或 data:admin）的金鑰回傳完整中繼資料 { projectId, projectName, tenantId, planId, scopes }；僅資料平面的金鑰只回傳 { projectId, scopes }。金鑰原始值絕不回傳；金鑰缺少或無效時回傳 401。

此端點有自己的速率限制，即每租戶每小時 60 次請求，與你的方案配額相互獨立；超過時回傳帶 Retry-After 標頭的 429。

OAuth 2.1

REST API 也接受以 OAuth 2.1 Bearer 權杖取代 API 金鑰：

Authorization: Bearer <access-token>

Framedash 是一個 OAuth 2.1 授權伺服器。用戶端可從 {origin}/.well-known/oauth-authorization-server 探索其端點（{origin} 為 https://app.framedash.dev）：

端點	URL
授權	`{origin}/oauth/authorize`
權杖	`{origin}/api/oauth/token`
動態用戶端註冊 (RFC 7591)	`{origin}/api/oauth/register`
撤銷	`{origin}/api/oauth/revoke`

僅支援帶 PKCE（S256）的授權碼流程，面向公開用戶端（token_endpoint_auth_method 為 none）。授權類型為 authorization_code 和 refresh_token。

OAuth 權杖只能攜帶 analytics:read 和 resources:write scope；用戶端未指定 scope 時授予 analytics:read。data:admin、events:write、events:synthetic scope 絕不透過 OAuth 授予，因此需要它們的操作仍僅限 API 金鑰。例如 POST /v1/query 需要 data:admin，因此無法以 OAuth 權杖呼叫。

已連結應用程式

已授權的 OAuth 應用程式列在儀表板的「設定」→「已連結應用程式」中。每個項目顯示用戶端名稱、已授予的 scope、已同意的專案，以及建立時間與最後使用時間，並可單獨撤銷。

查詢遙測

被取用的事件可以用 SQL 查詢。將 project_id 放在 JSON 主體中（而非請求標頭），並用 X-API-Key 認證。raw SQL 需要 data:admin scope（Full 預設）：

curl -X POST https://app.framedash.dev/api/v1/query \
  -H "X-API-Key: fd_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "your-project-uuid",
    "sql": "SELECT event_name, count() AS events FROM events WHERE timestamp >= today() GROUP BY event_name ORDER BY events DESC",
    "limit": 100
  }'

回應為 { "success": true, "data": { "rows": [...], "rowCount": N } }。被拒絕的查詢會回傳 HTTP 400 及 ClickHouse 診斷訊息（未知的欄位、資料表或函式，語法錯誤，型別不符，禁止的操作）；僅基礎設施故障回傳 500。欄位與驗證器規則見事件表結構，先確認事件是否到達見疑難排解。

取用事件

取用端點（POST /v1/events）只接受 application/x-protobuf（JSON 主體會回傳 415）。事件由官方的 Unity、UE5、Godot SDK 產生，它們會編碼 protobuf 的 TelemetryBatch 並為你設定所需的請求標頭。手動傳送事件代表你要自己編碼該 protobuf 結構，並傳送 X-API-Key（events:write scope）、Content-Type: application/x-protobuf、Content-Length 和 X-SDK-Version。對幾乎所有整合而言，請使用 SDK 而非直接傳送。

速率限制

API 速率限制以帳戶（租戶）為單位執行，並以每小時請求數計。同一帳戶下的所有專案與 API 金鑰共用一個上限。Free 方案為每小時 100 次請求，付費方案更高。

每個回應都會帶有以下三個回應標頭：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1782968400000

X-RateLimit-Reset 是以毫秒（而非秒）為單位的 Unix 時間戳記。

達到上限會回傳 429。此時 X-RateLimit-Remaining 為 0，並會追加一個表示等待秒數的 Retry-After 回應標頭：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782968400000
Retry-After: 3400

此限制以滑動視窗計算。因此在 X-RateLimit-Reset 所示時刻剛過之後，請求仍可能被限制，Retry-After 可能跳升至接近一整小時。請依 429 回應的 Retry-After 退避，而不要依重置時刻安排重試。在正常回應中，讀取 X-RateLimit-Remaining，在達到上限前拉開請求間隔。

回應格式

Web API（app.framedash.dev/api）與 Ingest API（ingest.framedash.dev）回傳的錯誤結構不同。不要假設單一解析器能處理兩者，請依各端點的結構分別處理。

Web API

成功時：

{
  "success": true,
  "data": { ... }
}

錯誤時，API 會以 application/problem+json 格式回傳 RFC 9457 Problem Details：

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Plan limit reached.",
  "error_category": "authorization",
  "retryable": false
}

成員	說明
`type`	問題類型 URI；沒有特定類型時為 `about:blank`。
`title`	HTTP 狀態的簡短、人類可讀摘要。
`status`	HTTP 狀態碼。
`detail`	針對該特定錯誤的人類可讀說明。
`error_category`	`authentication`、`authorization`、`validation`、`rate_limit`、`not_found`、`conflict`、`payload`、`internal` 之一。
`retryable`	重試是否可能成功（429 與 503 為 `true`）。
`retry_after`	選填。建議的重試等待秒數。

Ingest API

成功時：

{
  "status": "accepted"
}

錯誤時：

{
  "error": "Error message"
}

OpenAPI 規格

API 規格可以 OpenAPI 3.1 格式下載。

端點

詳細資訊請參閱側邊欄中自動產生的 API 參考。

Projects

端點	方法	說明
`/v1/projects`	GET	API 金鑰關聯的專案
`/v1/projects/{id}/status`	GET	專案狀態

金鑰驗證

端點	方法	說明
`/v1/whoami`	GET	驗證 API 金鑰並回傳非敏感的金鑰中繼資料

Analytics

端點	方法	說明
`/v1/projects/{id}/dashboard`	GET	儀表板指標（DAU、MAU、工作階段、事件數）
`/v1/projects/{id}/builds`	GET	列出包含效能資料的建置 ID
`/v1/projects/{id}/builds/compare`	GET	比較兩個建置的效能
`/v1/projects/{id}/heatmap`	GET	地圖熱力圖資料
`/v1/projects/{id}/retention`	GET	玩家留存率世代
`/v1/projects/{id}/funnels`	GET	漏斗轉換分析
`/v1/projects/{id}/insights`	GET	依維度聚合分析

Alerts

端點	方法	說明
`/v1/projects/{id}/alerts`	GET	警示規則清單
`/v1/projects/{id}/alerts`	POST	建立警示規則
`/v1/projects/{id}/alerts/{alertId}`	GET	取得警示規則
`/v1/projects/{id}/alerts/{alertId}`	PATCH	更新警示規則
`/v1/projects/{id}/alerts/{alertId}`	DELETE	停用警示規則
`/v1/projects/{id}/alerts/history`	GET	警示評估歷程
`/v1/projects/{id}/threshold-profiles`	GET	閾值設定檔清單

Maps

端點	方法	說明
`/v1/projects/{id}/maps`	GET	地圖清單
`/v1/projects/{id}/maps/{mapId}`	DELETE	刪除地圖
`/v1/maps/upload`	POST	上傳地圖

Content Registry

端點	方法	說明
`/v1/content`	GET	內容項目清單
`/v1/content`	POST	建立/更新內容項目
`/v1/content`	DELETE	刪除內容項目

Query

端點	方法	說明
`/v1/query`	POST	分析查詢執行

Data

端點	方法	說明
`/v1/data/export`	GET	匯出可存取的專案資料
`/v1/data/erase`	POST	刪除指定玩家的遙測資料

Event Ingestion

端點	方法	說明
`/v1/events`	POST	遙測事件擷取

針對 AI 代理: llms.txt