HTTP API

This page documents the HTTP API exposed by the MAC server.

The OpenAPI spec is also available at /openapi.json on a running server, with interactive documentation at /docs (Swagger UI) and /redocs (ReDoc).

GET /api/

API index route.

Returns a placeholder message.

Status Codes:

  • 200 OK – Response body for GET /api/.

DELETE /api/machine/locked_out/{machine_name}

Set or clear machine lockout state.

POST to lock out a machine (prevent all use). DELETE to unlock the machine.

Parameters:

  • machine_name (string)

Status Codes:
POST /api/machine/locked_out/{machine_name}

Set or clear machine lockout state.

POST to lock out a machine (prevent all use). DELETE to unlock the machine.

Parameters:

  • machine_name (string)

Status Codes:
DELETE /api/machine/oops/{machine_name}

Set or clear machine Oops state.

POST to set the machine into Oops (maintenance needed) state. DELETE to clear the Oops state.

Parameters:

  • machine_name (string)

Status Codes:
POST /api/machine/oops/{machine_name}

Set or clear machine Oops state.

POST to set the machine into Oops (maintenance needed) state. DELETE to clear the Oops state.

Parameters:

  • machine_name (string)

Status Codes:
POST /api/machine/update

API method to update machine state.

Accepts POSTed JSON containing the following key/value pairs:

  • machine_name (string) - name of the machine sending the update

  • oops (boolean) - whether the oops button is pressed

  • rfid_value (string) - value of the RFID fob/card that is currently

    present in the machine, or empty string if none present. Note that ESPHome strips leading zeroes from this, so inside this method it is left-padded with zeroes to a length of 10 characters.

  • uptime (float) - uptime of the ESP32 (MCU).

  • wifi_signal_db (float) - WiFi signal strength in dB

  • wifi_signal_percent (float) - WiFi signal strength in percent

  • internal_temperature_c (float) - internal temperature of the ESP32 in

    °C.

  • amps (float; optional) - amperage value from the current clamp

    ammeter, if present, or 0.0 otherwise.

Status Codes:
POST /api/reload-users

Reload users configuration.

Hot-reloads users.json without requiring a server restart. Returns counts of removed, updated, and added users.

Status Codes:
GET /metrics

API method to return Prometheus-compatible metrics.

Second Relay Protocol Additions

POST /api/machine/update accepts an optional additive request field and emits an additive response field to support the per-machine second_relay configuration (see Second Relay (second_relay) — Optional):

  • Request — second_relay_state (boolean, optional): The actual current state of the second relay as known to the MCU. Reported by firmware that drives a second relay; older firmware omits this field. The server uses this for observability only and never for authorization decisions.

  • Response — second_relay (boolean, always emitted, defaults to false): Desired state of the second relay. For machines without second_relay configured this is always false. Firmware that does not know about this field simply ignores it.

The display field is byte-identical between pre-feature and post-feature servers for any given (machine, operator, machine state) tuple. second_relay configuration never causes LCD changes.

Prometheus Metrics

GET /metrics

Returns Prometheus-compatible metrics in text/plain format. This endpoint is not included in the OpenAPI spec as it does not return JSON.

For machines with second_relay configured, the following additional metrics are emitted (one sample per machine, with labels machine_name, display_name, and second_relay_alias):

  • machine_second_relay_state — whether the second relay is currently energized (0/1)

  • machine_second_relay_configured — always 1 for machines with a second_relay block

  • machine_second_relay_unauth_warn_only — the unauthorized_warn_only config flag (0/1)

  • machine_second_relay_always_enabled — the always_enabled config flag (0/1)

These metrics are not emitted at all for machines without second_relay, keeping cardinality minimal.

See dm_mac.views.prometheus for details on the available metrics.