openapi: 3.1.0 info: title: LightBurn / MillMage REST API version: 1.0.0 description: | REST API for LightBurn and MillMage. Provides file upload and import, read-only project and machine-state queries, cut-setting edits, and real-time state streaming via Server-Sent Events. ## Authentication All endpoints except `POST /api/connect` and `GET /` require a Bearer token derived from a shared secret using HMAC-SHA256: ``` token = hex(HMAC-SHA256(secret, floor(unix_time / 60))) ``` The server accepts tokens for the current minute and the previous minute to handle clock drift. ## Obtaining a Secret Obtain a shared secret by pairing a local application: - **Local application pairing (`POST /api/connect`)**: For localhost applications only. Sends an `application_name` in the request body. The application user is shown a consent dialog every time; if approved, a new secret is generated and returned. The dialog has a 30-second timeout after which the connection is automatically declined. Applications are responsible for persisting their own secret. Each call produces a distinct secret, even for the same `application_name`. ## Multiple instances The port is served by one running copy of the application at a time. If several copies are open, the one most recently brought to the foreground serves it; switching windows moves the listener, and a request made during the switch may fail to connect. Retry. A secret is recognised by the copy that was running when you paired, and may not be recognised by another copy until that one reloads its settings. If a previously working secret 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. servers: - url: http://localhost:19520 description: | LightBurn. Port 19520, fixed per product — not user-overridable. Binds loopback by default; enable "Allow API Access From Network" in Settings > Extensions to accept connections on any interface. `POST /api/connect` stays localhost-only either way. The API listens while LightBurn is open. With more than one copy of LightBurn running, the port is served by the most recently focused window — see the Multiple instances note in the description above. - url: http://localhost:19521 description: | MillMage. Port 19521, fixed per product — not user-overridable. Binds loopback by default; enable "Allow API Access From Network" in Settings > Extensions to accept connections on any interface. `POST /api/connect` stays localhost-only either way. The API listens while MillMage is open. With more than one copy of MillMage running, the port is served by the most recently focused window — see the Multiple instances note in the description above. security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: HMAC-SHA256 time-based token derived from shared secret schemas: ErrorResponse: type: object properties: error: type: string example: Missing 'axis' parameter Position: type: object description: | Always in mm, regardless of display units. An axis the controller doesn't report is omitted. properties: machine: type: object properties: x: { type: number, example: 100.000 } y: { type: number, example: 50.000 } z: { type: number, example: -5.000 } workpiece: type: object properties: x: { type: number, example: 0.000 } y: { type: number, example: 0.000 } z: { type: number, example: -5.000 } ConnectionStatus: type: object properties: connected: type: boolean description: > Whether a device link is open at this moment. On Ruida and some other non-GCode controllers the link is brought up just in time and closed again afterwards, so this is `false` whenever no transfer is in progress — which does not mean the laser is absent or unusable. Not a presence or health check; expect it to toggle around activity. How long a link is held open varies by controller and by how the device is connected. device_name: { type: string, example: Shapeoko 5 Pro } supports_z: { type: boolean } supports_overrides: { type: boolean } JogSettings: type: object properties: xy_distance: { type: number, example: 10.0 } z_distance: { type: number, example: 1.0 } xy_speed: { type: number, example: 1500.0 } z_speed: { type: number, example: 250.0 } units: type: string enum: [mm/s, mm/min, in/s, in/min] description: > The speed unit. Distances use `distance_units` — do not infer them from this field. distance_units: type: string enum: [mm, in] description: > The distance unit. Reported separately because the application supports mixed modes that pair inch distances with metric speeds. SavedPosition: type: object properties: index: { type: integer } name: { type: string } x: { type: number } y: { type: number } z: { type: number } include_z: { type: boolean } workpiece: { type: boolean } JobState: type: object properties: state: type: string enum: [idle, running, paused] description: > Whether the application is running a job on the controller. On Ruida controllers this is always `idle` — while the job file is being sent and while the machine cuts — because the controller runs the job on its own once it has the file, and the application does not track it. On Ruida, `idle` does not mean the machine is free; `device.laser.controller` on `GET /api/project` identifies the controller. progress: type: number minimum: 0 maximum: 100 description: > Percent complete. Optional — absent when not applicable: while `state` is `idle`, and on controllers that cannot report progress. Never present on Ruida controllers, whose `state` is always `idle`. Treat absence as "unknown", not as zero. Overrides: type: object properties: speed_percent: { type: integer, example: 100 } power_percent: { type: integer, example: 100 } AuxState: type: object properties: spindle_on: { type: boolean } spindle_rpm: { type: integer } coolant_on: { type: boolean } vacuum_on: { type: boolean } PollSnapshot: type: object properties: position: { $ref: '#/components/schemas/Position' } job: { $ref: '#/components/schemas/JobState' } overrides: { $ref: '#/components/schemas/Overrides' } aux: { $ref: '#/components/schemas/AuxState' } connection: { $ref: '#/components/schemas/ConnectionStatus' } settings: { $ref: '#/components/schemas/JogSettings' } Error: $ref: '#/components/schemas/ErrorResponse' Point2: type: object properties: x: { type: number } y: { type: number } LaserCut: type: object required: [index, name, kind, layer_index, enabled, priority, profile, params] properties: index: { type: integer } name: { type: string } kind: { type: string, enum: [normal, image] } layer_index: { type: integer } enabled: { type: boolean } priority: { type: integer } in_use: type: boolean description: > True if any shape in the project uses this cut setting. Counted per cut setting across every page, so a normal and an image cut sharing a layer are reported separately — which the per-layer count in `GET /api/layers` cannot do. shape_count: type: integer description: Number of shapes using this cut setting. profile: type: string enum: [galvo, gantry, unknown] description: > Which machine the settings should be read as. On `kind: "normal"` cuts it therefore says which of `params.galvo` / `params.gantry` is present; `kind: "image"` cuts carry a `profile` too but never a machine block. Derived from the selected device profile, so it is correct with no machine physically connected. `unknown` means no device profile has been set up yet. Switching the active device changes this, and the block that comes with it, for an unchanged project — do not cache the response shape. global_passes: type: integer minimum: 1 description: > Galvo only; absent otherwise. Repeats the entire sub-layer stack, so the real number of passes is `global_passes` multiplied by the per-layer `num_passes`. negative: { type: boolean } pass_through: { type: boolean } enable_cleanup: { type: boolean } sort_within_layer: { type: boolean } tabs: type: object description: Tab (bridge) settings for this cut. properties: enabled: { type: boolean } manual: { type: boolean, description: Manual placement rather than automatic. } size: { type: number } use_spacing: { type: boolean, description: "Use `spacing`; otherwise `count`." } count: { type: integer, description: "-1 when unset." } count_max: { type: integer, description: "-1 when unset." } limit_max: { type: boolean } spacing: { type: number } skip_inner: { type: boolean } cut_power: { type: number } mode: type: string enum: [cut, scan, offset, image, tool] description: Only present when `kind == "normal"`. params: description: Shape follows `kind`. anyOf: - $ref: '#/components/schemas/LaserCutParams' - type: object description: | Image cut params (when `kind == "image"`), plus the source and pulse fields of `LaserCutParams` except `min_power_2`. properties: speed: { type: number } max_power: { type: number } dpi: { type: number } dither_mode: { type: string } cells_per_inch: { type: number, description: Halftone cell size. } halftone_angle: { type: number } link_dpi_to_interval: { type: boolean } max_power_2: { type: number } laser1_enabled: { type: boolean } laser2_enabled: { type: boolean } alt_source: { type: boolean } q_pulse_width: { type: number } fiber_pulse_width: { type: integer } sub_layers: type: array description: | Only present when `kind == "normal"`. Additional sub-layers beyond the base layer; the base layer itself is reported in `mode` / `params` and is not repeated here. Empty when the layer has no sub-layers. items: type: object required: [index, name, enabled, mode, params] properties: index: type: integer minimum: 1 description: Sub-layer position within the cut (the base layer is 0). name: type: string description: User-assigned sub-layer name; may be empty. enabled: type: boolean description: Whether this sub-layer is output. mode: type: string enum: [cut, scan, offset, image, tool] params: $ref: '#/components/schemas/LaserCutParams' LaserCutParams: type: object description: | Vector cut params, shared by a cut's base layer and its sub-layers. Exactly one machine-specific block is present — `galvo` or `gantry`, matching the entry's `profile`. The other machine's values remain stored in the project but are not reported. When `profile` is `unknown`, neither block is present. properties: speed: { type: number } min_power: { type: number } max_power: { type: number } min_power_2: { type: number, description: Min power for laser 2 (dual-source). } max_power_2: { type: number, description: Max power for laser 2 (dual-source). } default_speed: { type: boolean, description: Use the device default speed. } default_power1: { type: boolean } default_power2: { type: boolean } laser1_enabled: { type: boolean, description: Laser 1 fires on this layer (dual-source). } laser2_enabled: { type: boolean, description: Laser 2 fires on this layer (dual-source). } alt_source: type: boolean description: Galvo only — use the alternate (second) laser source. num_passes: { type: integer, minimum: 1 } z_offset: { type: number } z_per_pass: { type: number, description: Z movement applied per pass. } u_offset: { type: number, description: For machines with a U axis. } angle_per_pass: { type: number, description: Scan angle rotation per pass, in degrees. } kerf: { type: number } frequency: type: integer description: Hz. Also the galvo pulse frequency when the device supports it. override_frequency: type: boolean description: > Whether `frequency` is applied at all. When false the device default is used and the reported `frequency` has no effect — set this alongside `frequency` when writing. q_pulse_width: type: number description: MOPA pulse width in ns (when `device.laser.mopa_source` is not 0). fiber_pulse_width: type: integer description: Fiber pulse width in ns, for gantry fiber sources (`laser1_fiber` / `laser2_fiber`). bi_directional: { type: boolean } cross_hatch: { type: boolean } flood_fill: { type: boolean } auto_rotate: { type: boolean, description: Continuous rotation between passes. } scan_opt: type: string enum: [individual, by_group, merge_all] description: How shapes are grouped when scanning. angle: { type: number, description: Scan angle in degrees. } interval: { type: number, description: Scan line interval. } dot_width: { type: number } use_dot_correction: { type: boolean } ramp_length: { type: number } ramp_outer: { type: boolean } perforate: { type: boolean } perf_len: { type: number } perf_skip: { type: number } tabs_enabled: { type: boolean } overscan: { type: boolean } overscan_percent: { type: number } galvo: $ref: '#/components/schemas/LaserGalvoParams' gantry: $ref: '#/components/schemas/LaserGantryParams' LaserGalvoParams: type: object description: > Present only when the entry's `profile` is `galvo`. `start_delay` and `end_delay` are dot delays on a galvo; the same names mean pauses in `LaserGantryParams`. properties: override_timings: type: boolean description: Gate for the timing constants below. laser_on_tc: { type: integer, description: Laser-on time constant, microseconds. } laser_off_tc: { type: integer, description: Laser-off time constant, microseconds. } end_tc: { type: integer, description: End time constant, microseconds. } polygon_tc: { type: integer, description: Polygon time constant, microseconds. } jump_speed: { type: number } min_jump_delay: { type: integer, description: Microseconds. } max_jump_delay: { type: integer, description: Microseconds. } jump_dist_limit: { type: number } start_delay: { type: number, description: Dot delay at path start. } end_delay: { type: number, description: Dot delay at path end. } wobble_enable: { type: boolean } wobble_step: { type: number } wobble_size: { type: number } LaserGantryParams: type: object description: > Present only when the entry's `profile` is `gantry`. `start_delay` and `end_delay` are pauses on a gantry; the same names mean dot delays in `LaserGalvoParams`. properties: run_blower: { type: boolean, description: Air assist. } auto_blower: { type: boolean } blower_speed_override: { type: boolean } blower_speed_percent: { type: number } cut_through_start: { type: boolean } cut_through_end: { type: boolean } through_power: { type: number } through_power_2: { type: number } start_delay: { type: number, description: Pause at path start. } end_delay: { type: number, description: Pause at path end. } lead_in: { type: boolean } lead_out: { type: boolean } lead_angle: { type: number, description: Degrees. } lead_length: { type: number } lead_style: { type: string, enum: [line, arc] } enable_ppi: { type: boolean } ppi: { type: integer, description: Pulses per inch. } dot_mode: { type: boolean } dot_time: { type: number } dot_spacing: { type: number } force_constant_power: { type: boolean } dcc_value: { type: number } overcut: { type: number } LaserCuts: type: object required: [product, cuts] properties: product: { type: string, enum: [lightburn] } cuts: type: array items: $ref: '#/components/schemas/LaserCut' CncCut: type: object description: | One MillMage operation. Operations attach to shapes, not layers, so there is no `layer_index`. There is no `priority` either: operations run in list order, which `index` already gives. required: [index, name, kind, shape_count, enabled, operation, tool] properties: index: type: integer description: Position in the project's operation list (use with `/api/cuts/{index}`). name: { type: string } kind: { type: string, enum: [normal] } shape_count: type: integer description: Number of shapes the operation is assigned to; 0 means unused. enabled: { type: boolean } operation: type: string enum: - profile - pocket - rest_pocket - drill - dogbone_slot - chamfer_profile - inlay_female - inlay_male - flute - surfacing - face - bore - relief - roughing - texturing - vcarve - vcarve_clear - image - invalid tool: type: object properties: name: { type: string } diameter: { type: number } feed_rate: { type: number } plunge_rate: { type: number } spindle_rpm: { type: number } settings: type: object description: | The operation's stored properties, keyed by schema name; the set depends on the operation type (e.g. `passDepth`, `feedRate`, `stepOver`, `vacuum`, `coolant`). Distances in mm, speeds in mm/s. Enum properties are names, e.g. `cutDirection: "climb"`. Lists every stored property, including some the operation dialog doesn't show for this type. additionalProperties: true example: { passDepth: 1.5, feedRate: 25, cutDirection: climb, whichSide: outside, vacuum: false } shared_fields: type: array items: { type: string } description: | `settings` keys taken from the linked primary operation (e.g. `startDepth`, `finalDepth`). Their values are the primary's, and they can only be changed on the primary. Empty if not linked. CncCuts: type: object required: [product, cuts] properties: product: { type: string, enum: [millmage] } cuts: type: array items: $ref: '#/components/schemas/CncCut' responses: Unauthorized: description: Missing or invalid Bearer token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized BadRequest: description: Invalid or missing parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' paths: /: get: summary: Placeholder HTML app security: [] responses: '200': description: HTML page content: text/html: schema: type: string /api/connect: post: summary: Request localhost application pairing description: | Allows a local application to request a shared secret for API access, scoped to a specific set of capabilities. Only accepts connections from localhost (127.0.0.1 / ::1). The user is shown a consent dialog listing the requesting application's name and the capabilities it has asked for. If they approve, a new shared secret is generated and returned, bound to that capability set for its lifetime. If they decline (or the 30-second timeout expires), the request is rejected with 403. Each approval produces a distinct secret; applications are responsible for persisting their own secret. Capabilities are immutable for the life of a token. To change scope, the application re-pairs (and the user re-approves a new dialog). ### Capability values | Wire string | Covers | |---|---| | `state` | Read-only machine and job state. `/api/status`, `/api/position`, `/api/jog/settings`, `/api/goto/saved`, `/api/units`, `/api/events`, `/api/events/poll`. | | `project` | Read-only project data. `/api/project`, `/api/layers`, `/api/cuts`, `/api/cuts/{index}`, `/api/material-library`. | | `upload` | Submit files for import. `/api/file/upload`, `/api/file/open`. | | `project_write` | Change project data. `POST /api/cuts/{index}`. | security: [] requestBody: required: true content: application/json: schema: type: object required: [application_name, capabilities] properties: application_name: type: string description: Display name shown to the user in the consent dialog example: My Automation Tool capabilities: type: array minItems: 1 description: | Capabilities the token should grant. Must be a non-empty array of known wire strings; unknown entries fail with 400. items: type: string enum: [state, project, upload, project_write] example: [state, project] responses: '200': description: Connection approved, secret returned content: application/json: schema: type: object properties: status: { type: string, example: ok } secret: type: string description: Shared secret for deriving Bearer tokens example: aB3dE7fG9hJ1kL5m '400': $ref: '#/components/responses/BadRequest' '403': description: Connection rejected by user, timed out, or not from localhost content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /api/status: get: summary: Connection status description: | When no machine is attached, `connected` and the `supports_*` flags are `false` and `device_name` still names the selected device profile. The endpoint always answers — it does not fail or return an empty body because nothing is connected. **`connected: false` does not mean the laser is unavailable.** On Ruida and some other non-GCode controllers the device link is opened just in time and closed again once the transfer finishes, so `false` is the normal resting state for a laser that is present, powered on and ready to run. It reports only whether LightBurn is actively exchanging data with the device at that moment. Treat `connected` as "a transfer is in progress", not as a presence or health check, and expect it to toggle around jobs and queries. Don't surface it to users as a fault or a disconnected machine. How long a link is held open varies by controller and by how the device is connected — a networked device may report differently from the same controller over USB — so don't infer a device's behaviour from this field. `device_name` is the reliable way to tell which device profile is selected. responses: '200': description: Current connection state and device capabilities content: application/json: schema: $ref: '#/components/schemas/ConnectionStatus' '401': $ref: '#/components/responses/Unauthorized' /api/position: get: summary: Current position snapshot responses: '200': description: Machine and workpiece coordinates content: application/json: schema: $ref: '#/components/schemas/Position' '401': $ref: '#/components/responses/Unauthorized' /api/jog/settings: get: summary: Get jog distance and speed settings responses: '200': description: Current jog settings in display units content: application/json: schema: $ref: '#/components/schemas/JogSettings' '401': $ref: '#/components/responses/Unauthorized' /api/goto/saved: get: summary: List saved positions responses: '200': description: Array of saved positions from device profile content: application/json: schema: type: object properties: positions: type: array items: $ref: '#/components/schemas/SavedPosition' '401': $ref: '#/components/responses/Unauthorized' /api/units: get: summary: Get current display units description: | The user's display units, as two independent axes: `units` is the speed unit, `distance_units` the distance unit. They are separate because the application's control-unit modes include mixed combinations — inch distances with metric speeds — that a single string cannot express. Read `distance_units` to convert distances; do not infer the distance unit from `units`. responses: '200': description: Current units content: application/json: schema: type: object properties: units: type: string enum: [mm/s, mm/min, in/s, in/min] distance_units: type: string enum: [mm, in] example: units: mm/min distance_units: mm '401': $ref: '#/components/responses/Unauthorized' /api/file/upload: post: summary: Upload a file to import description: | Send the file as the raw request body. Include the filename in the `X-Filename` header. Returns 202 immediately; the import result is reported asynchronously via the `file_imported` SSE event. parameters: - name: X-Filename in: header schema: type: string default: upload.lbrn2 description: Filename for the uploaded file - name: X-Group-Shapes in: header schema: type: string enum: ["true", "false"] default: "false" description: | When "true", imported shapes are kept as a group. When "false" (default), the application's global grouping preference applies. - name: X-Position-X in: header required: false schema: { type: number } description: | Optional X coordinate (workspace mm, workpiece origin) for the anchor point of the imported shapes' bounding box. Must be paired with `X-Position-Y`. When omitted, the import lands at the current view center (the default "drop point"). - name: X-Position-Y in: header required: false schema: { type: number } description: | Optional Y coordinate (workspace mm, workpiece origin). Must be paired with `X-Position-X`. - name: X-Origin in: header required: false schema: type: string enum: - top-left - top-center - top-right - middle-left - center - middle-right - bottom-left - bottom-center - bottom-right default: center description: | Which corner of the imported shapes' bounding box should be anchored at (`X-Position-X`, `X-Position-Y`). Ignored unless both position headers are present. Defaults to `center`. requestBody: required: true content: application/octet-stream: schema: type: string format: binary responses: '202': description: File received, import in progress content: application/json: schema: type: object properties: status: { type: string, example: accepted } filename: { type: string, example: design.svg } '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /api/file/open: post: summary: Upload a file and open it as the new project description: | Replaces the current project with the uploaded file (File → Open semantics). The current project is closed first; if it has unsaved changes the desktop shows the standard save-changes prompt before the open proceeds. Unlike `/api/file/upload`, no shapes are merged into the existing project — the project is replaced wholesale. Same authorization scope as `/api/file/upload` (`upload` capability). No position or grouping headers — irrelevant for the replace-project flow. Returns 202 immediately; the result is reported by the `file_imported` SSE event. **`success` is reliable only for native project files** — `.lbrn` / `.lbrn2` on LightBurn, `.mage` on MillMage. Opening a template (`.lbt`, `.mmt`) or any other format (SVG, DXF, images, …) reports `{"success": false}` with an `error` message even when the file opened correctly, so for those formats `false` does not distinguish success from failure. To confirm such an open, read `GET /api/project` after the event: a successful open leaves `filename` empty and `shape_count` counts the opened shapes. The `error` text is translated for display; don't match on it. `/api/file/upload` is not affected. parameters: - name: X-Filename in: header schema: type: string default: upload.lbrn2 description: Filename hint; picks the loader/translator. requestBody: required: true content: application/octet-stream: schema: type: string format: binary responses: '202': description: File received, open in progress content: application/json: schema: type: object properties: status: { type: string, example: accepted } filename: { type: string, example: project.lbrn2 } '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /api/project: get: summary: Current project metadata description: | Top-level read-only snapshot of the loaded project: filename, modified flag, shape count, workspace dimensions, and the connected device. `workspace` values are always in mm. `units` names the user's display units (`distance` is the translated UI label). With no project loaded, only `filename`, `modified` and `shape_count` are returned. responses: '200': description: Project metadata content: application/json: schema: type: object properties: filename: { type: string } modified: { type: boolean } shape_count: { type: integer } units: type: object properties: distance: { type: string, example: mm } speed: { type: string, example: mm/s } workspace: type: object properties: machine_size: $ref: '#/components/schemas/Point2' workpiece_size: $ref: '#/components/schemas/Point2' workpiece_offset: $ref: '#/components/schemas/Point2' machine_view: { type: boolean } device: type: object properties: name: { type: string } supports_z: { type: boolean } laser: type: object description: | LightBurn only, and only while a machine profile is loaded. Capabilities that decide which cut source/pulse fields apply. LightBurn doesn't classify CO2 / diode / fiber in general; `controller` is given so clients can infer. properties: controller: { type: string, example: Ruida } galvo: { type: boolean } flying_galvo: { type: boolean } uv: { type: boolean } sources: type: integer description: Laser sources the controller supports (2 = dual-source). sources_enabled: type: integer description: Sources enabled in the device settings. mopa_source: type: integer enum: [0, 1, 2] description: Which source is MOPA (0 = none); enables `q_pulse_width`. laser1_fiber: type: boolean description: Laser 1 is a fiber source (gantry); enables `fiber_pulse_width`. laser2_fiber: { type: boolean } '401': $ref: '#/components/responses/Unauthorized' /api/layers: get: summary: All 32 layer definitions description: | Returns every layer slot (not just the ones in use). Clients that want to display only used layers should filter on `in_use == true`. Colors are `"#RRGGBB"` hex strings for direct CSS use. responses: '200': description: Layers snapshot content: application/json: schema: type: object properties: active_index: type: integer description: Index of the currently selected layer, or -1. layers: type: array items: type: object properties: index: { type: integer } name: { type: string } color: type: string example: "#000000" pattern: "^#[0-9a-fA-F]{6}$" type: type: string enum: [normal, tool, none] hidden: { type: boolean } in_use: type: boolean description: True if any shape references this layer. shape_count: type: integer description: Number of shapes referencing this layer. '401': $ref: '#/components/responses/Unauthorized' /api/cuts: get: summary: Cut settings for all layers description: | Product-specific response: the payload shape differs between LightBurn (laser cuts + image cuts) and MillMage (CNC operations). Inspect the `product` field to dispatch client-side. Image cut settings are included inline in the LightBurn response with `kind: "image"`; regular cuts use `kind: "normal"`. Each entry's `index` is a dense global 0..N-1 position across both kinds in the returned array — use that value with `/api/cuts/{index}`. The `layer_index` field is separate from `index` and maps to the actual layer slot on the desktop. The LightBurn list is fixed-size, whether or not layers are in use: 30 cut layers, 2 tool layers (`mode: "tool"`), one internal virtual-array cut (`layer_index: -1`, not editable), then 30 image cuts. Use `/api/layers` `in_use` to find the layers in use. On MillMage, `cuts` is the project's operation list in order, and `index` is the operation's position in it. LightBurn values and the MillMage `tool` block use the user's display units; MillMage `settings` use mm and mm/s. Each LightBurn entry carries a `profile` of `galvo`, `gantry` or `unknown`. On `kind: "normal"` entries that comes with exactly one matching machine-specific block inside `params`; `kind: "image"` entries carry the `profile` but no block at all. The project stores both sets of settings whatever machine is selected, so the discriminator is what tells you which block the machine actually reads. It comes from the selected device profile and is correct with no machine connected. **Switching the active device changes the shape for an unchanged project — do not cache it.** Use each entry's `in_use` / `shape_count` to find the cut settings actually used by the project. Prefer these over joining `/api/layers` on `layer_index`: they are counted per cut setting across every page, so a normal and an image cut sharing a layer are reported separately, which the per-layer count cannot do. responses: '200': description: Cut settings snapshot content: application/json: schema: oneOf: - $ref: '#/components/schemas/LaserCuts' - $ref: '#/components/schemas/CncCuts' discriminator: propertyName: product '401': $ref: '#/components/responses/Unauthorized' /api/cuts/{index}: get: summary: Single cut setting by global flat index description: | `index` is the dense 0..N-1 value taken from an entry's `index` field in `/api/cuts` (normal cuts first, image cuts after). parameters: - name: index in: path required: true schema: { type: integer, minimum: 0 } responses: '200': description: Single cut entry (bare, not wrapped) content: application/json: schema: oneOf: - $ref: '#/components/schemas/LaserCut' - $ref: '#/components/schemas/CncCut' '401': $ref: '#/components/responses/Unauthorized' '404': description: Cut index out of range or slot is empty content: application/json: schema: $ref: '#/components/schemas/Error' post: summary: Update one cut setting (partial) description: | Changes the cut at the global flat `index` (the same index `GET` uses). Only the fields present in the body change. Requires the `project_write` capability. The whole body is validated first; on any error nothing changes. A successful change is one undoable step in the application ("Change cut settings") and marks the project modified. Values use the same display units `GET` reports. Changes are allowed while a job is running; a job already sent to the machine is not affected. An out-of-range `index` returns `404` whether or not the editor is open — the index is checked first. Editable fields (LightBurn): - `kind: "normal"` cuts: `name`, `enabled`, `mode` (`cut` / `scan` / `offset`), `params` (any `LaserCutParams` field), and existing `sub_layers` addressed by `index` (`name`, `enabled`, `mode`, `params`). Adding or removing sub-layers is not supported. - Cut-level fields: `negative`, `pass_through`, `enable_cleanup`, `sort_within_layer`, `tabs`, and `global_passes` on galvo. - `kind: "image"` cuts: `name`, `enabled`, and `params.speed`, `params.max_power`, `params.dither_mode` (one of the strings `GET` reports, e.g. `Stucki`), plus the source and pulse fields. `dpi` is read-only. - Powers (including `*_power_2`) are 0–100; `q_pulse_width` > 0; `fiber_pulse_width` a positive integer. Machine-specific settings go in `params.galvo` or `params.gantry`, and must match the entry's `profile`. Sending the block for the other machine is a **400** rather than being ignored, so a request cannot quietly fail to configure what you intended. `global_passes` is likewise a 400 on a gantry device. Set `params.override_frequency` alongside `params.frequency`: with the override false the device default applies and the frequency you write has no effect. Tool layers and internal cuts are rejected with 400. Editable fields (MillMage): `name`, `enabled`, and any `settings` key the operation reports, with the same JSON type (enums by name). `shared_fields` are rejected on linked secondaries. The operation's type, tool and shapes can't be changed. The response `index` can differ from the request if a linked chain is re-sorted. parameters: - name: index in: path required: true schema: { type: integer, minimum: 0 } requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: { type: string, minLength: 1 } enabled: { type: boolean } mode: { type: string, enum: [cut, scan, offset] } in_use: { type: boolean, readOnly: true } shape_count: { type: integer, readOnly: true } profile: { type: string, readOnly: true } global_passes: type: integer minimum: 1 description: Galvo only; a 400 on a gantry device. negative: { type: boolean } pass_through: { type: boolean } enable_cleanup: { type: boolean } sort_within_layer: { type: boolean } tabs: type: object description: Partial; only the keys sent are changed. params: type: object description: | `LaserCutParams` fields for normal cuts, including at most one of `galvo` / `gantry` matching the entry's `profile`; `speed`, `max_power`, `dither_mode` for image cuts. sub_layers: type: array items: type: object required: [index] additionalProperties: false properties: index: { type: integer, minimum: 1 } name: { type: string } enabled: { type: boolean } mode: { type: string, enum: [cut, scan, offset] } params: { $ref: '#/components/schemas/LaserCutParams' } settings: type: object description: MillMage only — see `CncCut.settings`. example: params: speed: 150 max_power: 65 override_frequency: true frequency: 20000 gantry: { run_blower: true, enable_ppi: true, ppi: 250 } tabs: { enabled: true, count: 4 } sub_layers: - { index: 1, enabled: false } responses: '200': description: Updated cut (same shape as `GET /api/cuts/{index}`) content: application/json: schema: oneOf: - $ref: '#/components/schemas/LaserCut' - $ref: '#/components/schemas/CncCut' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': description: Cut index out of range content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The cut settings / operation editor is open in the application content: application/json: schema: $ref: '#/components/schemas/Error' /api/overlay: get: summary: Camera overlay image description: | The camera overlay currently drawn on the workspace, as a PNG. **LightBurn only.** MillMage returns 404. Returns only what is already in memory — requesting this never makes the application capture a new frame. If no overlay is loaded the response is 404 with a JSON error body (note the error content type differs from the `image/png` success body). Orientation matches the application's **File → Save Background Capture** output. Use `GET /api/overlay/metadata` first if you want the size, placement or revision without transferring the image. responses: '200': description: The overlay image content: image/png: schema: type: string format: binary '401': $ref: '#/components/responses/Unauthorized' '404': description: No camera overlay image is loaded, or not LightBurn content: application/json: schema: $ref: '#/components/schemas/Error' /api/overlay/metadata: get: summary: Camera overlay metadata description: | Size, workspace placement and a change token for the camera overlay, without transferring the image. **LightBurn only.** Same 404 behaviour as `GET /api/overlay`, and likewise never triggers a capture. responses: '200': description: Overlay metadata content: application/json: schema: type: object properties: source: type: string enum: [overhead, head] description: Which camera layer the image came from. width: type: integer description: Image width in pixels. height: type: integer description: Image height in pixels. bounds: type: object description: Placement on the workspace, in mm. properties: x: { type: number } y: { type: number } width: { type: number } height: { type: number } revision: type: string description: > Opaque token that changes whenever the overlay is replaced. Use it to skip re-fetching an unchanged image. Not stable across application restarts — treat a changed value as "refetch", never as a persistent id. example: source: overhead width: 1018 height: 1074 bounds: { x: 46.421722, y: 26.932907, width: 162.619812, height: 171.565491 } revision: "43284680410162" '401': $ref: '#/components/responses/Unauthorized' '404': description: No camera overlay image is loaded, or not LightBurn content: application/json: schema: $ref: '#/components/schemas/Error' /api/material-library: get: summary: Loaded material / operations library description: | Returns the currently-loaded material library. Product-specific payload: LightBurn returns a single `CutLibrary` (the one selected in the library picker) as a flat list of entries; MillMage returns the set of loaded operations library files, each as a tree of folders and operations. Inspect the `product` field to dispatch client-side. On LightBurn, if no library is currently selected, `entries` is an empty array. responses: '200': description: Loaded library content: application/json: schema: oneOf: - type: object description: LightBurn (laser) material library. properties: product: { type: string, enum: [lightburn] } name: { type: string } filename: { type: string } entries: type: array items: type: object properties: guid: { type: integer } material: { type: string } description: { type: string } no_thick_title: type: string description: Title shown when `thickness` is -1. thickness: type: number description: Material thickness; -1 for "no thickness" entries. locked: { type: boolean } cut: allOf: - $ref: '#/components/schemas/LaserCut' description: > Same shape as one /api/cuts entry, with one exception: `index` and `layer_index` are both -1. A library entry has no position in the project's cut list, so neither field can be used with /api/cuts/{index}. - type: object description: MillMage (CNC) operations library. properties: product: { type: string, enum: [millmage] } libraries: type: array items: type: object properties: name: { type: string } filename: { type: string } content: type: object description: | The raw operations library file content as stored on disk (operations tree + version metadata). discriminator: propertyName: product '401': $ref: '#/components/responses/Unauthorized' /api/events: get: summary: SSE event stream description: | Server-Sent Events stream for real-time state updates. Connect via `fetch()` with an `Authorization` header (the browser `EventSource` API does not support custom headers). ### Event types | Event | Frequency | `data` | |-------|-----------|--------| | `position` | ~2 Hz | `Position` | | `job` | ~2 Hz | `JobState` | | `settings` | On change | `JogSettings` | | `overrides` | On change | `Overrides` | | `aux` | On change | `AuxState` | | `connection` | On change | `ConnectionStatus` | | `file_imported` | After `/api/file/upload` or `/api/file/open` | `{"success": bool, "error"?: string}` | The stream opens with a `:connected` comment, and a `:keepalive` comment is sent every 30 seconds. "On change" events are not re-sent to a new subscriber, so call `/api/events/poll` once after connecting to get the current state. responses: '200': description: SSE event stream content: text/event-stream: schema: type: string '401': description: Missing or invalid Bearer token (empty body) /api/events/poll: get: summary: Polling fallback description: | Returns the latest state snapshot as a single JSON object. Use this if SSE is unavailable. responses: '200': description: Complete state snapshot content: application/json: schema: $ref: '#/components/schemas/PollSnapshot' '401': $ref: '#/components/responses/Unauthorized'