HTTP連携 API リファレンス

セットアップ

1. 設定 → HTTP連携タブを開く
2. 受信サーバー / 送信サーバーをそれぞれ有効にする
3. 必要に応じてポートを変更（デフォルト: 受信 11020 / 送信 11021）
4. 「認証・アクセス制御」から認証トークンをコピーし、外部ツールに設定する

両サーバーは 127.0.0.1 のみバインド（ローカルアクセスのみ）。すべてのリクエストにBearerトークン認証が必須です（下記「認証」を参照）。

---

認証

ローカルHTTPサーバーへのすべてのリクエストは、Bearerトークンによる認証が必須です。トークンの無いリクエスト、または一致しないリクエストは 401 Unauthorized で拒否されます。

• トークンはアプリの 設定 → HTTP連携 → 認証・アクセス制御 で表示・コピー・再生成できます
• 外部ツールからのリクエストに Authorization: Bearer <トークン> ヘッダを付与します
• トークンは第三者へ共有しないでください。再生成した場合は外部ツール側の設定も更新が必要です

コピーしたトークンを環境変数に入れて使う例:

TOKEN="＜設定画面でコピーしたトークン＞"

curl http://127.0.0.1:11021/api/groups \
  -H "Authorization: Bearer $TOKEN"

注意: 以降の curl 例では簡潔さのため Authorization ヘッダを省略しています。実際にはすべてのリクエストに付与してください。

ブラウザ上のページから利用する場合

ブラウザ上のWebページ（JavaScript）から呼び出す場合のみ、そのページのオリジン（例 http://localhost:3000）を設定の「許可するオリジン」に追加してください。ブラウザ以外の外部ツール（OBS・Bot・スクリプト等）はオリジンの登録は不要で、トークンのみで動作します。

---

送信サーバー（データ取得）

デフォルトポート: 11021

外部ツールがVRCPersonaのデータをGETで取得します。データは5秒間隔で更新されます。

User-Agentヘッダ（必須）

送信サーバーのデータ取得エンドポイント（/api/groups / /api/friends / /api/notifications）へのリクエストには、空でない User-Agent ヘッダが必須です。ヘッダが無い、または空のリクエストは 400 Bad Request で拒否されます（/api/health は疎通確認用のため対象外）。受信サーバー（11020）ではUser-Agentは不要です。

指定したUser-Agentは、VRCPersonaがあなたに代わってVRChat APIへ問い合わせる際に、VRCPersona/<バージョン> (via HTTP API; <あなたのUA>) … の形でVRChatへ伝えられます。これは「VRCPersona経由の、どの外部ツールからのアクセスか」をVRChat側に明示するためのものです。ツール名とバージョンがわかる値（例 MyOverlay/1.0）を設定してください。

curl をはじめ多くのHTTPクライアントは既定でUser-Agentを送信するため、追加の設定なしで動作します。ブラウザの fetch や独自クライアント等でUser-Agentを送らない場合のみ、明示的に付与してください。

curl http://127.0.0.1:11021/api/friends \
  -H "Authorization: Bearer $TOKEN" \
  -H "User-Agent: MyOverlay/1.0"

GET /api/groups

グループ一覧を取得（サーバーグループ + ローカルグループ）。

curl http://127.0.0.1:11021/api/groups

レスポンス例:

[
  {
    "id": "d7569eaf-9673-4d5b-922e-5d868a048593",
    "name": "お気に入り",
    "color": "#1e65d3",
    "icon": null,
    "storage": "server",
    "statusColor": "blue",
    "statusMessage": "だれでもおいで",
    "memberIds": ["usr_xxx", "usr_yyy"]
  },
  {
    "id": "local_0211fdf8-dbea-4f3b-a5b3-caca9d2c1d80",
    "name": "ローカルグループ",
    "color": "#c43fe0",
    "icon": null,
    "storage": "local",
    "statusColor": null,
    "statusMessage": null,
    "memberIds": ["usr_aaa", "usr_bbb"]
  }
]

