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.

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.

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