HTTP API

The HTTP API is the integration surface for Beam Bench. The desktop app, the CLI, and any external client all talk to the same routes. If you have a use case that needs Beam Bench in a non-CLI environment (web app, integration server, mobile app, your own tooling), use the API directly.

The API is shipped with the desktop app and runs in-process. There is no separate service to install.

Defaults and security

In the current build, the local API server runs by default with these settings:

• Local API: on.
• API Port: 5900.
• Allow network devices to connect: on. The server binds to 0.0.0.0 and accepts connections from any device on your network.

This means a fresh install of Beam Bench, on a network you share with others (office, coworking space, conference Wi-Fi, an unsegmented home network with guest devices), exposes an unauthenticated API that can move the machine and fire the laser to anyone on that network.

If you do not want network exposure, change the defaults from Settings → General:

1. Open the desktop app.
2. Edit → Settings → General.
3. Turn Allow network devices to connect off to bind to localhost only.
4. Or turn Local API off entirely to stop the server.

Changes take effect immediately; no restart needed.

Base URL

http://<host>:5900/api/v1

<host> is localhost (or 127.0.0.1) when Allow network devices to connect is off. When it is on, the server is reachable at the machine's LAN IP from any device on the network.

The port is configurable in Settings → General; 5900 is the default.

Authentication

None. The API has no token, no key, no login.

• With localhost binding, the OS-level access model is the boundary: any process on your machine can talk to the API.
• With network binding (the default), anyone on the same network can talk to the API. Treat that like running an open SMB share. Do not run Beam Bench in network-binding mode on untrusted Wi-Fi.

Request format

All POST/PATCH/PUT bodies are JSON:

Content-Type: application/json

Query strings are flat key=value. Path segments are URL-encoded as usual.

Response envelope

Successful responses return the resource body directly, no wrapper:

{
  "field": "value",
  "...": "..."
}

Errors return a uniform envelope:

{
  "error": {
    "code": "InvalidInput",
    "message": "Human-readable summary of what went wrong.",
    "details": { "...optional structured context..." }
  }
}

error.code is one of:

Confirmation-required errors

A small set of operations can move the machine or fire the laser. Those endpoints require an explicit confirmation flag in the request body. If missing, the API returns 428 Precondition Required:

{
  "error_code": "CONFIRMATION_REQUIRED",
  "missing": ["confirm_motion"],
  "message": "This command can move the machine and requires explicit confirmation."
}

Re-send the request with the named flag set to true. The flags currently in use are confirm_motion, confirm_laser_on, confirm_raw_gcode, and confirm_air_assist.

Endpoint groups

Per-resource reference pages are a work in progress; consult the agent capability schema in the meantime.

Discover the live surface

The fastest way to see what your installed version exposes:

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

This returns the full capability schema, including every endpoint, its parameters, and its response shape. The schema is the authoritative description; this page is a guide to it.

For state introspection:

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

For a written orientation on how to drive the app:

curl -s http://localhost:5900/api/v1/agent/guide

Versioning

All routes are under /api/v1. Breaking changes go in /api/v2 when they happen. Additive changes (new endpoints, new optional fields) ship in v1 without a version bump.

Related

• Using the HTTP API guide: a tutorial-style introduction with worked examples.
• How the CLI and app share state: the consistency model behind these endpoints.
• Settings → General: where to enable the API and pick the port.