API Guide

OverMox ships a full local API. Everything you can do in the app, you can drive programmatically over HTTP and WebSocket against the OverMox app running on your own machine at http://localhost:5000. There are three lenses on it: this guide, the REST reference, and the live event stream.

REST Reference

Every endpoint, request, and response. Browse and try the OpenAPI reference.

L3 Event Stream

The live WebSocket events (AsyncAPI) the app emits as your scene runs.

Run it locally

The interactive “Try it” buttons on the REST reference talk to the OverMox app on your own machine (http://localhost:5000). Launch OverMox to run requests live; the reference is fully browsable without it.

You can also view the raw llms.txt, the same machine-readable API guide OverMox serves, and feed it to your own AI assistant.

REST + WebSocket API for OverMox, a realtime 3D creative environment, and its companion visual node graph editor (OverMox Controller).

Website: https://overmox.com Documentation: https://overmox.com/docs Base URL: http://localhost:5000 API root (discovery): http://localhost:5000/api API Reference: http://localhost:5000/swagger OpenAPI spec: http://localhost:5000/swagger/v1/swagger.json Rendered llms.txt: http://localhost:5000/llms

Start Here

This document is the canonical orientation. Use GET /api/toc for the full endpoint catalog and GET /api/schemas/layer1 for request/response shapes.

What This API Does

OverMox is a realtime 3D creative environment. OverMox Controller is its companion visual node graph editor. You create graphs in the Controller, add nodes to them, connect node ports together, set values, and run the graphs to execute logic in OverMox. Think of it like building a program visually - each node is a function, connections are data/control flow, and ports are inputs/outputs.

Three Layers

Layer 1: Graph CRUD (REST)

Build and manage node graphs, nodes, connections, ports, and variables in the Controller. Create graphs, add nodes, connect ports, set values, run/stop execution.

• Base: /api/graphs
• Discovery: /api/node-types, /api/node-types/enum-values, /api/schemas/layer1

Layer 2: Direct Actions (REST)

Execute OverMox capabilities as one-shot commands without building graphs. 146 actions across categories like scene, transform, physics, audio, animation.

• Base: /api/actions/{category}/{action}
• Discovery: /api/actions/schema
• Key scene actions: scene.spawn (use ‘type’ for Bundled Asset MenuPath from GET /api/discovery/spawnables, ‘sceneObject’ to duplicate by tag, ‘asset’ for project assets - exactly one required), scene.setColor, scene.switch, scene.reset, scene.clear (optional preserve parameter), scene.objects.destroy, scene.objects.setName, scene.objects.setActive, scene.objects.setLayer, scene.objects.getLayer, scene.createLayer (create or rename a layer by index; valid indexes 0-5 and 9-31, 6/7/8 are reserved). Layer names must be configured OverMox layers - use GET /api/discovery/layers to enumerate
• Asset actions: assets.list (enumerate all project assets with optional filters), assets.delete (permanent deletion, bundled assets require confirm=true), assets.createBundled (save a scene object as a reusable bundled asset), assets.getProperty / assets.setProperty / assets.setProperties (read/write asset properties via actions), assets.getProperties (bulk-read all properties), assets.getShader / assets.changeShader (read or change shader on materials), assets.listShaders (discover available shader names)
• MIDI: midi.send (output), midi.subscribe/unsubscribe (input streaming), midi.devices (enumeration)
• Output Settings: output.get (read), output.set (write), output.toggle (individual booleans) - resolution, FPS, VSync, Spout, NDI, markup
• Webhooks: webhook.listen (register), webhook.unlisten (remove), webhook.listeners (list) + webhook.received L3 event
• Streaming: streaming.platforms (discover), streaming.subscribe/unsubscribe (control), streaming.status (list) + streaming.event L3 event - supports Twitch, YouTube, StreamElements, StreamLabs

Layer 3: Real-time Events (WebSocket)

Stream events from OverMox and send continuous control inputs via SignalR at ws://localhost:5000/api/events. Events include graph.running, graph.stopped, node.executing, console.log, tween.completed, midi.input, and more.

• Catalog: visit /asyncapi for the human-readable AsyncAPI viewer or GET /api/events/types for the raw JSON document.
• node.done: a node finished executing.
• ports.updated: port values changed during graph execution.
• variable.changed: a variable value was updated.
• variable.deleted: a variable was removed.
• webhook.received: an external HTTP POST hit a registered webhook listener.
• streaming.event: a streaming platform event arrived (Twitch, YouTube, StreamElements, StreamLabs).
• process.loaded: a process started via process.start finished loading; payload carries processId, processName, and startTime. Subscribe and filter by processId from the process.start response to gate downstream work on a specific child.
• process.exited: a process started via process.start exited; payload carries processId, processName, and exitCode. Pairs with process.loaded for full-lifecycle tracking; process.start is fire-and-forget on the REST side.
• project.opened: a project was loaded.
• project.closed: a project was unloaded.
• overmox.connected: an OverMox client connected.
• overmox.disconnected: an OverMox client disconnected.
• Hub methods: Subscribe(patterns), Unsubscribe(patterns), SendAction(CommandRequest), SendActionBatch(commands, parallel=false)
• SendAction: pass Action (dot notation, e.g. “log.console”), Parameters, optional RequestId (omit or empty GUID for fire-and-forget)
• SendActionBatch: send multiple commands; when parallel=true, responses collected concurrently
• Callbacks: ReceiveEvent, ActionResponse (per-command), BatchActionResponse (batch completion)

Security

The external API is OFF by default; enable it under Settings > API in the OverMox Controller. While disabled, gated endpoints return 403 API_DISABLED and only the OverMox runtime link and the doc viewers keep working. Gated endpoints require a token. For REST send it as the X-API-Key header; for the /api/events hub send it as the access_token query parameter or a Bearer header. The token (apiToken) is auto-generated and stored in the per-user settings file at %AppData%/OverMoxController/api-security-settings.json, readable only by the current OS user. GET /api/health is always free and explains onboarding - it reports apiEnabled and authenticated, and for loopback callers includes the settings-file path. Tiers: free endpoints (no token) are /api/health, /api/toc, /api/schemas, /api/actions/schema, plus the doc viewers (/swagger, /llms, /asyncapi, /llms.txt); everything else under /api and the hub SendAction/SendActionBatch methods are gated. Network: loopback is the default, serving plain HTTP on localhost that is not network-reachable. Optional LAN mode serves over HTTPS with a self-signed cert (its SHA-256 fingerprint is shown for client pinning), still requires the token, and only accepts connections from allow-listed client IPs. The internal OverMox runtime link is loopback-only and Origin-checked, takes no token, and is unaffected by the API toggle. Sensitive port values (JWT tokens, API keys) are redacted by default. Port responses include isSensitive (bool) and hasValue (bool, when redacted) metadata. Writing to sensitive ports always works; only read responses are redacted. Enable ‘Expose sensitive port values’ in the Controller settings UI for full access.

Runtime Discovery

Query what OverMox knows at runtime - scene objects, Bundled Assets, components, and more.

GET /api/discovery - list all 11 available data types with descriptions GET /api/discovery/scene-objects - all objects in the current scene GET /api/discovery/bundled-assets - available Bundled Assets for spawning GET /api/discovery/runtime-assets - audio clips, videos, materials, textures, models GET /api/discovery/components-info - component types and their properties GET /api/discovery/scenes - available scenes GET /api/discovery/transitions - animation transitions GET /api/discovery/midi-devices - connected MIDI hardware GET /api/discovery/input-info - input bindings (no OverMox needed) GET /api/discovery/input-action - current input state GET /api/discovery/app-data - application data and component catalog GET /api/discovery/layers - configured OverMox layers (names for SetLayer / Other Layer)

All responses use uniform envelope: { “dataType”: ”…”, “count”: N, “items”: […] } Use ?filter=keyword to narrow results by name/type.

Property Access

Read and write component and asset properties directly on scene objects and assets, without building node graphs.

Scene Object Properties

Workflow: discover components on an object, then list or read/write individual properties.

GET /api/objects/{tag}/components - list all components on a scene object with property counts GET /api/objects/{tag}/components/{component} - list all properties on a component with current values and types GET /api/objects/{tag}/components/{component}/{property} - read a single property value PUT /api/objects/{tag}/components/{component}/{property} - set a property value. Body: { “value”: }

Asset Properties

GET /api/assets/{tag}/properties - list all properties on an asset with current values GET /api/assets/{tag}/properties/{property} - read a single asset property value PUT /api/assets/{tag}/properties/{property} - set an asset property value. Body: { “value”: }

Bulk Property Set

Set multiple properties in one call instead of N individual PUTs. Best-effort - each property is set independently, and per-property results are returned.

PUT /api/objects/{tag}/components/{component}/properties - set multiple component properties POST /api/actions/components/refresh - trigger visual rebuild after property changes (AudioVisualizer, DynamicShadowBoxModeler, VectorShape, TextElement3d) PUT /api/assets/{tag}/properties - set multiple asset properties

Body: { “properties”: [ { “name”: “Position”, “value”: { “x”: 1, “y”: 2, “z”: 3 } }, { “name”: “Scale”, “value”: { “x”: 2, “y”: 2, “z”: 2 } } ] } Response: { “totalCount”: 2, “succeededCount”: 2, “failedCount”: 0, “results”: [ { “name”: “Position”, “success”: true }, … ] }

Important Notes

• Property names are case-sensitive and may contain spaces - URL-encode them (e.g., Is%20Trigger).
• Use GET /api/discovery/scene-objects to find valid object tags.
• Use GET /api/discovery/runtime-assets to find valid asset tags.
• Use GET /api/types for value format reference when setting property values.

Console Log History

Read the in-memory console log buffer (up to 500 entries, newest first).

GET /api/console - list all console log entries GET /api/console?type=error - filter by severity (log, warning, error) GET /api/console?contextType=graph - filter by context kind (graph, node, none) GET /api/console?since=2024-01-15T10:30:00Z - entries after a timestamp GET /api/console?type=error&limit=10 - combine filters

For real-time console streaming, subscribe to the console.log WebSocket event via Layer 3.

How to Build a Graph (Step by Step)

Step 1: Check health

GET /api/health Returns: { “status”: “healthy”, “overmoxConnected”: true } Both OverMox and the Controller should be running. Layer 2 and 3 require OverMox to be connected (check overmoxConnected in the health response).

Step 2: Orient yourself

GET /api/toc Returns the full endpoint catalog with method, path, and one-line purpose for every endpoint. Combine with this guide for orientation.

Step 3: Find the nodes you need

GET /api/node-types/search?q=console log Returns matching nodes with their enumValue field. The enumValue is what you use as the category when adding nodes.

Currently available: 165 nodes across 20 categories. GET /api/node-types/enum-values returns all valid category values.

Step 4: Create a graph

POST /api/graphs Body: { “name”: “My Graph” } Both fields are optional - name is auto-generated if omitted, path defaults to the project’s Graphs folder if omitted. Returns 409 NO_PROJECT if no project is open, or 409 DUPLICATE_PATH if a graph already exists at the specified path. Use ?replace=true to replace an existing graph at the same path instead of getting 409. Returns the full graph detail including two default nodes (Start and OnNewFrame) with all their port IDs - no follow-up call needed.

Step 5: Add nodes

POST /api/graphs/{graphId}/nodes Body: { “category”: “ConsoleLog”, “locationX”: 200, “locationY”: 0 } Use the enumValue from step 3 as the category field. The response includes the node’s ID and all its input/output ports with their IDs and types.

For bulk creation, POST /api/graphs/{graphId}/nodes/bulk with an array of node specs (up to 1000). All-or-nothing with rollback.

Step 6: Connect nodes

POST /api/graphs/{graphId}/connections Body: { “outputPortId”: ”…”, “inputPortId”: ”…” } Connect an output port from one node to an input port on another. Port IDs come from the node responses in step 5.

Step 7: Set port values

PUT /api/ports/{portId}/value Body: { “value”: “Hello World” } Use GET /api/types to learn the correct value format for each port type (e.g., Vector3 uses {“x”:0,“y”:0,“z”:0}). Vector ports also accept [x,y,z] arrays or a scalar (applied to all axes). Color ports accept [r,g,b,a], [r,g,b] (alpha defaults to 1), or {“r”:1,“g”:0,“b”:0,“a”:1}. For dropdown/enum ports, use GET /api/ports/{portId}/options to discover valid values. Set by label string or index integer. Invalid strings return 400 with valid options listed.

Step 8: Run the graph

POST /api/graphs/{graphId}/sync (required before run - L1 edits do not auto-sync) POST /api/graphs/{graphId}/run (execute the graph) POST /api/graphs/{graphId}/stop (stop execution) POST /api/graphs/{graphId}/ports/sync (force-flush live port values during execution; pair with GET /api/ports/{portId}/value for deterministic reads while the graph runs) Tip: All L1 mutation endpoints accept ?sync=true to sync after the mutation (e.g., POST /api/graphs/{graphId}/nodes?sync=true). Use on the last edit in a batch instead of a separate /sync call.

Other operations

POST /api/project/open (open a project from a file path - requires OverMox connected) POST /api/actions/project/refresh (refresh the project panel from disk - requires OverMox connected) POST /api/graphs/{graphId}/save (save to disk - returns 409 GRAPH_RUNNING if running; stop it first) POST /api/graphs/{graphId}/duplicate (duplicate - returns 409 GRAPH_RUNNING if running; stop it first) POST /api/graphs/{graphId}/remove (remove from Controller - does NOT delete the file on disk)

Node Lookup (Cross-Graph)

GET /api/nodes/{nodeId} - look up a node by ID across all graphs. Returns node detail with a graphId field. No graph ID needed in the URL.

Note Nodes (Header Chrome)

Note nodes (category=Note) are visual annotations rendered in the graph canvas. They have header-only formatting (font, color, font size) that does not affect graph execution. Text body still uses the standard PUT /api/ports/{portId}/value path; the formatting fields are exposed only via the dedicated sub-resource:

GET /api/graphs/{graphId}/nodes/{nodeId}/note - returns the current text, font, color, and fontSize plus availableFonts/availableColors/availableFontSizes for discovery. PUT /api/graphs/{graphId}/nodes/{nodeId}/note - partial update. Body: { “text”: ”…”, “font”: ”…”, “color”: ”…”, “fontSize”: 20 }. Any subset of fields; absent fields stay unchanged. Unknown font/color or unsupported fontSize returns 400 INVALID_VALUE; calling against a non-Note node returns 400 INVALID_REQUEST.

Declarative Graph Builder

POST /api/graphs/{graphId}/build - create nodes, set port values, and wire connections in one call. Supports connections-only builds (empty nodes array) for wiring existing nodes. All-or-nothing with rollback on failure. Limits: 1000 nodes, 5000 connections.

Body: { “nodes”: [ { “tempId”: “n1”, “category”: “ConsoleLog”, “ports”: { “Message”: “Hello” } } ], “connections”: [ { “from”: “n1/Exit”, “to”: “existingNodeId/Enter” } ] }

Connections reference ports as tempId/PortName (new nodes) or existingNodeId/PortName (existing nodes). Port values accept compound formats (arrays, objects, scalars for vectors and colors).

Batch Operations

POST /api/batch - execute multiple operations in one request. Best-effort, sequential.

Body: { “operations”: [ { “method”: “POST”, “path”: “/api/graphs”, “body”: { “name”: ”…” } }, … ] } Response: { “totalOperations”: N, “succeeded”: N, “failed”: N, “results”: [ { “index”: 0, “status”: 201, “body”: … } ] }

Order preserved. Each runs through full middleware. No recursive batches.

Key Concepts

• Nodes are functions. Each has typed input and output ports.
• Connections link an output port to an input port, creating data or control flow. Port type compatibility is validated - allowed pairings: same type, Generic with any, Float with Integer, String with ObjectSelector, Button to Trigger (one-way). Use POST /api/graphs/{graphId}/connections/validate to check before connecting.
• Port types use shortened canonical names: Float, Trigger, Dropdown. Use GET /api/types for the full list.
• Trigger ports control execution order (like trigger/execution pins in visual scripting).
• Category enum values are the canonical identifiers for node types. Always use GET /api/node-types/enum-values to discover valid values.
• Port expansion - Vector and Color ports can be expanded into individual sub-ports (X/Y/Z or R/G/B/A) via POST /api/ports/{portId}/expand and collapsed via POST /api/ports/{portId}/collapse. Port responses include metadata: isExpandable, isExpanded, isExpandedChild, parentPortId, affectsNodePorts.
• Trigger port disable/enable - Trigger ports can be disabled via POST /api/ports/{portId}/disable and re-enabled via POST /api/ports/{portId}/enable. Both are idempotent. Returns 404 PORT_NOT_FOUND, 405 TYPE_IMMUTABLE for non-trigger ports, or 409 GRAPH_RUNNING if the graph is running.
• Dynamic ports - Dropdown/enum port value changes may alter the node’s port structure. When this happens, PUT /api/ports/{portId}/value returns both the port and the full updated node. Check affectsNodePorts on a port to know if it may trigger structure changes.
• L2 parameter validation - Layer 2 action parameters are validated against schemas before dispatch. Wrong types or missing required params return 400. Use GET /api/actions/schema for parameter details.
• Layer 2 parameters are case-insensitive - both {“text”: “hello”} and {“Text”: “hello”} work. Use GET /api/actions/schema for canonical parameter names.
• Variable sync for L2 actions - if you update a variable (PUT /api/variables/{id}/value) and then call an L2 action that reads it (e.g., text.format), add ?sync=true to the variable update so the new value reaches OverMox before the action runs.
• Camera control - cameras are scene objects. Use transform/tween actions with the camera’s tag (e.g., _camera) for dolly shots, rotations, look-at, and orbit. Use the property endpoint to adjust Field Of View for zoom.
• ComposeVector3 - use the ComposeVector3 node to build a Vector3 from individual X, Y, Z float values. Useful when constructing positions or rotations from separate numeric inputs.

Error Handling

All errors include actionable messages that tell you which endpoint to call to fix the problem. For example, an invalid category error will tell you to check GET /api/node-types/enum-values.

Error format: { “error”: { “code”: “ERROR_CODE”, “message”: “Human-readable message with fix suggestion” } } Full error catalog: GET /api/errors

Pagination & Filtering

• All list endpoints support ?limit=N&offset=M for pagination. X-Total-Count header is always present.
• Use ?wrap=true to get a {totalCount, items} envelope instead of a bare array.
• Some endpoints support ?include=field1,field2 or ?exclude=field1,field2 to reduce response size.

Layout Endpoints

6 endpoints under /api/graphs/{id}/layout/ for auto-layout, tidy, restore, and aspect ratio management:

• POST /api/graphs/{id}/layout - Apply auto-layout (7 modes: Story, Compact, Wide, etc.)
• POST /api/graphs/{id}/layout/tidy - Grid-snap and alignment
• POST /api/graphs/{id}/layout/restore - Restore pre-layout positions
• GET /api/graphs/{id}/layout/saved - Check if saved positions exist
• GET /api/graphs/{id}/layout/aspect-ratio - Get current aspect ratio
• PUT /api/graphs/{id}/layout/aspect-ratio - Set aspect ratio

Discovery Endpoints (Reference)

Endpoint	Purpose
GET /api/node-types	Browse node categories
GET /api/node-types/search?q=…	Search for nodes by name
GET /api/node-types/enum-values	All valid category values for adding nodes
GET /api/schemas/layer1	Request/response schemas for CRUD operations
GET /api/actions/schema	All Layer 2 action schemas with parameters
GET /api/types	Port types, compatibility rules, value formats
GET /api/errors	Error code catalog with resolutions
GET /api/health	API and OverMox connection status
GET /api/toc	Complete endpoint listing
GET /api/objects/{tag}/components	List components on a scene object
GET /api/assets/{tag}/properties	List properties on an asset
PUT /api/objects/{tag}/components/{component}/properties	Set multiple component properties in one call
PUT /api/assets/{tag}/properties	Set multiple asset properties in one call
GET /api/console	Console log history with filtering
GET /api/nodes/{nodeId}	Look up a node by ID across all graphs
POST /api/graphs/{id}/nodes/bulk	Add multiple nodes in one call (up to 1000, all-or-nothing)
POST /api/graphs/{id}/build	Declarative graph builder (nodes + ports + connections in one call)