REST API

REST API は、MCP と同じツールを APIキーで呼び出す JSON API です。自作のスクリプトや集計ツールから、マイライブラリやプレイ記録を読み書きできます。ファイル出力（exportMyData・exportMasterData）は REST API だけで使えます。

権限・プラン・応答の共通の決まりはMCP / API の仕様を参照してください。

準備

Retro Game Gather のユーザー設定の MCP / APIで APIキーを発行します
用途に合った権限を選びます（読み取りだけなら「閲覧のみ」）
表示されたキーを安全な場所に保管します

APIキーは Authorization ヘッダーで送ります。

Authorization: Bearer <APIキー>

キーが使えるかは、getAccount で確かめられます。プラン、登録件数と上限、今日の使用率が返れば、キーは有効です。

curl -H "Authorization: Bearer <APIキー>" \
  https://game.retrogather.com/rest/v1/getAccount

ツールの一覧と引数

各ツールの引数（名前・必須・型・許容値・件数の制約）と応答の形は、API リファレンスで確認できます。このリファレンスは、次の公開カタログから生成しています。

エンドポイント	内容
`GET /rest/v1/tools`	ツールのカタログ（JSON）
`GET /rest/v1/openapi.json`	同じカタログを OpenAPI 3.1 に変換したもの

どちらも認証は不要で、利用上限も消費しません。APIキーを付けても付けなくても、同じ内容を返します
定義は最上位のプラン（プレミアム）を基準にしています。自分のプランで使える範囲は、getAccount のプランと、各ツールの plans・planDifferences で判断します
内容が変わると revision（OpenAPI では x-rgg-revision）が変わります。ETag も同じ値で、If-None-Match を送ると、変わっていなければ 304 を返します
メンテナンス中は、他の経路と同じく 503 になります

/rest/v1/tools の各ツールは、name・title（日本語の名前）・description・scopes・plans・methods・annotations・inputSchema・outputSchema と、プランによる違いがあるときだけ planDifferences を持ちます。methods は、読み取りのツールなら ["GET","POST"]、それ以外は ["POST"] です。

プランによる違い（planDifferences）

planDifferences は、プレミアムの定義と比べた、通常（FREE）・ライト（LIGHT）での違いです。

項目	内容
`removedProperties`	そのプランでは受け付けない引数
`changedProperties`	そのプランでの定義（許容値・制約・説明が違う引数）
`required`	必須の引数が基準と違う場合だけ付く

"planDifferences": {
  "FREE": { "removedProperties": ["consoleIds", "includeHistory"] },
  "LIGHT": { "removedProperties": ["includeHistory"] }
}

定義に表れないプランの制約は planDifferences に含まれません。たとえば exportMyData は、出力するデータの種類ごとに必要なプランが違います。これは各ツールの description を参照してください。

定義に表れない決まり

次の決まりは、入力スキーマでは表せません。カタログの notes と各ツールの description を正とします。

GET のクエリでは配列をカンマ区切りにし、値を percent-encode する
オブジェクトの引数（externalId など）は POST の JSON でしか渡せない
limit は 1,000 を超えると 1,000 に丸められ、さらにツールごとの上限が適用される。実際の件数は effectiveLimit・limitReduced で分かる

description は MCP と共通の説明に、REST だけ違う点を 1 文足した形です（例: getGamesBatch は MCP では 20 件、REST では 100 件）。REST では、足された 1 文と入力スキーマの値を正としてください。

ツールリファレンスには、ツールの用途・権限・プランを日本語でまとめています。

呼び出し方

ツールは /rest/v1/{ツール名} で呼び出します。

操作	メソッド	引数の渡し方
読み取り	GET または POST	クエリ文字列、または JSON
追加・更新・削除	POST	JSON

GET のクエリでは、配列をカンマ区切りで渡します。数値と真偽値は入力スキーマに従って変換します
GET のクエリ値は percent-encode してください。 日本語を含む値や、オブジェクトの引数（externalId など）は POST の JSON のほうが確実です
fields=（値なし）は、fields: [] と同じく最小限の項目だけを返します
受け付けるメソッドは GET / POST / PUT です。それ以外は 405 を返します

例: マイライブラリを取得する

