API 概览

使用 Framedash REST API 可以获取和分析遥测数据。

注意

详细的 API 参考页面仅提供英文版本。请参阅侧边栏的”Framedash 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	遥测事件摄取