HTTP API Reference

Overview

The RbxGenie daemon exposes a REST API on http://127.0.0.1:7766 that allows any HTTP client to invoke Roblox Studio tools. This is the foundation for MCP integration and custom AI agents.

The daemon uses an event-driven long-polling architecture to bridge HTTP requests with the Roblox Studio plugin.

Base URL

http://127.0.0.1:7766

Default port: 7766 To use a custom port, set the PORT environment variable before starting the daemon:

PORT=8080 npm run dev

Authentication

The API currently does not require authentication — it binds to 127.0.0.1 (localhost only) for security.

Do not expose the daemon to the network without adding authentication. Anyone with access to the API can modify your Roblox Studio place.

Endpoints

POST /tool/:name

Invoke a tool by name. URL Parameters:

name (string) — Tool name (e.g., get_file_tree, set_property, execute_luau)

Request Body:

JSON object containing tool-specific arguments

Response:

200 OK — Tool executed successfully
500 Internal Server Error — Tool failed or timed out

Timeout:

120 seconds (2 minutes)

curl -X POST http://127.0.0.1:7766/tool/get_place_info \
  -H "Content-Type: application/json" \
  -d '{}'

Success Response

{
  "ok": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "result": {
    "PlaceId": 1234567890,
    "Name": "MyPlace",
    "CreatorType": "User",
    "CreatorId": 123456
  }
}

Fields:

ok (boolean) — Always true on success
id (string) — Unique command ID (UUID)
result (any) — Tool-specific result data

Error Response

{
  "ok": false,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "Instance not found: Workspace.NonExistent",
  "timeout": false
}

Fields:

ok (boolean) — Always false on error
id (string) — Unique command ID (UUID)
error (string) — Error message
timeout (boolean) — true if the command timed out
timeoutMs (number) — Timeout duration in milliseconds (present if timeout: true)

GET /health

Health check endpoint. Response:

{
  "ok": true,
  "service": "RbxGenie",
  "port": 7766
}

Use this to verify the daemon is running:

curl http://127.0.0.1:7766/health

GET /poll

Internal endpoint used by the Roblox Studio plugin to poll for pending commands.

Do not call this endpoint from external clients. It is designed for the plugin’s long-polling loop.

Behavior:

Returns immediately if a command is queued
Waits up to 15 seconds if no command is available
Returns { "hasCommand": false } on timeout

POST /result

Internal endpoint used by the Roblox Studio plugin to return command results.

Do not call this endpoint from external clients. It is designed for the plugin to resolve pending commands.

Request Format

All tool invocations use the same format:

POST /tool/<tool_name>
Content-Type: application/json

{ ...args }

Examples

POST /tool/get_file_tree

{
  "root": "Workspace",
  "depth": 2
}

Response Format

Success Response

{
  "ok": true,
  "id": "<uuid>",
  "result": <any>
}

The result field contains tool-specific data:

String results — Returned as plain strings
Object results — Returned as JSON objects
Array results — Returned as JSON arrays
Empty results — May be null, {}, or ""

Error Response

{
  "ok": false,
  "id": "<uuid>",
  "error": "<error message>",
  "timeout": false
}

Timeout Response

{
  "ok": false,
  "id": "<uuid>",
  "error": "Command <id> timed out after 120000ms",
  "timeout": true,
  "timeoutMs": 120000
}

Property Value Types

When setting properties, Roblox-specific types must be serialized as JSON:

Roblox Type	JSON Format
`string`	`"hello"`
`number`	`42`
`boolean`	`true`
`Vector3`	`{"type":"Vector3","value":[x,y,z]}`
`Vector2`	`{"type":"Vector2","value":[x,y]}`
`Color3`	`{"type":"Color3","value":[r,g,b]}` (0–1)
`CFrame`	`{"type":"CFrame","value":[...12 components]}`
`UDim2`	`{"type":"UDim2","value":[xScale,xOffset,yScale,yOffset]}`
`UDim`	`{"type":"UDim","value":[scale,offset]}`
`Enum`	`{"type":"Enum","value":"Enum.Material.Grass"}`