curl -H "Authorization: Bearer <APIキー>" \
  "https://game.retrogather.com/rest/v1/getLibrary?page=1&limit=50&fields=game,purchase,memo"

例: ゲームを検索する

curl -X POST -H "Authorization: Bearer <APIキー>" \
  -H "Content-Type: application/json" \
  -d '{"query":"どらくえ5","limit":5}' \
  https://game.retrogather.com/rest/v1/searchGames

結果の各ゲームは gameId を持ちます。追加や更新ではこの gameId を使います。

例: マイライブラリに追加する

curl -X POST -H "Authorization: Bearer <APIキー>" \
  -H "Content-Type: application/json" \
  -d '{"gameId":1234,"buyDate":"2026-09-20","buyPrice":1500,"buyPlace":"近所の中古ショップ"}' \
  https://game.retrogather.com/rest/v1/addToLibrary

ウィッシュリストにあるゲームを追加すると、ウィッシュリストから外れます。

例: マイコレクションのゲームを置き換える

集合を置き換える操作では、読み取り時の revision を送ります。

{
  "collectionId": "対象のID",
  "gameIds": [1010001, 1010002],
  "revision": "getCollections で取得した値"
}

POST /rest/v1/updateCollection の本文の例です。revision が合わない場合は拒否されるので、取得し直してから組み立て直してください。

例: 削除する

削除は 2 回の呼び出しで実行します。

1 回目は何も変更せず、確認の情報を返します。

curl -X POST -H "Authorization: Bearer <APIキー>" \
  -H "Content-Type: application/json" \
  -d '{"gameId":1234}' \
  https://game.retrogather.com/rest/v1/removeFromWishlist

応答の summary に削除する対象と影響、confirmToken に確認用のトークンが入ります。利用者の同意を得たら、同じ引数に confirmToken を加えて送ります。

curl -X POST -H "Authorization: Bearer <APIキー>" \
  -H "Content-Type: application/json" \
  -d '{"gameId":1234,"confirmToken":"1回目の応答の値"}' \
  https://game.retrogather.com/rest/v1/removeFromWishlist

削除の権限は、APIキーの発行時に「個別に設定」で選んだ場合だけ付きます。

MCP との違い

項目	REST API
応答	`structuredContent` と同じ内容を JSON の本文で返す。ゲームの情報の値が無い項目は、省略せず `null` で返す
外部リンク	完成した URL ではなく、外部サービスの ID で返す。専門 wiki などのリンクは返さない。IGDB の ID はIGDB の識別子を参照
`getGamesBatch`	`gameIds` は 1 回 100 件まで（MCP は 20 件）。MCP と上限が違うのはこの引数だけで、ゲームタグ・マイコレクションの `gameIds` / `excludeGameIds` は MCP と同じ上限（マイコレクションは 1,000 件、ゲームタグは 1 タグ 1,000 件）
`limit`	1 未満や整数以外は 400。1,000 を超える値は 1,000 に丸め、さらにツールごとの上限を適用する
ファイル出力	`exportMyData`・`exportMasterData` は REST API だけで使える。MCP のツール一覧には出ない

IGDB の識別子

ゲームの応答（マイライブラリなどの一覧に含まれるゲームも）には、igdbId に加えて igdbSlug と igdbCoverId が入ります。この 2 つは fields の指定に関係なく常に返し、値が無い場合は null です。カスタムゲームの igdbSlug は常に null です。MCP はこれらの ID を返さず、完成した URL（externalLinks）だけを返します。

項目	URL の組み立て方
`igdbSlug`	IGDB のゲームページ `https://www.igdb.com/games/{igdbSlug}`
`igdbCoverId`	IGDB の表紙画像 `https://images.igdb.com/igdb/image/upload/t_cover_big/{igdbCoverId}.jpg`

IGDB のページと画像には、IGDB の規約が適用されます。

エラー

入口のエラー（認証・経路）は error キー、ツールのエラーは code と message を持つ JSON を返します。

状況	HTTP
認証に失敗した	401
権限またはプランが足りない	403
対象やツールが無い	404
すでに登録されている	409
`revision` が合わない（競合）	409
入力が不正	400
本文が JSON として読めない	400
利用上限に達した	429
一時的に利用できない	503
想定外のエラー	500

