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.
| Method | Header | Use case |
|---|---|---|
| API Key | Authorization: Bearer xrift_sk_xxx | For third-party developers (scoped + rate limited) |
| CLI Token | Authorization: Bearer xrf_xxx | For 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
401error
Scopes
API key authentication uses scope-based access control. If the required scope is missing, a 403 error is returned.
| Scope | Access |
|---|---|
read:worlds | World list, search, details, popular ranking, stats, and user's public worlds |
read:users | User public profile and user search |
read:instances | Instance list, details, and world instances |
read:marketplace | Marketplace listings: list, search, and details |
read:events | Event list and details |
CLI tokens skip scope checks and have access to all endpoints.
Endpoints
GET /worlds
List worlds with pagination.
- Scope:
read:worlds
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 20 | Number of items (max 50) |
offset | number | 0 | Offset |
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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
q | string | Required | - | Search keyword |
limit | number | - | 20 | Number of items (max 50) |
offset | number | - | 0 | Offset |
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
| Status | Condition | Response |
|---|---|---|
| 400 | q parameter is missing | { "error": "Query parameter \"q\" is required" } |
GET /worlds/popular
Get popular world rankings.
- Scope:
read:worlds
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
period | string | all | Ranking period (all / week / month) |
limit | number | 20 | Number of items (max 50) |
offset | number | 0 | Offset |
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
| Parameter | Type | Description |
|---|---|---|
id | string | World 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
| Status | Condition | Response |
|---|---|---|
| 404 | World does not exist | { "error": "World not found" } |
GET /worlds/:id/stats
Get public statistics for a specific world.
- Scope:
read:worlds
Path parameters
| Parameter | Type | Description |
|---|---|---|
id | string | World 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
}
}
Daily visit details (dailyVisits) are not publicly available.
Errors
| Status | Condition | Response |
|---|---|---|
| 404 | World 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
| Parameter | Type | Description |
|---|---|---|
id | string | World ID |
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 20 | Number of items (max 50) |
offset | number | 0 | Offset |
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
| Status | Condition | Response |
|---|---|---|
| 404 | World does not exist | { "error": "World not found" } |
GET /users/search
Search users by display name.
- Scope:
read:users
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
q | string | Required | - | Search keyword (partial match on displayName) |
limit | number | - | 20 | Number of items (max 50) |
offset | number | - | 0 | Offset |
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
| Status | Condition | Response |
|---|---|---|
| 400 | q 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
| Parameter | Type | Description |
|---|---|---|
id | string | User 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
| Status | Condition | Response |
|---|---|---|
| 404 | User 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
| Parameter | Type | Description |
|---|---|---|
id | string | User ID |
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 20 | Number of items (max 50) |
offset | number | 0 | Offset |
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
| Status | Condition | Response |
|---|---|---|
| 404 | User does not exist | { "error": "User not found" } |
GET /instances
List active instances with pagination.
- Scope:
read:instances
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
worldId | string | - | - | Filter instances by world |
limit | number | - | 20 | Number of items (max 50) |
offset | number | - | 0 | Offset |
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
}
}
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
| Parameter | Type | Description |
|---|---|---|
id | string | Instance 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
| Status | Condition | Response |
|---|---|---|
| 404 | Instance 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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
sort | string | - | popular | Sort order (popular: most acquired / newest: newest first / trending: recent momentum) |
ownerId | string | - | - | Only return listings by this user |
limit | number | - | 20 | Number of results (1–50; values above 50 are treated as 50) |
offset | number | - | 0 | Offset (0 or greater) |
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
}
}
fileSizeis the size in bytes, returned as a string
Errors
The validation error messages for this endpoint are returned in Japanese.
| Status | Condition | Response |
|---|---|---|
| 400 | Invalid sort | { "error": "sort は popular、newest、trending のいずれかを指定してください" } |
| 400 | Empty ownerId | { "error": "ownerId は空にできません" } |
| 400 | limit / offset is not a decimal integer (1.5, 1e2, 0x10, etc.), or limit is 0 | { "error": "limit は 1 以上の整数を指定してください" } |
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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
q | string | Required | - | Search keyword |
sort | string | - | newest | Sort order (popular / newest / trending) |
ownerId | string | - | - | Only return listings by this user |
limit | number | - | 20 | Number of results (1–50; values above 50 are treated as 50) |
offset | number | - | 0 | Offset (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
| Status | Condition | Response |
|---|---|---|
| 400 | q parameter is missing (including whitespace only) | { "error": "Query parameter \"q\" is required" } |
| 400 | Invalid sort / ownerId / limit / offset | Same as GET /marketplace/items |
GET /marketplace/items/:id
Get the details of the item with the specified ID.
- Scope:
read:marketplace
Path parameters
| Parameter | Type | Description |
|---|---|---|
id | string | Item 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
| Status | Condition | Response |
|---|---|---|
| 404 | Item doesn't exist, is private, or is under review | { "error": "Item not found" } |
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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
from | string | Required | - | Start of the period (ISO 8601) |
to | string | Required | - | End of the period (ISO 8601). Within 366 days of from |
worldId | string | - | - | Filter by venue world |
instanceId | string | - | - | Filter by instance |
ownerId | string | - | - | Filter by organizer |
kind | string | - | - | scheduled / instant |
status | string | - | - | upcoming / live / ended / cancelled |
order | string | - | asc | Sort order by start time (asc / desc) |
limit | number | - | 20 | Number of results (1–50; values above 50 are treated as 50) |
offset | number | - | 0 | Offset (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
idof the form{series ID}::{original start time of the occurrence}, andseriesIdholds the series ID. One-off events use their plain ID and have noseriesId worldcontains the venue world (omitted when the world has no published version)instanceis only present for instant events (kind: instant) and contains the running instancestatusis the actual state based on the time of the request
Errors
The validation error messages for this endpoint are returned in Japanese.
| Status | Condition | Example response |
|---|---|---|
| 400 | from / to is missing | { "error": "from と to(表示範囲)は必須です(ISO 8601)" } |
| 400 | from / to is not a valid date | { "error": "from は有効な日時(ISO 8601)を指定してください" } |
| 400 | from is after to | { "error": "from は to 以前を指定してください" } |
| 400 | The period exceeds 366 days | { "error": "取得期間(from〜to)は366日以内で指定してください" } |
| 400 | Invalid kind / status / order, or empty ownerId | An error for that parameter |
| 400 | limit / 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
| Parameter | Type | Description |
|---|---|---|
id | string | Event 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).
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
| Status | Condition | Response |
|---|---|---|
| 404 | Event 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.
| Status | Meaning | Response example |
|---|---|---|
| 401 | Authorization header missing | { "error": "Authentication required" } |
| 401 | Invalid token format | { "error": "Invalid token format" } |
| 401 | Invalid API key | { "error": "Invalid API key" } |
| 401 | API key is deactivated | { "error": "API key is deactivated" } |
| 401 | API key has expired | { "error": "API key has expired" } |
| 401 | Invalid CLI token | { "error": "Invalid CLI token" } |
| 401 | CLI token has expired | { "error": "CLI token has expired" } |
| 403 | Insufficient scope | { "error": "Insufficient scope. Required: read:worlds" } |
| 429 | Rate 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).
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed |
X-RateLimit-Remaining | Remaining requests |
X-RateLimit-Reset | Reset time (Unix timestamp) |
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.