HTTP API Reference

Direct HTTP API usage for RbxGenie daemon

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 Example

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

Get file tree

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

Vector3 Position

{
  "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:

1. 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).

2. Client sends tool request

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

3. Daemon enqueues command

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

4. Plugin receives command

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

5. Plugin executes and returns

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

6. 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