Using the HTTP API

Drive Beam Bench from any HTTP client. Same operations as the CLI, integration-friendly.

Beam Bench's HTTP / WebSocket API is the same surface the CLI talks to. If you have a use case that needs Beam Bench in a non-CLI environment (web app, integration server, mobile app), use the HTTP API directly.

What you need

Beam Bench installed.
The Local API enabled in Edit → Settings → General. It ships off by default.
An HTTP client (curl, your language's HTTP library, Postman, etc.).

Verify the API is enabled

The defaults in the current build are deliberately locked down:

Local API: off.
API Port: 5900.
Allow network devices to connect: off. While it remains off, the server accepts connections only from this computer.

Open the desktop app, go to Edit → Settings → General, and turn Local API on. Leave Allow network devices to connect off for scripts running on the same computer. The settings take effect immediately.

Read the HTTP API page before binding to the network on a shared Wi-Fi. The API has no authentication and can move the machine and fire the laser.

Base URL

http://localhost:5900/api/v1

(Or your machine's LAN IP instead of localhost, when Allow network devices to connect is on.)

Steps

1. Verify the API is up

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

Returns the capability schema. (Replace 5900 with your configured port if you changed it.)

2. Inspect state

curl -s http://localhost:5900/api/v1/agent/state | jq .

3. Open a project

curl -s -X POST http://localhost:5900/api/v1/projects/open \
  -H 'Content-Type: application/json' \
  -d '{"path":"/abs/path/to/file.lzrproj"}'

4. Render the design (headless)

curl -s -X POST http://localhost:5900/api/v1/design/render \
  -H 'Content-Type: application/json' \
  -d '{"format":"png","pixels_per_mm":4,"output_path":"/tmp/out.png"}'

5. Get camera state

curl -s http://localhost:5900/api/v1/camera/state | jq .

6. Render camera overlay (requires app)

curl -s -X POST http://localhost:5900/api/v1/camera/overlay/render \
  -H 'Content-Type: application/json' \
  -d '{"output_path":"/tmp/overlay.png","view":"fit","keep":true}'

Available endpoint groups

See the API reference section (when populated) for the full surface. Major groups:

/agent, capabilities, state, guide.
/camera, devices, state, capture, overlay (display, transform, render), calibration, alignment.
/design, describe, render, transactions.
/projects, open, save, close, layers, objects, undo/redo, import.
/export, svg, dxf, pdf, eps, ai.

Security

The API server has no authentication. It assumes the network it is on is trusted.

Localhost-only binding limits exposure to the local machine.
Network binding is a separate opt-in and opens the API to anyone on the same LAN. Enable it only on a trusted network.

Verify it worked

curl agent/capabilities returns JSON.
A render call produces the requested file.

Using the HTTP API

On this page