Public API v1

外部開発者が API キーを使って XRift のデータにアクセスするための Public API リファレンスです。

ベース URL: https://api.xrift.net/api/public/v1

認証

2 種類の認証方式をサポートしています。リクエスト時に Authorization ヘッダーでトークンを送信してください。

認証方式	ヘッダー	用途
API キー	`Authorization: Bearer xrift_sk_xxx`	サードパーティ開発者向け（スコープ + レート制限あり）
CLI トークン	`Authorization: Bearer xrf_xxx`	CLI / 内部ツール向け（全権限、レート制限なし）

API キーは XRift の設定画面から取得できます。

API キーは xrift_sk_ プレフィックスで識別されます
CLI トークンは xrf_ プレフィックスで識別されます
いずれの形式にも該当しないトークンは 401 エラーになります

スコープ

API キー認証ではスコープによるアクセス制御が行われます。必要なスコープが不足している場合は 403 エラーが返されます。

スコープ	アクセス対象
`read:worlds`	ワールド一覧・検索・詳細・人気ランキング・統計・ユーザーの公開ワールド
`read:users`	ユーザー公開プロフィール・ユーザー検索
`read:instances`	インスタンス一覧・詳細・ワールドのインスタンス

ヒント

CLI トークンはスコープチェックをスキップし、全エンドポイントにアクセスできます。

エンドポイント

GET /worlds

ワールド一覧を取得します（ページネーション付き）。

スコープ: read:worlds

パラメータ

パラメータ	型	デフォルト	説明
`limit`	number	20	取得件数（最大 50）
`offset`	number	0	オフセット

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/worlds?limit=10&offset=0"

レスポンス例

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "My World",
      "description": "サンプルワールド",
      "ownerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "isPublic": true,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 10,
    "offset": 0
  }
}

GET /worlds/search

ワールドをキーワードで検索します。

スコープ: read:worlds

パラメータ

パラメータ	型	必須	デフォルト	説明
`q`	string	必須	-	検索キーワード
`limit`	number	-	20	取得件数（最大 50）
`offset`	number	-	0	オフセット

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/worlds/search?q=tokyo&limit=5"

レスポンス例

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Tokyo Tower World",
      "description": "東京タワーを再現したワールド"
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 5,
    "offset": 0
  }
}

エラー

ステータス	条件	レスポンス
400	`q` パラメータが未指定	`{ "error": "Query parameter \"q\" is required" }`

GET /worlds/popular

人気ワールドランキングを取得します。

スコープ: read:worlds

パラメータ

パラメータ	型	デフォルト	説明
`period`	string	`all`	集計期間（`all` / `week` / `month`）
`limit`	number	20	取得件数（最大 50）
`offset`	number	0	オフセット

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/worlds/popular?period=week&limit=10"

レスポンス例

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Popular World",
      "description": "人気のワールド",
      "ownerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "isPublic": true,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 10,
    "offset": 0
  },
  "period": "week"
}

GET /worlds/:id

指定した ID のワールド詳細を取得します。

スコープ: read:worlds

パスパラメータ

パラメータ	型	説明
`id`	string	ワールド ID

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/worlds/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

レスポンス例

{
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "My World",
    "description": "サンプルワールド",
    "ownerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "isPublic": true,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

エラー

ステータス	条件	レスポンス
404	ワールドが存在しない	`{ "error": "World not found" }`

GET /worlds/:id/stats

指定したワールドの公開統計情報を取得します。

スコープ: read:worlds

パスパラメータ

パラメータ	型	説明
`id`	string	ワールド ID

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/worlds/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/stats"

レスポンス例

{
  "data": {
    "worldId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "totalVisits": 12345,
    "uniqueVisitors": 6789,
    "visitsLast7Days": 234,
    "visitsLast30Days": 890
  }
}

注記

日別の訪問数（dailyVisits）は非公開です。

エラー

ステータス	条件	レスポンス
404	ワールドが存在しない	`{ "error": "World not found" }`

GET /worlds/:id/instances

指定したワールドのインスタンス一覧を取得します。公開インスタンスのみ返却されます。

スコープ: read:instances

パスパラメータ

パラメータ	型	説明
`id`	string	ワールド ID

パラメータ

パラメータ	型	デフォルト	説明
`limit`	number	20	取得件数（最大 50）
`offset`	number	0	オフセット

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/worlds/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/instances?limit=10"

レスポンス例

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "worldId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 10,
    "offset": 0
  }
}

エラー

ステータス	条件	レスポンス
404	ワールドが存在しない	`{ "error": "World not found" }`

GET /users/search

ユーザーを表示名で検索します。

スコープ: read:users

パラメータ

パラメータ	型	必須	デフォルト	説明
`q`	string	必須	-	検索キーワード（displayName の部分一致）
`limit`	number	-	20	取得件数（最大 50）
`offset`	number	-	0	オフセット

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/users/search?q=sawa&limit=10"

レスポンス例

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "displayName": "sawa-zen",
      "userIconUrl": "https://example.com/avatar.png",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

エラー

ステータス	条件	レスポンス
400	`q` パラメータが未指定	`{ "error": "Query parameter \"q\" is required" }`

GET /users/:id

指定した ID のユーザー公開プロフィールを取得します。

スコープ: read:users

パスパラメータ

パラメータ	型	説明
`id`	string	ユーザー ID

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

レスポンス例

{
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "displayName": "sawa-zen",
    "userIconUrl": "https://example.com/avatar.png",
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
}

エラー

ステータス	条件	レスポンス
404	ユーザーが存在しない	`{ "error": "User not found" }`

GET /users/:id/worlds

指定したユーザーの公開ワールド一覧を取得します。公開かつ ACTIVE なワールドのみ返却されます。

