Skip to main content

Public API v1

API reference for external developers to access XRift data using API keys.

Base URL: https://api.xrift.net/api/public/v1

Authentication​

Two authentication methods are supported. Send the token via the Authorization header.

MethodHeaderUse case
API KeyAuthorization: Bearer xrift_sk_xxxFor third-party developers (scoped + rate limited)
CLI TokenAuthorization: Bearer xrf_xxxFor CLI / internal tools (full access, no rate limit)

You can obtain an API key from the XRift settings page.

  • API keys are identified by the xrift_sk_ prefix
  • CLI tokens are identified by the xrf_ prefix
  • Tokens that don't match either format will return a 401 error

Scopes​

API key authentication uses scope-based access control. If the required scope is missing, a 403 error is returned.

ScopeAccess
read:worldsWorld list, search, details, popular ranking, stats, and user's public worlds
read:usersUser public profile and user search
read:instancesInstance list, details, and world instances
read:marketplaceMarketplace listings: list, search, and details
read:eventsEvent list and details
tip

CLI tokens skip scope checks and have access to all endpoints.

Endpoints​

GET /worlds​

List worlds with pagination.

  • Scope: read:worlds

Parameters​

ParameterTypeDefaultDescription
limitnumber20Number of items (max 50)
offsetnumber0Offset

Request example​

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

Response example​

{
"data": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "My World",
"description": "A sample world",
"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​

Search worlds by keyword.

  • Scope: read:worlds

Parameters​

ParameterTypeRequiredDefaultDescription
qstringRequired-Search keyword
limitnumber-20Number of items (max 50)
offsetnumber-0Offset

Request example​

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

Response example​

{
"data": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Tokyo Tower World",
"description": "A world recreating Tokyo Tower"
}
],
"pagination": {
"total": 3,
"limit": 5,
"offset": 0
}
}

Errors​

StatusConditionResponse
400q parameter is missing{ "error": "Query parameter \"q\" is required" }

GET /worlds/popular​

Get popular world rankings.

  • Scope: read:worlds

Parameters​

ParameterTypeDefaultDescription
periodstringallRanking period (all / week / month)
limitnumber20Number of items (max 50)
offsetnumber0Offset

Request example​

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

Response example​

{
"data": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Popular World",
"description": "A popular world",
"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​

Get world details by ID.

  • Scope: read:worlds

Path parameters​

ParameterTypeDescription
idstringWorld ID

Request example​

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

Response example​

{
"data": {
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "My World",
"description": "A sample world",
"ownerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"isPublic": true,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
}

Errors​

StatusConditionResponse
404World does not exist{ "error": "World not found" }

GET /worlds/:id/stats​

Get public statistics for a specific world.

  • Scope: read:worlds

Path parameters​

ParameterTypeDescription
idstringWorld ID

Request example​

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

Response example​

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

Daily visit details (dailyVisits) are not publicly available.

Errors​

StatusConditionResponse
404World does not exist{ "error": "World not found" }

GET /worlds/:id/instances​

List instances for a specific world. Only public instances are returned.

  • Scope: read:instances

Path parameters​

ParameterTypeDescription
idstringWorld ID

Parameters​

ParameterTypeDefaultDescription
limitnumber20Number of items (max 50)
offsetnumber0Offset

Request example​

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

Response example​

{
"data": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"worldId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"currentUsers": 8,
"maxCapacity": 20,
"participants": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"displayName": "sawa-zen",
"userIconUrl": null
}
],
"createdAt": "2026-01-01T00:00:00.000Z"
}
],
"pagination": {
"total": 3,
"limit": 10,
"offset": 0
}
}

People counts work the same as in GET /instances: use currentUsers, and don't count participants.

Errors​

StatusConditionResponse
404World does not exist{ "error": "World not found" }

GET /users/search​

Search users by display name.

  • Scope: read:users

Parameters​

