HTTP連携 API リファレンス

VRCPersonaのデータを外部ツール（OBS、オーバーレイ、Bot等）から読み書きするためのローカルHTTP APIです。

有料プラン限定機能

セットアップ

  1. 設定 → HTTPタブを開く
  2. 受信サーバー / 送信サーバーをそれぞれ有効にする
  3. 必要に応じてポートを変更（デフォルト: 受信 11020 / 送信 11021）

両サーバーは 127.0.0.1 のみバインド（ローカルアクセスのみ）。

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

デフォルトポート: 11021

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

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"]
  }
]
フィールド型説明
idstringグループID
namestringグループ名
colorstring | nullグループカラー（HEX）
iconstring | nullグループアイコン
storagestring | null"server" or "local"
statusColorstring | null自分が設定したステータスカラー（blue / green / orange / red / null）
statusMessagestring | null自分が設定したステータスメッセージ
memberIdsstring[]メンバーのVRChat User ID一覧

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"
    }
  }
]
フィールド型説明
idstringVRChat User ID
displayNamestring表示名
statusstringVRChatステータス（blue / green / orange / red）
statusDescriptionstring | nullステータスメッセージ
locationstring | null現在のlocation（wrld_xxx:instanceId 形式）
groupsstring[]所属グループID一覧
prioritynumberソート優先度（小さいほど上位）
platformstring | nullプラットフォーム（standalonewindows / android / web 等）
avatarThumbnailstring | nullアバターサムネイルURL
userIconstring | nullユーザーアイコンURL（?include=raw で取得時に自動反映）
minutesAtLocationnumber | null現在のインスタンスに滞在している分数
instanceInfoobject | nullインスタンス詳細情報（下記参照）

instanceInfo

フィールド型説明
worldIdstringワールドID
worldNamestringワールド名
instanceIdstringインスタンスID
userCountnumber | null現在の人数
capacitynumber | null定員
instanceTypestringインスタンスタイプ（パブリック / フレンド / フレンド+ 等）
regionstring | nullリージョン（jp / us / eu 等）

オプション情報（?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"
include値追加フィールド説明
rawrawUserVRChatユーザー詳細の全JSON（bio, tags, dateJoined 等）
groupsvrchatGroupIdsそのユーザーが所属するVRChatグループIDの配列
worldsuserWorldIdsそのユーザーが作成したワールドIDの配列
mutualsmutualFriends共通のフレンド一覧
me配列先頭に自分を追加"isMe": true フラグ付き、基本フィールド（displayName等）も含む

?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":"配信中"}'

リクエストボディ:

フィールド型説明
status_colorstring | null"blue" / "green" / "orange" / "red" / null（解除）
status_messagestring | nullステータスメッセージ（省略可）

レスポンス: 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

注意事項