Skip to content

API Overview

The LightBurn / MillMage REST API is an HTTP interface exposed by the desktop applications. It lets external programs read application and machine state, read project data, adjust cut settings, and submit files for import — over plain HTTP, on the loopback interface by default.

This page is the conceptual map. For step-by-step usage see Getting started; for the exhaustive contract see openapi.yaml.

Where the API lives

The API is served by the running desktop application — there is no separate server to start. It listens while the app is open:

Application Base URL
LightBurn http://localhost:19520
MillMage http://localhost:19521

These ports are fixed per product — there is no setting to change them.

The API binds to the loopback interface by default. To reach it from another machine, enable Settings → Extensions → Allow API Access From Network in the desktop application; the listener then accepts connections on any interface. On Windows this may prompt once for a firewall rule.

Pairing is the exception: POST /api/connect is always restricted to localhost, even with network access enabled, and returns 403 otherwise. A remote client must therefore be paired locally first, then use the resulting secret from wherever it runs. See Authentication.

Multiple instances

One running copy of the application serves the port at a time. Users can open several copies at once, which has two consequences worth coding for:

  • The listener follows the foreground window. Whichever copy was most recently brought to the front serves the port. Switching windows moves the listener, and a request issued during the switch may fail to connect — retry rather than treating it as fatal.
  • A secret belongs to the copy you paired with. Another copy may not recognise it until it reloads its settings. If a secret that was working starts returning 401 on a machine with several copies open, pair again rather than assuming it was revoked.

Neither applies to a single running instance, which serves the port for as long as it is open.

flowchart LR
    subgraph Desktop["Desktop machine"]
        App["LightBurn / MillMage<br/>(REST API listener)"]
        Local["Local app / script"]
        Local -- "HTTP + Bearer token" --> App
        Local -. "POST /api/connect<br/>(localhost only)" .-> App
    end
    subgraph Remote["Another machine (network access enabled)"]
        Far["Remote app / script"]
    end
    Far -- "HTTP + Bearer token" --> App
    App -- "consent dialog" --> User((User))

How a client interacts

  1. Pair once — POST /api/connect with an application name and the capabilities you need. The user approves a consent dialog; you receive a shared secret. Persist it.
  2. Authenticate every request — derive a short-lived Bearer token from the secret (HMAC-SHA256 over the current minute). See Authentication.
  3. Call endpoints within your granted capabilities — read state, read project data, change cut settings, or upload files.
sequenceDiagram
    participant C as Client
    participant A as LightBurn / MillMage
    participant U as User
    C->>A: POST /api/connect {name, capabilities}
    A->>U: Consent dialog
    U-->>A: Approve
    A-->>C: { secret }
    Note over C: store secret
    C->>A: GET /api/project  (Bearer token)
    A-->>C: workspace, units, device
    C->>A: POST /api/file/upload  (Bearer token)
    A-->>C: 202 Accepted

Capabilities

Access is scoped at pairing time to one or more capabilities. Request only what you need. See Capabilities for the per-endpoint breakdown.

Capability Grants
state Read-only machine and job state (status, position, units, events)
project Read-only project data (project, layers, cuts, material library)
upload Submit files for import (/api/file/upload, /api/file/open)
project_write Change project data — currently cut settings (POST /api/cuts/{index})

What the API is for

  • Reading application and machine state
  • Querying project and material information
  • Adjusting layer and operation cut settings
  • Submitting designs for import
  • Building companion apps, automation, and workflow integrations

What the API is not

  • Not a machine-control interface. The public API does not expose endpoints that move or operate machinery. Changing cut settings edits the project only — it doesn't start, stop or alter a job already sent to the machine.
  • Not a safety system. See ../SAFETY.md.
  • Not version-stable yet. Behaviour may change between application releases — see Versioning.

For supported API functionality that supplies or modifies operational parameters, the operator must review and verify the resulting job and its settings in LightBurn or MillMage before running it. See API-Modified Job Settings.

Real-time updates

State changes are available two ways: a Server-Sent Events stream (GET /api/events) and a polling fallback (GET /api/events/poll). Import results arrive as a file_imported event after an upload or open.

Position and job events stream at about 2 Hz; settings, overrides, aux and connection events are sent only when they change, and aren't replayed to a new subscriber. A client that opens the stream should call GET /api/events/poll once to learn the current state, then follow the stream from there.

sequenceDiagram
    participant C as Client
    participant A as LightBurn / MillMage
    C->>A: GET /api/events  (SSE)
    A-->>C: :connected
    C->>A: GET /api/events/poll
    A-->>C: current snapshot
    loop while connected
        A-->>C: position / job (~2 Hz)
        A-->>C: settings / overrides / aux / connection (on change)
        A-->>C: :keepalive (every 30 s)
    end

Units

Positions and the project workspace are always reported in mm. Cut values on LightBurn, the MillMage tool block, and jog settings use the user's display units, which GET /api/units reports as two independent fields — units for speed, distance_units for distance. They are separate because the application supports mixed modes that pair inch distances with metric speeds, so one cannot be inferred from the other. MillMage operation settings are always mm and mm/s. See Cut settings.

Next steps