ParameterTypeRequiredDefaultDescription
qstringRequired-Search keyword (partial match on displayName)
limitnumber-20Number of items (max 50)
offsetnumber-0Offset

Request example​

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

Response example​

{
"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
}
}

Errors​

StatusConditionResponse
400q parameter is missing{ "error": "Query parameter \"q\" is required" }

GET /users/:id​

Get a user's public profile by ID.

  • Scope: read:users

Path parameters​

ParameterTypeDescription
idstringUser ID

Request example​

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

Response example​

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

Errors​

StatusConditionResponse
404User does not exist{ "error": "User not found" }

GET /users/:id/worlds​

List a user's public worlds. Only public and ACTIVE worlds are returned.

  • Scope: read:worlds

Path parameters​

ParameterTypeDescription
idstringUser ID

Parameters​

ParameterTypeDefaultDescription
limitnumber20Number of items (max 50)
offsetnumber0Offset

Request example​

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

Response example​

{
"data": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "My World",
"description": "A sample world",
"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
}
}

Errors​

StatusConditionResponse
404User does not exist{ "error": "User not found" }

GET /instances​

List active instances with pagination.

  • Scope: read:instances

Parameters​

ParameterTypeRequiredDefaultDescription
worldIdstring--Filter instances by world
limitnumber-20Number of items (max 50)
offsetnumber-0Offset

Request examples​

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

# Instances for a specific world
curl -H "Authorization: Bearer xrift_sk_xxx" \
"https://api.xrift.net/api/public/v1/instances?worldId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Response example​

{
"data": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"worldId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"currentUsers": 8,
"maxCapacity": 20,
"participants": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"displayName": "sawa-zen",
"userIconUrl": null
}
],
"createdAt": "2026-01-01T00:00:00.000Z"
}
],
"pagination": {
"total": 5,
"limit": 20,
"offset": 0
}
}
note

Use currentUsers for the number of people in the instance and maxCapacity for its capacity. participants is for display, such as showing a row of icons: it holds at most the first 5 registered users and never includes guests. Its length can differ from the number of people in the instance.


GET /instances/:id​

Get instance details by ID.

An instance is deleted automatically 5 minutes after everyone leaves, so a stored ID may later return 404. Only XRift Plus persistent instances stay.

  • Scope: read:instances

Path parameters​

ParameterTypeDescription
idstringInstance ID

Request example​

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

Response example​

{
"data": {
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"worldId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"currentUsers": 8,
"maxCapacity": 20,
"participants": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"displayName": "sawa-zen",
"userIconUrl": null
}
],
"createdAt": "2026-01-01T00:00:00.000Z"
}
}

People counts work the same as in GET /instances: use currentUsers, and don't count participants.

Errors​

StatusConditionResponse
404Instance does not exist{ "error": "Instance not found" }

GET /marketplace/items​

Get the list of items listed on the marketplace. Only public items that have passed review are returned.

  • Scope: read:marketplace

Parameters​

ParameterTypeRequiredDefaultDescription
sortstring-popularSort order (popular: most acquired / newest: newest first / trending: recent momentum)
ownerIdstring--Only return listings by this user
limitnumber-20Number of results (1–50; values above 50 are treated as 50)
offsetnumber-0Offset (0 or greater)
note

With sort=trending, items that haven't been acquired recently are not included.

Request example​

# Most popular
curl -H "Authorization: Bearer xrift_sk_xxx" \
"https://api.xrift.net/api/public/v1/marketplace/items?limit=10"

# A specific user's listings, newest first
curl -H "Authorization: Bearer xrift_sk_xxx" \
"https://api.xrift.net/api/public/v1/marketplace/items?ownerId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&sort=newest"

Response example​

