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