GET /api/friends

フレンド一覧を取得。

curl http://127.0.0.1:11021/api/friends

レスポンス例:

[
  {
    "id": "usr_xxx",
    "displayName": "ユーザー名",
    "status": "green",
    "statusDescription": "遊んでるよ",
    "location": "wrld_xxx:12345~friends(usr_yyy)~region(jp)",
    "groups": ["d7569eaf-..."],
    "priority": 3.1,
    "platform": "standalonewindows",
    "avatarThumbnail": "https://...",
    "userIcon": null,
    "minutesAtLocation": 42,
    "instanceInfo": {
      "worldId": "wrld_xxx",
      "worldName": "My World",
      "instanceId": "12345~friends(usr_yyy)~region(jp)",
      "userCount": 8,
      "capacity": 32,
      "instanceType": "フレンド",
      "region": "jp"
    }
  }
]

instanceInfo

オプション情報（?include= クエリパラメータ）

?include= でカンマ区切りの値を指定すると、各フレンドに追加情報が付与されます。

curl "http://127.0.0.1:11021/api/friends?include=groups"
curl "http://127.0.0.1:11021/api/friends?include=raw,groups,me"
curl "http://127.0.0.1:11021/api/friends?include=groups&fresh=true"

?fresh=true: キャッシュを無視してVRChat APIから最新情報を取得します。省略時はキャッシュ利用（7日間有効）。

注意: include を指定すると、各フレンドのVRChat APIへの問い合わせが発生するため、レスポンスに時間がかかる場合があります。キャッシュヒット時は即応答。

GET /api/notifications

VRChat通知一覧を取得。

curl http://127.0.0.1:11021/api/notifications

レスポンス例:

[
  {
    "id": "not_xxx",
    "type": "invite",
    "senderUserId": "usr_xxx",
    "senderUsername": "ユーザー名",
    "message": "",
    "details": {
      "worldId": "wrld_xxx",
      "worldName": "ワールド名",
      "inviteMessage": "遊びにおいでよ！"
    },
    "created_at": "2026-03-20T17:52:28.263Z",
    "seen": false
  }
]

GET /api/health

サーバーの稼働確認。

curl http://127.0.0.1:11021/api/health

レスポンス:

{"status": "ok"}

---

受信サーバー（ステータス変更）

デフォルトポート: 11020

外部ツールからVRCPersonaのグループステータスを変更します。

PUT /api/groups/:groupId/status

グループステータス（カラー・メッセージ）を変更。

curl -X PUT http://127.0.0.1:11020/api/groups/{groupId}/status \
  -H "Content-Type: application/json" \
  -d '{"status_color":"blue","status_message":"配信中"}'

リクエストボディ:

レスポンス: 202 Accepted

{"ok": true}

変更はVRCPersonaサーバーに非同期で反映されます。

ステータスを解除する例:

curl -X PUT http://127.0.0.1:11020/api/groups/{groupId}/status \
  -H "Content-Type: application/json" \
  -d '{"status_color":null,"status_message":null}'

GET /api/health

curl http://127.0.0.1:11020/api/health

---

注意事項

• すべてのリクエストに認証トークンが必須（未設定・不一致は 401）。トークンはアプリの「設定 → HTTP連携 → 認証・アクセス制御」で管理
• 送信サーバーのデータ取得エンドポイント（/api/groups・/api/friends・/api/notifications）は User-Agent ヘッダも必須（空・無しは 400／/api/health と受信サーバーは対象外）。指定値はVRChatへの問い合わせ時に経由元として伝えられる（詳細）
• groupId は送信サーバーの GET /api/groups で取得できる id フィールドを使用
• ステータス変更はサーバーグループのみ有効（ローカルグループはステータス共有非対応）
• 送信サーバーのデータは5秒間隔で更新されるため、最大5秒の遅延がある
• 有料プランが無効になるとサーバーは自動停止する
• ポートが他のアプリと競合する場合は設定画面で変更可能（1024〜65535）