{
"data": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Picture Frame",
"description": "A frame for displaying photos",
"sceneUrl": "https://assets.xrift.net/.../remoteEntry.js",
"thumbnailUrl": "https://assets.xrift.net/.../thumbnail.png",
"githubUrl": null,
"fileSize": "1048576",
"status": "ACTIVE",
"securityScore": 0,
"isPublic": true,
"currentVersionNumber": 2,
"acquireCount": 42,
"permissions": {
"allowedDomains": [],
"allowedCodeRules": []
},
"owner": {
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"displayName": "sawa-zen",
"userIconUrl": "https://example.com/avatar.png"
},
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
],
"pagination": {
"total": 99,
"limit": 10,
"offset": 0
}
}
  • fileSize is the size in bytes, returned as a string

Errors​

The validation error messages for this endpoint are returned in Japanese.

StatusConditionResponse
400Invalid sort{ "error": "sort は popular、newest、trending のいずれかを指定してください" }
400Empty ownerId{ "error": "ownerId は空にできません" }
400limit / offset is not a decimal integer (1.5, 1e2, 0x10, etc.), or limit is 0{ "error": "limit は 1 以上の整数を指定してください" }
note

Passing the ID of a user who doesn't exist as ownerId is not an error; an empty list is returned.


GET /marketplace/items/search​

Search items listed on the marketplace by partial match on name, description, or creator name.

  • Scope: read:marketplace

Parameters​

ParameterTypeRequiredDefaultDescription
qstringRequired-Search keyword
sortstring-newestSort order (popular / newest / trending)
ownerIdstring--Only return listings by this user
limitnumber-20Number of results (1–50; values above 50 are treated as 50)
offsetnumber-0Offset (0 or greater)

Request example​

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

Response example​

Same shape as GET /marketplace/items.

Errors​

StatusConditionResponse
400q parameter is missing (including whitespace only){ "error": "Query parameter \"q\" is required" }
400Invalid sort / ownerId / limit / offsetSame as GET /marketplace/items

GET /marketplace/items/:id​

Get the details of the item with the specified ID.

  • Scope: read:marketplace

Path parameters​

ParameterTypeDescription
idstringItem ID

Request example​

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

Response example​

{
"data": {
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Picture Frame",
"description": "A frame for displaying photos",
"acquireCount": 42,
"owner": {
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"displayName": "sawa-zen"
}
}
}

(Some fields are omitted. See the GET /marketplace/items response example for all fields.)

Errors​

StatusConditionResponse
404Item doesn't exist, is private, or is under review{ "error": "Item not found" }
note

Private items and items under review return 404 even when requested with the owner's API key.


GET /events​

Get the list of events. Recurring events are expanded into each occurrence within the requested period.

  • Scope: read:events

Parameters​

ParameterTypeRequiredDefaultDescription
fromstringRequired-Start of the period (ISO 8601)
tostringRequired-End of the period (ISO 8601). Within 366 days of from
worldIdstring--Filter by venue world
instanceIdstring--Filter by instance
ownerIdstring--Filter by organizer
kindstring--scheduled / instant
statusstring--upcoming / live / ended / cancelled
orderstring-ascSort order by start time (asc / desc)
limitnumber-20Number of results (1–50; values above 50 are treated as 50)
offsetnumber-0Offset (0 or greater)

Request example​

curl -H "Authorization: Bearer xrift_sk_xxx" \
"https://api.xrift.net/api/public/v1/events?from=2026-12-01T00:00:00Z&to=2026-12-31T23:59:59Z&limit=10"

Response example​

{
"data": [
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx::2026-12-02T13:00:00.000Z",
"seriesId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"kind": "scheduled",
"status": "upcoming",
"title": "VR Catch-up",
"description": "A catch-up meetup every two weeks",
"thumbnailUrl": null,
"worldId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"currentUsers": 0,
"instanceId": null,
"startAt": "2026-12-02T13:00:00.000Z",
"endAt": "2026-12-02T14:00:00.000Z",
"repeatFrequency": "biweekly",
"owner": {
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"displayName": "sawa-zen",
"userIconUrl": "https://example.com/avatar.png"
},
"createdAt": "2026-10-01T00:00:00.000Z",
"updatedAt": "2026-10-01T00:00:00.000Z"
}
],
"pagination": {
"total": 139,
"limit": 10,
"offset": 0
}
}
  • Each occurrence of a recurring event has an id of the form {series ID}::{original start time of the occurrence}, and seriesId holds the series ID. One-off events use their plain ID and have no seriesId
  • world contains the venue world (omitted when the world has no published version)
  • instance is only present for instant events (kind: instant) and contains the running instance
  • status is the actual state based on the time of the request