スコープ: read:worlds

パスパラメータ

パラメータ	型	説明
`id`	string	ユーザー ID

パラメータ

パラメータ	型	デフォルト	説明
`limit`	number	20	取得件数（最大 50）
`offset`	number	0	オフセット

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/worlds?limit=10"

レスポンス例

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "My World",
      "description": "サンプルワールド",
      "ownerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "isPublic": true,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 10,
    "offset": 0
  }
}

エラー

ステータス	条件	レスポンス
404	ユーザーが存在しない	`{ "error": "User not found" }`

GET /instances

アクティブなインスタンス一覧を取得します（ページネーション付き）。

スコープ: read:instances

パラメータ

パラメータ	型	必須	デフォルト	説明
`worldId`	string	-	-	指定したワールドのインスタンスのみ取得
`limit`	number	-	20	取得件数（最大 50）
`offset`	number	-	0	オフセット

リクエスト例

# 全インスタンス一覧
curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/instances"

# 特定ワールドのインスタンスのみ
curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/instances?worldId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

レスポンス例

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "worldId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0
  }
}

GET /instances/:id

指定した ID のインスタンス詳細を取得します。

スコープ: read:instances

パスパラメータ

パラメータ	型	説明
`id`	string	インスタンス ID

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/instances/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

レスポンス例

{
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "worldId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
}

エラー

ステータス	条件	レスポンス
404	インスタンスが存在しない	`{ "error": "Instance not found" }`

GET /stats

プラットフォーム全体の統計情報を取得します。

スコープ: なし（認証のみ必要、どの API キーでもアクセス可能）

リクエスト例

curl -H "Authorization: Bearer xrift_sk_xxx" \
  "https://api.xrift.net/api/public/v1/stats"

レスポンス例

{
  "data": {
    "totalUsers": 15000,
    "totalPublicWorlds": 3200,
    "totalPublicInstances": 850
  }
}

共通エラーレスポンス

全エンドポイント共通で返される可能性のあるエラーです。

ステータス	意味	レスポンス例
401	認証ヘッダーが未指定	`{ "error": "Authentication required" }`
401	トークン形式が不正	`{ "error": "Invalid token format" }`
401	API キーが無効	`{ "error": "Invalid API key" }`
401	API キーが無効化済み	`{ "error": "API key is deactivated" }`
401	API キーが期限切れ	`{ "error": "API key has expired" }`
401	CLI トークンが無効	`{ "error": "Invalid CLI token" }`
401	CLI トークンが期限切れ	`{ "error": "CLI token has expired" }`
403	スコープ不足	`{ "error": "Insufficient scope. Required: read:worlds" }`
429	レート制限超過	`{ "error": "Rate limit exceeded" }`

レート制限

1 時間あたり 1,000 リクエスト（デフォルト）
API キー認証のみ適用（CLI トークンは対象外）
固定ウィンドウ方式で計算されます

レスポンスヘッダーで現在の使用状況を確認できます（API キー認証時のみ付与）。

ヘッダー	説明
`X-RateLimit-Limit`	上限
`X-RateLimit-Remaining`	残り回数
`X-RateLimit-Reset`	リセット時刻（Unix timestamp）

注意

レート制限を超過すると 429 Too Many Requests が返されます。X-RateLimit-Reset ヘッダーの時刻まで待ってからリトライしてください。

認証​

スコープ​

エンドポイント​

GET /worlds​

パラメータ​

リクエスト例​

レスポンス例​

GET /worlds/search​

パラメータ​

リクエスト例​

レスポンス例​

エラー​

GET /worlds/popular​

パラメータ​

リクエスト例​

レスポンス例​

GET /worlds/:id​

パスパラメータ​

リクエスト例​

レスポンス例​

エラー​

GET /worlds/:id/stats​

パスパラメータ​

リクエスト例​

レスポンス例​

エラー​

GET /worlds/:id/instances​

パスパラメータ​

パラメータ​

リクエスト例​

レスポンス例​

エラー​

GET /users/search​

パラメータ​

リクエスト例​

レスポンス例​

エラー​

GET /users/:id​

パスパラメータ​

リクエスト例​

レスポンス例​

エラー​

GET /users/:id/worlds​

パスパラメータ​

パラメータ​

リクエスト例​

レスポンス例​

エラー​

GET /instances​

パラメータ​

リクエスト例​

レスポンス例​

GET /instances/:id​

パスパラメータ​

リクエスト例​

レスポンス例​

エラー​

GET /stats​

リクエスト例​

レスポンス例​

共通エラーレスポンス​

レート制限​

認証

スコープ

エンドポイント

GET /worlds

パラメータ

リクエスト例

レスポンス例

GET /worlds/search

パラメータ

リクエスト例

レスポンス例

エラー

GET /worlds/popular

パラメータ

リクエスト例

レスポンス例

GET /worlds/:id

パスパラメータ

リクエスト例

レスポンス例

エラー

GET /worlds/:id/stats

パスパラメータ

リクエスト例

レスポンス例

エラー

GET /worlds/:id/instances

パスパラメータ

パラメータ

リクエスト例

レスポンス例

エラー

GET /users/search

パラメータ

リクエスト例

レスポンス例

エラー

GET /users/:id

パスパラメータ

リクエスト例

レスポンス例

エラー

GET /users/:id/worlds

パスパラメータ

パラメータ

リクエスト例

レスポンス例

エラー

GET /instances

パラメータ

リクエスト例

レスポンス例

GET /instances/:id

パスパラメータ

リクエスト例

レスポンス例

エラー

GET /stats

リクエスト例

レスポンス例

共通エラーレスポンス

レート制限