Rooms

These routes are for creator-owned game workflows. They are not a general-purpose database API. Use the smallest route that matches the change you need, and test the result in a non-production game first.

Create a game from a template

POST /api/v2/rooms/create

Required header: x-access-key

Request body:

{
  "templateName": "current-template-name",
  "customTemplateName": "optional display name"
}

templateName is required in practice and is resolved against the current template catalog. Do not hard-code a list from this documentation: available templates can change.

On success, the response is:

{
  "code": "SUCCESS",
  "room": {
    "RoomID": "string",
    "Name": "string or null"
  }
}

The returned room object contains additional game metadata. Use room.RoomID as the identifier for later room operations.

A missing or unknown template returns an error. The service can also reject creation when creator or storage limits apply.

Duplicate a game you own

POST /api/v2/rooms/duplicate

Required header: x-access-key

Request body:

{
  "roomId": "source-room-id"
}

A successful response has this shape:

{
  "code": "SUCCESS",
  "message": "human-readable copy message",
  "roomId": "new-room-id"
}

The caller must own the source game. A copy receives a new game identifier and should be treated as a separate project. Test it before sharing or publishing it.

Update supported top-level metadata

POST /api/v2/room/update-room-settings

Required header: x-access-key

The body must wrap fields inside room. RoomID is required for the public contract:

{
  "room": {
    "RoomID": "room-id",
    "Name": "New name",
    "Description": "Short player-facing summary"
  }
}

This route only persists an explicit server-side allowlist. The public automation subset is:

Send only fields you intend to change. Fields outside this documented subset are not a public automation contract. This endpoint is not a replacement for a room-data snapshot import.

A successful response is:

{
  "data": {
    "RoomID": "room-id",
    "...": "updated public game data"
  }
}

Updating metadata requires authorization to manage the game. Archiving a game requires the game's owner.

Download a room-data snapshot

GET /api/v2/mcp/download-room-data

Required headers:

The response is an application/json attachment with a Content-Length header. Its file shape is documented in Room Data Format.

Always download and keep a backup before importing room data. The route can return 404 if the room’s runtime data is not currently available; opening the game in a browser can make it available.

Import room data from a JSON location

POST /api/v2/mcp/upload-room-data-url

Required headers:

Request body:

{
  "jsonUrl": "publicly readable JSON location"
}

The service first sends a HEAD request to jsonUrl. The response must include Content-Length, and the content must be 50 MB or smaller. It then reads the JSON and applies the sections that are present.

Import behavior is section-specific:

• When roomItems is present, it is reconciled with the existing item set. Items omitted from that object are removed.
• When settings, roomTasks, or quests is present, that section is rewritten. Omit a section to leave it unchanged.
• When logic is present with roomItems, each logic entry is merged back into the matching item’s extraData field.

This is why backup-first matters. Start with a snapshot, make a focused edit, validate the JSON, and import only after you can explain the intended difference.

If the JSON location is the service-managed location returned by the JSON upload route, the import handler removes that object after a successful import. Keep your original backup somewhere you control.

Read a game’s build inventory

GET /api/v2/room/get-build-items?roomId=room-id

Required header: x-access-key

The caller must be authorized to manage the game. A successful response is:

{
  "code": "SUCCESS",
  "items": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "category": "string",
      "glb": "string or null",
      "audio": "string or null",
      "thumbnailSrc": "string"
    }
  ]
}

The list combines directly attached items and items supplied by attached build lists. It returns placeable models, audio, images, and textures that are accessible to the game.

Prefer a safer route when possible

• Change a title or image: use update-room-settings.
• Start from an existing game: use duplicate.
• Inspect available build assets: use get-build-items.
• Change an entire saved room snapshot: download first, then use the JSON import workflow.
• Need help deciding or testing a change: start with MCP setup.