409 は登録済み（already_exists）と競合（revision_conflict）の両方で返ります。HTTP ステータスだけで判断せず、code で区別してください。競合の場合は最新の状態を取得し直し、更新内容を組み直してから送ります
削除の確認中に対象が変わった場合は、エラーではなく新しい確認（confirmToken）を返します
429 と 503 では Retry-After に従ってください
retryable が返る場合は、その値で再試行するかを判断します。retryable: true なら同じ呼び出しを再試行できます
500 のエラーは再試行しても直りません。問い合わせの際は requestId を添えてください

保存済みのエラー

saved: true を含むエラーは、保存は完了しています。同じ追加を送り直さず、返された ID や結果を使ってください。応答が失われた場合も、読み取りで状態を確かめてから再送するかを決めてください。詳しくはエラーの後の確認を参照してください。

ファイル出力

ファイル出力は REST API だけで使えます。MCP のツール一覧には含まれません。

ツール	内容	形式	プラン
`exportMyData`	自分のマイライブラリ・ウィッシュリスト・プレイ記録などの一覧	CSV / JSON	全プラン
`exportMasterData`	ゲームマスタ（プラットフォーム別のゲーム、プラットフォーム、発売元、ジャンル）	NDJSON	プレミアム

どちらもファイルの本文ではなく、ダウンロード用の URL を返します。

URL の有効期限は 15 分です
期限内は、URL を持っていれば誰でもダウンロードできます。 URL を共有しないでください
ダウンロードも利用上限を消費します。本文を返せなかった場合は、消費した分を戻します
実際の列は、応答の columns で確認してください。値が無い列は null です

アプリのゲーム検索から出力する「ゲーム一覧のエクスポート」（CSV / JSON）とは別の機能です。

exportMyData

dataset で出力するデータの種類を選びます。種類によって必要なプランが違います（ゲームタグとゲーム機はライト以上、マイコレクションとカスタムゲームはプレミアム）。マイライブラリ・ウィッシュリスト・プレイ記録・マイコレクション・ゲーム機は、対応する一覧のツールと同じ条件と並び順を指定できます。

exportMasterData

dataset（必須）で対象を選びます。本文はすべて NDJSON です。

`dataset`	内容	並び順
`games`	`platformId` で指定した 1 つのプラットフォームのゲーム（自分のカスタムゲームを含む）	発売日の昇順（同じ日は `gameId` 順）
`platforms`	すべてのプラットフォーム	`platformId` 順
`companies`	すべての発売元	`companyId` 順
`genres`	主ジャンルのすべて	`genreId` 順

games では platformId が必須です。指定できるのは公式のプラットフォームだけで、カスタムプラットフォームは not_found になります。カスタムゲームは exportMyData の customGames で出力します
games 以外の dataset では、platformId を受け付けません
ゲームの行は、プラットフォーム・ジャンル・発売元を ID（platformId・genreId・publisherId）と名前の両方で持ちます。ID で platforms・genres・companies のファイルと突き合わせられます
ゲームの行には、JAN コードと外部サービスの ID（mediaId・gpsId・igdbId・igdbSlug・igdbCoverId）が入ります
genres は主ジャンルだけです。ゲームの genreId は主ジャンルを指します
platforms・companies には、プレミアムプランで登録した自分のカスタムプラットフォーム・カスタム発売元が custom: true で入ります
ゲームのダウンロードは、platforms・companies・genres のダウンロードより多く利用上限を消費します

応答は url・dataset・generation・totalCount・expiresInSec・expiresAt・columns です（games は platformId も）。generation はデータの世代で、前回の応答と同じなら取り直す必要はありません。

利用条件

取得したデータは、アプリ・ツール・サイトへの組み込みを含めて会員本人が利用できます。組み込む場合は、データの出典が Retro Game Gather であることを明示してください。ダウンロードしたファイルそのもの、またはそれと実質的に同じ一覧を配布・公開することは、出典を明記した場合も含めて禁止しています。この条件の対象は Retro Game Gather が提供するゲームデータで、自分で登録した記録とカスタムデータは対象になりません。スクレイピングや大量取得、利用上限を回避する行為は利用停止の対象です。

条件の全体はMCP / API の仕様の利用条件と利用規約を参照してください。