Errors​

The validation error messages for this endpoint are returned in Japanese.

StatusConditionExample response
400from / to is missing{ "error": "from と to(表示範囲)は必須です(ISO 8601)" }
400from / to is not a valid date{ "error": "from は有効な日時(ISO 8601)を指定してください" }
400from is after to{ "error": "from は to 以前を指定してください" }
400The period exceeds 366 days{ "error": "取得期間(from〜to)は366日以内で指定してください" }
400Invalid kind / status / order, or empty ownerIdAn error for that parameter
400limit / offset is not a decimal integer, or limit is 0{ "error": "limit は 1 以上の整数を指定してください" }

GET /events/:id​

Get the details of the event with the specified ID.

  • Scope: read:events

Path parameters​

ParameterTypeDescription
idstringEvent ID. Occurrence IDs of recurring events ({series ID}::{time}) are also accepted

With an occurrence ID, the details of that occurrence are returned (its own time, plus any changes made to that occurrence only). With a series ID, the series is returned (with the time of the first occurrence).

tip

Occurrence IDs contain :, so URL-encode them before use.

Request example​

# One-off event or series
curl -H "Authorization: Bearer xrift_sk_xxx" \
"https://api.xrift.net/api/public/v1/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# An occurrence (xxxxxxxx-...::2026-12-02T13:00:00.000Z, URL-encoded)
curl -H "Authorization: Bearer xrift_sk_xxx" \
"https://api.xrift.net/api/public/v1/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%3A%3A2026-12-02T13%3A00%3A00.000Z"

Response example​

Returns the same shape as each element of GET /events, under data.

{
"data": {
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx::2026-12-02T13:00:00.000Z",
"seriesId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"title": "VR Catch-up",
"startAt": "2026-12-02T13:00:00.000Z",
"endAt": "2026-12-02T14:00:00.000Z",
"repeatFrequency": "biweekly"
}
}

(Some fields are omitted.)

Errors​

StatusConditionResponse
404Event doesn't exist, the occurrence was cancelled, or the time isn't part of the series{ "error": "Event not found" }

GET /stats​

Get platform-wide statistics.

  • Scope: None (authentication only — accessible with any API key)

Request example​

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

Response example​

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

Common error responses​

Errors that can be returned by all endpoints.

StatusMeaningResponse example
401Authorization header missing{ "error": "Authentication required" }
401Invalid token format{ "error": "Invalid token format" }
401Invalid API key{ "error": "Invalid API key" }
401API key is deactivated{ "error": "API key is deactivated" }
401API key has expired{ "error": "API key has expired" }
401Invalid CLI token{ "error": "Invalid CLI token" }
401CLI token has expired{ "error": "CLI token has expired" }
403Insufficient scope{ "error": "Insufficient scope. Required: read:worlds" }
429Rate limit exceeded{ "error": "Rate limit exceeded" }

Rate limiting​

  • 1,000 requests per hour (default)
  • Applies to API key authentication only (CLI tokens are exempt)
  • Calculated using a fixed window algorithm

Rate limit usage is returned via response headers (API key authentication only).

HeaderDescription
X-RateLimit-LimitMaximum requests allowed
X-RateLimit-RemainingRemaining requests
X-RateLimit-ResetReset time (Unix timestamp)
caution

When the rate limit is exceeded, a 429 Too Many Requests response is returned. Wait until the time indicated in the X-RateLimit-Reset header before retrying.