insert_model

Insert a model from the Roblox marketplace

Description

Searches the Roblox marketplace for free models and inserts the top result into the game. Automatically positions the model in front of the camera and handles naming conflicts.

Endpoint

insert_model

Parameters

query · string · required

The search query for finding the model (e.g., “tree”, “car”, “sword”)

parent · string

The path to the parent instance. Defaults to Workspace if not specified.

Response

ok · boolean

Returns true if the model was inserted successfully

name · string

The name assigned to the inserted model

className · string

The class name of the inserted instance (e.g., “Model”, “Folder”)

assetId · number

The Roblox asset ID of the inserted model

path · string

The full path to the inserted instance

error · string

Error message if the search or insertion failed

Behavior

Positioning

• Models: Positioned via PivotTo() at the camera raycast point
• BaseParts: Positioned via Position property
• Other: Inserted without position adjustment

Naming

• Query is converted to TitleCase (e.g., “cool tree” → “CoolTree”)
• If name exists, appends a number (e.g., “Tree1”, “Tree2”)

Multiple Objects

• If asset contains multiple objects, they’re wrapped in a Model or Folder
• Uses Model if any object is a PVInstance, otherwise uses Folder

Examples

Insert a tree

{
  "query": "tree"
}

Response:

{
  "ok": true,
  "name": "Tree",
  "className": "Model",
  "assetId": 123456789,
  "path": "Workspace.Tree"
}

Insert into a specific parent

{
  "query": "sword",
  "parent": "ReplicatedStorage.Weapons"
}

Response:

{
  "ok": true,
  "name": "Sword",
  "className": "Model",
  "assetId": 987654321,
  "path": "ReplicatedStorage.Weapons.Sword"
}

Name conflict handling

{
  "query": "car"
}

Response (if “Car” already exists):

{
  "ok": true,
  "name": "Car1",
  "className": "Model",
  "assetId": 555555555,
  "path": "Workspace.Car1"
}

No results found

{
  "query": "xyznonexistent123"
}

Response:

{
  "error": "No models found for: xyznonexistent123"
}

Marketplace search failed

{
  "query": "tree"
}

Response:

{
  "error": "Marketplace search failed: [error details]"
}

Notes

• Only searches free models (no paid assets)
• Inserts the top search result
• Positioning uses a raycast from the center of the camera viewport
• Fallback position is 20 studs in front of the camera if no surface is hit
• Models are inserted at the raycast hit point or fallback distance