Worlds API (Draft WIP) - lolmaxz/vrc-ts GitHub Wiki

World API Documentation

The World API allows you to manage worlds in VRChat—create, update, delete, and search for worlds.

Index

  1. searchAllWorlds - Search and list any worlds by query filters.

  2. createWorld - Create a new world.

  3. listActiveWorlds - Search and list currently active worlds.

  4. listFavoritedWorlds - Search and list favorited worlds.

  5. listRecentWorlds - Search and list recently visited worlds.

  6. getWorldById - Get information about a specific world.

  7. updateWorld - Update information about a specific world.

  8. deleteWorld - Delete a world.

  9. getWorldMetadata - Get a world's metadata (deprecated).

  10. getWorldPublishStatus - Get a world's publish status.

  11. publishWorld - Publish a world.

  12. unpublishWorld - Unpublish a world.

  13. getWorldInstance - Get information about a world instance.

Endpoints

1. searchAllWorlds

Search and list any worlds by query filters.

Purpose

Search and list any worlds by applying various query filters.

Method Signature

searchAllWorlds(options: {
  featured?: boolean;
  sort?: string;
  n?: number;
  offset?: number;
  order?: 'ascending' | 'descending';
  search?: string;
  tag?: string;
  notag?: string;
  releaseStatus?: 'public' | 'private' | 'hidden' | 'all';
  maxUnityVersion?: string;
  minUnityVersion?: string;
  platform?: string;
  user?: 'me';
  userId?: string;
  developer?: 'none' | 'internal';
  fuzzy?: boolean;
  includeInstances?: boolean;
}): Promise<LimitedWorld[]>

Parameters

  • options (object):

    • featured (boolean, optional):
      Filter by featured worlds. Default is false.

    • sort (string, optional):
      Sorting option. Default is 'popularity'.

    • n (number, optional):
      Number of results to return (1-100). Default is 10.

    • offset (number, optional):
      Offset from the first result. Must be 0 or greater.

    • order ('ascending' | 'descending', optional):
      Order of the results. Default is 'descending'.

    • search (string, optional):
      Search query string.

    • tag (string, optional):
      Tag to include.

    • notag (string, optional):
      Tag to exclude.

    • releaseStatus ('public' | 'private' | 'hidden' | 'all', optional):
      Release status to filter by.

    • maxUnityVersion (string, optional):
      Maximum Unity version.

    • minUnityVersion (string, optional):
      Minimum Unity version.

    • platform (string, optional):
      Platform to filter by.

    • user ('me', optional):
      User filter. Only 'me' is allowed for non-admin users.

    • userId (string, optional):
      User ID to filter by.

    • developer ('none' | 'internal', optional):
      Developer type to filter by.

    • fuzzy (boolean, optional):
      Enable fuzzy search. Default is false.

    • includeInstances (boolean, optional):
      Include instance information. Default is false.

Returns

  • Promise<LimitedWorld[]>: A promise that resolves to an array of limited world objects.

Example Usage

// Example: Search for public worlds with the tag 'game'
const worlds = await vrchatApi.worldsApi.searchAllWorlds({
  tag: 'game',
  releaseStatus: 'public',
  n: 20,
});
console.log(worlds);

2. createWorld

Create a new world.

Purpose

Create a new world. Requires valid asset URLs and image URLs.

Method Signature

createWorld(options: {
  assetUrl: string;
  assetVersion?: number;
  authorId?: string;
  authorName?: string;
  capacity?: number;
  description?: string;
  id?: string;
  imageUrl: string;
  name: string;
  platform?: string;
  releaseStatus?: 'public' | 'private' | 'hidden' | 'all';
  tags?: string[];
  unityPackageUrl?: string;
  unityVersion?: string;
}): Promise<World>

Parameters

  • options (object):

    • assetUrl (string, required):
      The asset URL of the world.

    • imageUrl (string, required):
      The image URL of the world.

    • name (string, required):
      Name of the world.

    • Other optional fields:

      • assetVersion (number, optional)
      • authorId (string, optional)
      • authorName (string, optional)
      • capacity (number, optional)
      • description (string, optional)
      • id (string, optional)
      • platform (string, optional)
      • releaseStatus ('public' | 'private' | 'hidden' | 'all', optional)
      • tags (string[], optional)
      • unityPackageUrl (string, optional)
      • unityVersion (string, optional)

Returns

  • Promise<World>: A promise that resolves to the created world object.

Example Usage

