コンテンツにスキップ
Game Market Copilot Docs
日本語
English日本語
Esc
↑↓navigate↵open⌘Jpreview
このページの内容

APIの概要

GMC REST APIのベースURL、認証方式、レスポンスエンベロープ、エラー、クレジット・レート制限の挙動について解説します。

ベースURL

すべてのエンドポイントは次のパス以下でバージョン管理されています。

https://gamemarketcopilot.com/api/v1

認証済みのアクセス（APIキーまたはCLI認証情報）にはAPIアクセスを含むプランが必要 です。StarterとProには標準で含まれており、無償アクセスの付与によって有効化さ れる場合もあります。未認証の呼び出しでもほとんどの読み取りエンドポイントには 到達でき、件数を制限した公開プレビューを取得できます。結果には上限が設けられ、 一部のフィールドは省略されるのではなくロックまたはマスクされた状態で返される ため、レスポンスの形状自体は変わりません。各プランで解放される内容は /plansを参照してください。

認証

このAPIはすべてのリクエストでベアラートークンを受け付けます。

Authorization: Bearer <token>

トークンには3種類があり、互いに互換性はありません。

  1. APIキー（gmc_...）。GMCダッシュボードの設定 → API・連携で作成しま す。シークレットは作成時に一度だけ表示されるため、シークレットマネー ジャーやCI変数に保存してください。CI、バックグラウンドジョブ、サーバー 間連携に最適です。
  2. CLI認証情報（gmcc_...）。gmc loginを実行したとき（/cli を参照）にブラウザのOAuthフローで発行されます。有効期限が短く、自分で 管理する長期シークレットではなくブラウザセッションに紐づいているため、 ローカル開発に向いています。
  3. MCP OAuthトークン。MCPクライアント向けに発行され、MCPエンドポイント のみにスコープされます。このREST APIでは拒否されます。MCPの呼び出し元 は/api/v1/...を直接叩くのではなく、MCPプロトコルの経路を使用します。 /agents/mcpを参照してください。

ブラウザアプリ自体は上記のいずれのトークンも使用しません。Copilotチャット、 チャート生成、エクスポートの各エンドポイントはブラウザセッションのCookieで 認証されており、このベアラートークンAPIの契約には含まれないため、APIキーや CLI認証情報では呼び出せません。

レスポンスエンベロープ

成功時のレスポンスはすべて同じ形のJSONオブジェクトです（paginationと warningsは該当する場合のみ含まれます）。

{
  "data": {},
  "meta": {
    "requestId": "req_...",
    "generatedAt": "2026-01-01T00:00:00.000Z"
  },
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1234,
    "nextOffset": 20
  },
  "warnings": []
}
  • dataはペイロード本体です。その形はエンドポイントごとに異なり、OpenAPI 契約で定義されています。
  • metaには常にrequestId（問題を報告する際に役立ちます）と generatedAtが含まれます。エンドポイントによっては、エンタイトルメント、 タクソノミー、翻訳、処理時間に関する情報も含まれます。
  • paginationは一覧系エンドポイントに含まれ、offset/limit方式のページング を使用します。リクエストにlimitとoffsetを指定し、レスポンスの totalと（存在する場合は）nextOffsetから次のページを取得してください。
  • warningsは、エラーには至らないものの何かを伝えたい場合に含まれます。 たとえばデータソースの一部が劣化しているときなどです。

エラー

REST APIのエラーは、安定した機械可読のcodeを持つ単一のエンベロープで返さ れます（MCPツールのエラーは、MCPプロトコルで定義されたよりフラットな独自 の形を持ちます）。以下は発生する可能性が最も高いコードで、エッジケースで はこの他のコードが返ることもあります。

{
  "error": {
    "code": "INVALID_TAG",
    "message": "Unknown tags: foo. Search valid tags at GET /api/v1/tags.",
    "param": "tags",
    "requestId": "req_..."
  }
}

安定したエラーコード:

コード HTTPステータス 内容
BAD_REQUEST 400 リクエストパラメーターがバリデーションに失敗しました。
INVALID_TAG 400 tagsの値の一部が既知のスラッグではありません。エラーには不明なタグと候補の置き換え案が含まれます。事前にGET /api/v1/tagsでタグを解決してください。
UNAUTHORIZED 401 トークンがない、トークンが無効・期限切れである、またはこのエンドポイントに対してトークンの種類が合っていません（例: REST APIに対するMCPトークン）。
PLAN_REQUIRED 402 ワークスペースの現在のプランにこのエンドポイントが含まれていません。
FORBIDDEN 403 トークンは有効ですが、このリソースへのアクセスは許可されていません。
QUOTA_EXCEEDED 429 ワークスペースの月間クレジット枠を使い切りました。
RATE_LIMITED 429 短時間に多くのリクエストが送信されました。

クレジットとレート制限

すべての呼び出しはクレジットで課金されます。課金内訳はGMCダッシュボードの利 用状況画面に項目ごとに表示され、現在の利用状況と残りの枠は/api/v1/status から取得できます。またMCPツールのレスポンスには、そのメタデータに正確な課 金額が追加で含まれます。料金はプロダクトの進化に伴って変わるため、このサイ トではエンドポイントごとの固定価格表は公開していません。代わりにコストモデ ルでは、エンドポイントを少数のコストクラスに分類しています。

  • 無料: ステータス確認やタグ一覧の取得など、市場データに触れないワーク スペース・メタデータ操作は無料です。
  • ベースライン: 1本のゲーム詳細を取得するようなシンプルな読み取りは、 課金対象の中で最も安価です。
  • 件数と小規模集計: 回答の背後にあるスキャン範囲が広い分、ベースライン の読み取りより少し高くなります。
  • タイトル単位の分析生成: 1タイトル分のレビューやマーケティング分析を 生成するエンドポイントは、背後にある大量のデータを統合・要約するため、 ベースラインの数倍のコストになります。
  • 重いコホート集計分析: 多数のゲームを横断してスキャン・統合するコホー トレベルやタイトル横断のベンチマーク系エンドポイントが最もコストが高くな ります。

HTTP 429は2つの異なる原因で発生し、いずれの場合もRetry-Afterヘッダー(秒数) が含まれます。

  • RATE_LIMITED: 短時間に呼び出しすぎています。指定されたRetry-Afterの 分だけ待ってから再試行してください。
  • QUOTA_EXCEEDED: ワークスペースの月間クレジット枠を使い切っています。 Retry-Afterは枠がリセットされるまでの時間を示し、実務的な対処はプラン のアップグレードかリセット待ちです。/plansを参照してくださ い。

想定外にどちらかの状態になった場合は/troubleshooting を確認してください。

契約のソース

このページと/api/endpointsは、API全体に共通する挙動を 説明するものです。エンドポイントごとのパラメーター、フィールド、リクエス ト/レスポンススキーマはあえて記載していません。その詳細レベルにおける正本 はOpenAPIドキュメントです。

次のステップ

  • エンドポイントの分類を見る: /api/endpoints
  • ターミナルからAPIを使う: /cli
  • MCP経由でエージェントからAPIを使う: /agents/mcp

このページは役に立ちましたか？