Settings

Portals has two different settings surfaces, and they should not be confused.

• Top-level game metadata is changed with the supported room metadata route.
• Runtime scene settings travel inside a room-data snapshot and should be preserved as a complete object.

For normal creator work, use the no-code settings interface. Use REST only when an integration has a clear reason to automate a supported change.

Supported top-level metadata

POST /api/v2/room/update-room-settings changes an explicit public subset of game metadata. Its body must be wrapped in room and include RoomID:

{
  "room": {
    "RoomID": "room-id",
    "Name": "Updated title",
    "Description": "Updated summary"
  }
}

See Rooms for the complete public metadata allowlist and the permission rules.

This is the right route for player-facing identity, discovery metadata, build-inventory references, and other listed top-level fields. It is not a general runtime-settings patch.

Runtime scene settings

A room-data download includes a top-level settings object. That object contains the complete stored scene settings for the game.

When you need to automate a runtime settings change:

1. Download the current room-data snapshot.
2. Save an untouched backup.
3. Modify only the settings values you understand and intend to change.
4. Keep the rest of the settings object exactly as downloaded.
5. Import a JSON document that contains the complete settings object.
6. Reload the game and test the changed player experience.

The import handler writes settings only when a settings section is included. A settings-only import leaves roomItems, roomTasks, and quests untouched.

Why preserve the complete object

The runtime settings structure can contain nested and serialized values that work together. Rebuilding it from a partial reference risks changing player movement, camera behavior, atmosphere, communication, or interface behavior unintentionally.

Do not rely on an exhaustive field catalog from an older guide. The current source of truth for an integration is the snapshot returned by the target game plus the tested workflow you are applying.

Safe checklist

• Use the top-level metadata route for a title, description, image, or other documented metadata field.
• Use a room-data snapshot only when the change belongs inside runtime settings.
• Do not mix unrelated settings changes into one import.
• Validate JSON before import.
• Keep the backup until you have tested the game from the player spawn.
• If you need help deciding what is safe, start with MCP setup.

For visual and player-facing settings, see Build Your Game.