// Example: Create a new world
const newWorld = await vrchatApi.worldsApi.createWorld({
  assetUrl: 'https://example.com/asset.vrcw',
  imageUrl: 'https://example.com/image.png',
  name: 'My New World',
  description: 'A wonderful new world to explore.',
  capacity: 16,
  tags: ['exploration', 'fun'],
  releaseStatus: 'private',
});
console.log(newWorld);

3. listActiveWorlds

Search and list currently active worlds.

Purpose

Search and list currently active worlds by applying various query filters.

Method Signature

listActiveWorlds(options?: {
  n?: number;
  offset?: number;
  sort?: string;
  order?: 'ascending' | 'descending';
  search?: string;
  tag?: string;
  notag?: string;
  releaseStatus?: 'public' | 'private' | 'hidden' | 'all';
  maxUnityVersion?: string;
  minUnityVersion?: string;
  platform?: string;
}): Promise<LimitedWorld[]>

Parameters

  • options (object, optional):

    • n (number, optional):
      Number of results to return (1-100). Default is 10.

    • Other optional fields:
      Same as in searchAllWorlds, excluding featured, user, userId, developer, fuzzy, and includeInstances.

Returns

  • Promise<LimitedWorld[]>: A promise that resolves to an array of limited world objects.

Example Usage

// Example: List active worlds sorted by popularity
const activeWorlds = await vrchatApi.worldsApi.listActiveWorlds({
  sort: 'popularity',
  n: 20,
});
console.log(activeWorlds);

4. listFavoritedWorlds

Search and list favorited worlds.

Purpose

Search and list favorited worlds by applying various query filters.

Method Signature

listFavoritedWorlds(options?: {
  userId?: string;
  n?: number;
  offset?: number;
  sort?: string;
  order?: 'ascending' | 'descending';
  search?: string;
  tag?: string;
  notag?: string;
  releaseStatus?: 'public' | 'private' | 'hidden' | 'all';
  maxUnityVersion?: string;
  minUnityVersion?: string;
  platform?: string;
}): Promise<LimitedWorld[]>

Parameters

  • options (object, optional):

    • userId (string, optional):
      User ID to filter by. Admin only.

    • Other optional fields:
      Same as in listActiveWorlds.

Returns

  • Promise<LimitedWorld[]>: A promise that resolves to an array of favorited world objects.

Example Usage

// Example: List your favorited worlds
const favoritedWorlds = await vrchatApi.worldsApi.listFavoritedWorlds();
console.log(favoritedWorlds);

5. listRecentWorlds

Search and list recently visited worlds.

Purpose

Search and list recently visited worlds by applying various query filters.

Method Signature

listRecentWorlds(options?: {
  userId?: string;
  n?: number;
  offset?: number;
  sort?: string;
  order?: 'ascending' | 'descending';
  search?: string;
  tag?: string;
  notag?: string;
  releaseStatus?: 'public' | 'private' | 'hidden' | 'all';
  maxUnityVersion?: string;
  minUnityVersion?: string;
  platform?: string;
}): Promise<LimitedWorld[]>

Parameters

  • options (object, optional):

    • userId (string, optional):
      User ID to filter by. Admin only.

    • Other optional fields:
      Same as in listActiveWorlds.

Returns

  • Promise<LimitedWorld[]>: A promise that resolves to an array of recently visited world objects.

Example Usage

// Example: List your recently visited worlds
const recentWorlds = await vrchatApi.worldsApi.listRecentWorlds();
console.log(recentWorlds);

6. getWorldById

Get information about a specific world.

Purpose

Retrieve detailed information about a specific world by its ID.

Method Signature

getWorldById(options: { worldId: string }): Promise<World>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world to retrieve.

Returns

  • Promise<World>: A promise that resolves to the world object.

Example Usage

// Example: Get information about a specific world
const worldId = 'wrld_12345678-1234-1234-1234-1234567890ab';
const worldInfo = await vrchatApi.worldsApi.getWorldById({ worldId });
console.log(worldInfo);

7. updateWorld

Update information about a specific world.

Purpose

Update information about a specific world. You can update fields like name, description, tags, image URL, release status, etc.

Method Signature

updateWorld(options: {
  worldId: string;
  assetUrl?: string;
  assetVersion?: string;
  authorId?: string;
  authorName?: string;
  capacity?: number;
  description?: string;
  imageUrl?: string;
  name?: string;
  platform?: string;
  releaseStatus?: 'public' | 'private' | 'hidden' | 'all';
  tags?: string[];
  unityPackageUrl?: string;
  unityVersion?: string;
}): Promise<World>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world to update.

    • Other optional fields:
      Any of the fields you want to update (same as in createWorld).

