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 (it ships on by default, on port 5900).
An HTTP client (curl, your language's HTTP library, Postman, etc.).

Verify the API is enabled

The defaults in the current build:

Local API: on.
API Port: 5900.
Allow network devices to connect: on. The server is reachable from any device on your network.

To change any of these, open the desktop app and go to Edit → Settings → General. 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, which is on by default in the current build, opens to anyone on the same LAN. Treat that like running an open SMB share.

Verify it worked

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

Using the HTTP API

On this page