API 概覽

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

基礎 URL

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

驗證

所有請求都需要 API 金鑰。透過 X-API-Key 標頭傳送：

X-API-Key: fd_your_api_key_here

可以在儀表板的「設定」>「API 金鑰」中取得 API 金鑰。

API 金鑰類型

類型	用途
admin	Web API 端點的完整存取權限
write	僅限事件擷取
ci	CI 建置用事件擷取（繞過計費）

速率限制

根據方案套用速率限制。可以透過回應標頭確認：

X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1999
X-RateLimit-Reset: 1700000000

回應格式

Web API

成功時：

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

錯誤時：

{
  "success": false,
  "error": "Error message"
}

Ingest API

成功時：

{
  "status": "accepted"
}

錯誤時：

{
  "error": "Error message"
}

OpenAPI 規格

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

端點

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

Projects

端點	方法	說明
`/v1/projects`	GET	專案清單
`/v1/projects/{id}/status`	GET	專案狀態

Analytics

端點	方法	說明
`/v1/projects/{id}/dashboard`	GET	儀表板指標（DAU、MAU、工作階段、事件數）
`/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	警示評估歷程

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	分析查詢執行

Event Ingestion

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