API ドキュメント

Minefolio が提供する公開 API の仕様書です。認証なしで利用可能なエンドポイントを掲載しています。

注意: 認証必須の API（/api/me/*、/api/auth/* 等）はこのページには掲載していません。これらは Minefolio 内部からのみ利用される想定です。

エンドポイント一覧

GET /api/skin

Minecraft スキン画像を返す。

パラメータ:

取得優先順位:

1. DB のカスタムスキン URL（userId 指定時）
2. Mojang API（UUID 経由）
3. Steve デフォルトスキン

レスポンス: image/png（バイナリ）

キャッシュ: Cache-Control: public, max-age=3600（1時間）

GET /api/cape

Mojang のマント画像を返す。

パラメータ:

レスポンス: image/png（バイナリ）。マントが無い場合は 404、Mojang 側の失敗は 502

キャッシュ: Cache-Control: public, max-age=3600（1時間。502 のみ短時間）

GET /api/guides/search

公開ガイドをタイトルで検索する（部分一致）。

パラメータ:

件数を指定するパラメータはありません。

レスポンス:

{
  "guides": [
    {
      "id": "...",
      "title": "...",
      "slug": "...",
      "summary": "...",
      "coverImageUrl": "...",
      "authorSlug": "...",
      "authorName": "...",
      "url": "/guides/{authorSlug}/{slug}"
    }
  ]
}

• 検索対象は title のみです（summary は検索対象ではなく、レスポンスに含まれるだけです）。
• 公開済みで、かつ著者のプロフィールが公開のガイドのみ対象です。
• 更新日時の新しい順に最大 10 件を返します。
• q が未指定または空の場合は、エラーにせず { "guides": [] } を返します。

GET /api/favorites

お気に入り一覧（slug 配列）を取得する。

未認証ユーザーは空配列を返す。認証済みユーザーは DB に保存された自分のお気に入りを返す。

レスポンス:

{ "favorites": ["slug1", "slug2"] }

旧 minefolio_favorites Cookie が残っていれば自動削除される（Set-Cookie: ... Max-Age=0）。

POST /api/favorites

お気に入りを追加・削除する。認証必須。

リクエストボディ（JSON）:

{ "slug": "playerSlug", "action": "add" }

レスポンス: 更新後のお気に入り一覧

{ "favorites": ["slug1", "slug2"] }

PUT /api/favorites

ブラウザに保存されていたお気に入り（localStorage 等）を DB に一括同期する用途。認証必須。重複は無視。

リクエストボディ（JSON）:

{ "slugs": ["slug1", "slug2"] }

レスポンス: 同期後のお気に入り一覧（POST と同形式）

POST /api/likes

ガイド・サーチクラフトテンプレートへの「いいね」を追加・解除する。認証必須。

リクエストボディ:

{ "targetType": "guide", "targetId": "<id>", "action": "like" }

• targetType: guide または template
• targetId: ガイド／テンプレートの ID（スラッグではない）
• action: like（いいねする）または unlike（解除）。絶対指定なので再送しても状態がずれない

レスポンス:

{ "liked": true, "count": 3 }

エラー: 400（リクエスト不正）/ 401（未ログイン）/ 403（自分の投稿）/ 404（対象なし・未公開・著者が非公開）/ 405（POST以外）

POST /api/users/by-slugs

スラッグ配列から複数ユーザーの基本情報を取得する。最大 100 件。

リクエストボディ（JSON）:

{ "slugs": ["slug1", "slug2"] }

レスポンス:

{
  "users": [
    {
      "slug": "...",
      "mcid": "...",
      "uuid": "...",
      "displayName": "...",
      "displayNameAlphabet": "...",
      "pronouns": "...",
      "role": "runner",
      "mainEdition": "java",
      "mainPlatform": "pc_windows",
      "shortBio": "...",
      "location": "...",
      "updatedAt": "...",
      "customSkinUrl": "...",
      "slimSkin": false
    }
  ]
}

入力された slugs の順序を維持して返す。

GET /api/home-feed

ホーム画面のフィードデータを取得する。複数の種別がクエリパラメータで指定できる。

パラメータ:

レスポンス例（type=live-runs）:

{
  "liveRuns": [...],
  "mcidToUuid": { "...": "..." },
  "mcidToSkinUrl": { "...": "..." }
}

CDN キャッシュ付き（種別ごとに 30秒〜30分、stale-while-revalidate あり）。並び順は新しい順で、ユーザーに依存しない。視聴者ロールのユーザーは含まれない。

GET /api/keybindings-csv

公開プロフィールに設定が登録されているユーザーのデータを CSV 形式でダウンロードする。認証は不要。

パラメータ:

レスポンス: text/csv（ブラウザがダウンロード、UTF-8 BOM 付き）。パラメータが不正な場合は 400（application/json、{ "error": "..." }）

選択したセクションごとに CSV を生成し、空行を挟んで結合する。remaps セクションの末尾には Type 列（リマップ種別: all / trigger / chat、未設定は空欄）が含まれる。

エラー（400）:

• sections が空（sections= など）、または上記以外のセクション名を含む
• userSlugs が空（userSlugs= など）、または次のいずれかに当たる slug を含む: 存在しない／非公開／視聴者ロール／設定が空。どれに当たるかは区別しない。見つからなかった slug は notFound 配列で返す

{ "error": "Some userSlugs were not found or are not exportable", "notFound": ["ghost"] }

POST /api/set-locale

表示言語を切り替える。

リクエストボディ（FormData）:

レスポンス: Set-Cookie で言語設定を保存し、リファラーへリダイレクト。

利用上の注意

• 各エンドポイントは予告なく仕様変更される可能性があります。
• レート制限は明示的には設けていませんが、過剰なリクエストは控えてください。
• 不具合や仕様への要望は GitHub Issue または フィードバックフォーム からお知らせください。