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 プランでは、1 つのプロジェクトにつき有効な API キーは最大 2 個までで、キーの値は作成時に一度だけ表示されます。上限に達した場合は、不要なキーを無効化してから新しいキーを作成してください。

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 を返します。

このエンドポイントには、プランのクォータとは別に、テナントごとに 1 時間あたり 60 リクエストの専用レート制限があります。上限を超えると Retry-After ヘッダー付きの 429 を返します。

OAuth 2.1

REST API は API キーの代わりに OAuth 2.1 Bearer トークンも受け付けます:

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 トークンが持てる scope は analytics:read と resources:write のみです。クライアントが 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 が生成します。これらの SDK は protobuf の TelemetryBatch をエンコードし、必要なヘッダーを自動で設定します。手動でイベントを送るには、その protobuf スキーマを自分でエンコードし、X-API-Key（events:write scope）、Content-Type: application/x-protobuf、Content-Length、X-SDK-Version を送る必要があります。ほとんどの統合では、直接送信せず SDK を使ってください。

レート制限

API のレート制限はアカウント（テナント）単位で、1 時間あたりのリクエスト数で数えます。同じアカウントに属するすべてのプロジェクトと API キーが、1 つの上限を共有します。 Free プランは 1 時間あたり 100 リクエスト、有料プランはこれより多くなります。

どのレスポンスにも以下の 3 つのヘッダーが付きます:

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 が 1 時間近くまで跳ね上がることがあります。リセット時刻を狙って再送するのではなく、429 レスポンスの Retry-After に従って待機してください。通常のレスポンスでは X-RateLimit-Remaining を見て、上限に達する前にリクエストの間隔を空けてください。

レスポンス形式

Web API（app.framedash.dev/api）と Ingest API（ingest.framedash.dev）はエラーの形が異なります。 1 つのパーサーで両方を扱えると仮定せず、エンドポイントごとに形を分けて処理してください。

Web API

成功時:

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

エラー時、API は RFC 9457 Problem Details を application/problem+json 形式で返します:

{
  "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	2 つのビルドのパフォーマンス比較
`/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