Returns

  • Promise<World>: A promise that resolves to the updated world object.

Example Usage

// Example: Update the description of a world
const updatedWorld = await vrchatApi.worldsApi.updateWorld({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
  description: 'An updated description for the world.',
});
console.log(updatedWorld);

8. deleteWorld

Delete a world.

Purpose

Delete a world. Note that a world is never fully "deleted"; only its releaseStatus is set to 'hidden' and the linked files are deleted. The worldId is permanently reserved.

Method Signature

deleteWorld(options: { worldId: string }): Promise<Response>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world to delete.

Returns

  • Promise<Response>: A promise that resolves to a response object indicating the result.

Example Usage

// Example: Delete a world
const response = await vrchatApi.worldsApi.deleteWorld({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
});
console.log(response);

9. getWorldMetadata

Get a world's metadata (deprecated).

Purpose

Retrieve a world's custom metadata. This endpoint is deprecated and may be removed in the future.

Method Signature

getWorldMetadata(options: { worldId: string }): Promise<WorldMetadata>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world to get metadata for.

Returns

  • Promise<WorldMetadata>: A promise that resolves to the world's metadata object.

Example Usage

// Example: Get metadata for a world
const metadata = await vrchatApi.worldsApi.getWorldMetadata({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
});
console.log(metadata);

Note: This endpoint is deprecated and may not return useful data.

10. getWorldPublishStatus

Get a world's publish status.

Purpose

Check whether a world can be published.

Method Signature

getWorldPublishStatus(options: { worldId: string }): Promise<{ canPublish: boolean }>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world to check.

Returns

  • Promise<{ canPublish: boolean }>: A promise that resolves to an object indicating if the world can be published.

Example Usage

// Example: Check if a world can be published
const publishStatus = await vrchatApi.worldsApi.getWorldPublishStatus({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
});
console.log(publishStatus); // { canPublish: true }

11. publishWorld

Publish a world.

Purpose

Publish a world. You can only publish one world per week.

Method Signature

publishWorld(options: { worldId: string }): Promise<Response>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world to publish.

Returns

  • Promise<Response>: A promise that resolves to a response object indicating the result.

Example Usage

// Example: Publish a world
const response = await vrchatApi.worldsApi.publishWorld({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
});
console.log(response);

12. unpublishWorld

Unpublish a world.

Purpose

Unpublish a world.

Method Signature

unpublishWorld(options: { worldId: string }): Promise<Response>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world to unpublish.

Returns

  • Promise<Response>: A promise that resolves to a response object indicating the result.

Example Usage

// Example: Unpublish a world
const response = await vrchatApi.worldsApi.unpublishWorld({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
});
console.log(response);

13. getWorldInstance

Get information about a world instance.

Purpose

Retrieve information about a specific instance of a world.

Method Signature

getWorldInstance(options: {
  worldId: string;
  instanceId?: string;
}): Promise<Instance>

Parameters

  • options (object):

    • worldId (string, required):
      The ID of the world.

    • instanceId (string, optional):
      The ID of the instance to retrieve. If omitted, retrieves information about all instances.

Returns

  • Promise<Instance>: A promise that resolves to an instance object.

Example Usage

// Example: Get information about a specific instance of a world
const instanceInfo = await vrchatApi.worldsApi.getWorldInstance({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
  instanceId: 'instance_1',
});
console.log(instanceInfo);

// Example: Get information about all instances of a world
const allInstances = await vrchatApi.worldsApi.getWorldInstance({
  worldId: 'wrld_12345678-1234-1234-1234-1234567890ab',
});
console.log(allInstances);

Note: Some methods may require the user to be authenticated. Ensure you have successfully logged in before using these methods.

Please replace placeholder IDs like 'wrld_12345678-1234-1234-1234-1234567890ab' with actual IDs as needed.

Additional Notes

  • Deprecated Methods: The getWorldMetadata endpoint is deprecated and may be removed in future updates.
  • Publish Limits: You can only publish one world per week. Attempting to publish more frequently may result in an error.
  • Deletion: Deleting a world does not fully remove it; it sets the releaseStatus to 'hidden' and deletes linked files. The worldId remains reserved.
⚠️ **GitHub.com Fallback** ⚠️