Examples

{
  "path": "Workspace.Part",
  "property": "Position",
  "value": {
    "type": "Vector3",
    "value": [10, 5, -3]
  }
}

Architecture

The HTTP API uses an event-driven command queue to bridge stateless HTTP requests with the long-lived Roblox Studio plugin connection:

Plugin polls for work

The Roblox Studio plugin maintains a long-polling loop, calling GET /poll every 15 seconds (or immediately when a command is queued).

Client sends tool request

An HTTP client (MCP server, custom script, etc.) POSTs to /tool/:name with arguments.

Daemon enqueues command

The daemon generates a UUID, enqueues the command, and waits for the plugin to pick it up.

Plugin receives command

The plugin’s pending /poll request immediately receives the queued command and starts execution.

Plugin executes and returns

The plugin dispatches the tool in Studio, captures the result, and POSTs it back to /result with the command ID.

Daemon resolves promise

The daemon matches the result by ID, resolves the pending promise, and returns the result to the HTTP client.

Error Handling

Timeout Errors

If the plugin does not respond within 120 seconds:

{
  "ok": false,
  "error": "Command <id> timed out after 120000ms",
  "timeout": true,
  "timeoutMs": 120000
}

Common causes:

Plugin is not running or disconnected
Studio is frozen or unresponsive
Tool execution is taking too long (e.g., large batch operations)

Execution Errors

If the tool fails in Roblox Studio:

{
  "ok": false,
  "error": "Instance not found: Workspace.BadPath"
}

Common causes:

Invalid instance paths
Missing permissions (e.g., trying to modify CoreGui)
Invalid property names or types
Luau runtime errors

Network Errors

If the daemon is unreachable:

Fetch failed: ECONNREFUSED

Common causes:

Daemon is not running
Wrong port or URL
Firewall blocking localhost connections

Rate Limiting

There is no rate limiting on the API. However:

Queueing too many commands simultaneously may cause Studio to become unresponsive. The plugin processes commands sequentially.

Best practices:

Wait for previous commands to complete before sending more
Use batch operations (mass_set_property, mass_create_objects, etc.) instead of individual requests
Monitor command execution time and adjust accordingly

Next Steps

Custom Agents

Build AI agents using the HTTP API

Tools Reference

Browse all 46 available tools

Claude Desktop

Use MCP with Claude Desktop

Cursor

Use MCP with Cursor IDE

Get Started

Architecture

Integration

Guides

Examples

HTTP API Reference

Overview

Base URL

Authentication

Endpoints

POST /tool/:name

Success Response

Error Response

GET /health

GET /poll

POST /result

Request Format

Examples

Response Format

Success Response

Error Response

Timeout Response

Property Value Types

Examples

Architecture

Error Handling

Timeout Errors

Execution Errors

Network Errors

Rate Limiting

Next Steps

Custom Agents

Tools Reference

Claude Desktop

Cursor

Build docs developers (and LLMs) love

Get Started

Architecture

Integration

Guides

Examples

​Overview

​Base URL

​Authentication

​Endpoints

​POST /tool/:name

​Success Response

​Error Response

​GET /health

​GET /poll

​POST /result

​Request Format

​Examples

​Response Format

​Success Response

​Error Response

​Timeout Response

​Property Value Types

​Examples

​Architecture

​Error Handling

​Timeout Errors

​Execution Errors

​Network Errors

​Rate Limiting

​Next Steps

Custom Agents

Tools Reference

Claude Desktop

Cursor

Build docs developers (and LLMs) love

Overview

Base URL

Authentication

Endpoints

POST /tool/:name

Success Response

Error Response

GET /health

GET /poll

POST /result

Request Format

Examples

Response Format

Success Response

Error Response

Timeout Response

Property Value Types

Examples

Architecture

Error Handling

Timeout Errors

Execution Errors

Network Errors

Rate Limiting

Next Steps