Change settings

POST

/api/v1/settings

curl --request POST \
  --url http://pwrman.local/api/v1/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "port_priorities": [ 1, 2, 0, 3, 4, 5 ] }'

• Plain HTTP, the default
• HTTPS, once a certificate is installed and HTTPS is on

Send any subset of the keys. Keys left out keep their value, and unknown keys are ignored. The whole body is checked before anything changes, so one bad value changes nothing.

The device name, Wi-Fi, MQTT broker and addressing apply after POST /api/v1/reboot; the reply’s reboot_required says when one is needed. Everything else applies at once.

Posting an export back restores it. During first-time setup the body must be sent as application/json and must set token.

Authorizations

• token

Request Body^required

Media typeapplication/json

object

name

Device name, used for <name>.local and the MQTT topics.

string

<= 31 characters /^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$/

wifi_ssid

string

<= 32 characters

mqtt_host

MQTT broker; empty turns MQTT off.

string

<= 63 characters

mqtt_port

integer

>= 1 <= 65535

mqtt_user

string

<= 32 characters

mqtt_tls

Connect to the broker over TLS.

boolean

mqtt_tls_verify

With mqtt_tls, check the broker’s certificate.

boolean

mqtt_ca

The broker’s CA certificate as PEM, up to 2048 bytes as DER; empty for none. Without one a verified link trusts the Let’s Encrypt roots.

string

contract_steps

A contract event for every voltage step a PPS or SPR AVS sink takes. Off, the event comes only when the sink switches to that range or away from it.

boolean

ip_mode

string

Allowed values: dhcp static

ip

Static address, as a dotted quad or empty.

string

netmask

string

gateway

string

dns

DNS server; empty uses the one DHCP names (the gateway with static addressing).

string

ntp_server

Time server; empty uses the one DHCP names, or time.cloudflare.com.

string

<= 63 characters

hostnames

Extra host names the web server answers to, separated by spaces. Commas are also accepted when writing.

string

syslog_host

Syslog server; empty sends no syslog.

string

<= 63 characters

syslog_port

integer

>= 1 <= 65535

update_url

Update source, as http://host[:port][/path] without a trailing slash; empty never checks.

string

<= 63 characters

update_auto

New releases install by themselves.

boolean

auth_read

Also require the API token to read status, the fault log, the certificate details and Prometheus metrics.

boolean

budget_w

The power budget, in watts.

integer

>= 15 <= 600

fan_mode

string

Allowed values: auto on off

fan_on_w

Automatic mode turns the fan on at this total power, in watts.

integer

>= 1 <= 1000

fan_off_w

Automatic mode turns the fan off at this total power, in watts. Must be below fan_on_w.

integer

<= 1000

fan_on_ma

Automatic mode also runs the fan while any contract is above this current, in mA; 0 turns this off.

integer

<= 10000

charged_mw

A device drawing less than this, in mW, for charged_min minutes counts as charged; 0 turns this off.

integer

<= 20000

charged_min

integer

>= 1 <= 255

led_brightness

integer

<= 255

led_boot

The light sweep at power-up.

string

Allowed values: white rainbow

led_dim

Brightness during the night window and when idle.

integer

<= 255

led_night

Night window as HH:MM-HH:MM local time; empty for none.

string

led_idle_min

Dim after this many minutes without a port event; 0 never.

integer

<= 1440

tz_offset_min

Local time minus UTC, in minutes.

integer

>= -720 <= 840

blade_boot_via_loader

Set each blade, once, to start through its bootloader, so the controller can update it.

boolean

blade_watch_s

A switched-off blade the controller has not addressed for this many seconds restarts into its bootloader; 0 never.

integer

<= 255

port_names

Port names; empty for the default name.

Array<string>

<= 6 items

port_limits_w

Power limit per port, in watts.

Array<integer>

<= 6 items

port_max_v

The highest voltage each port offers.

Array<integer>

<= 6 items

Allowed values: 5 9 12 15 20

port_priorities

Priority per port; 0 is the most important.

Array<integer>

<= 6 items

port_boot

Each port’s state at power-up.

Array<string>

<= 6 items

Allowed values: on off last

port_auto_off

1 switches the port off once its device is charged.

Array<integer>

<= 6 items

Allowed values: 0 1

port_sleep_min

Switch the port off this many minutes after a device connects; 0 never.

Array<integer>

<= 6 items

wifi_pass

string

<= 64 characters

mqtt_pass

string

<= 64 characters

token

The API token; printable ASCII without spaces.

string

<= 32 characters /^[!-~]+$/

https

Turn HTTPS on or off. Needs an installed certificate.

boolean

Examples

Make port 3 the most important

{
  "port_priorities": [
    1,
    2,
    0,
    3,
    4,
    5
  ]
}

Name the first two ports

{
  "port_names": [
    "Laptop",
    "Phone"
  ]
}

Responses

200

Saved.

Media typeapplication/json

object

ok

required

boolean

reboot_required

required

A changed setting takes effect after POST /api/v1/reboot.

boolean

Example

{
  "ok": true,
  "reboot_required": false
}

400

A value is out of range or malformed. Nothing was changed.

Media typeapplication/json

object

error

required

Why the request was refused, in words.

string

Examples

{
  "error": "port_limits_w: 5-100 W each"
}

{
  "error": "https: install a certificate first (POST /api/v1/tls)"
}

{
  "error": "set an API token to finish setup"
}

401

The token is missing or wrong. On a controller with no token yet, the error says how to open first-time setup.

Media typeapplication/json

object

error

required

Why the request was refused, in words.

string

Examples

{
  "error": "bearer token required"
}

{
  "error": "no API token yet: Wi-Fi setup unlocks settings for an hour, or connect Ethernet"
}

415

A request let in by first-time setup was not sent as JSON.

Media typeapplication/json

object

error

required

Why the request was refused, in words.

string

Example

{
  "error": "settings must be sent as application/json"
}

500

The settings could not be saved.

Media typeapplication/json

object

error

required

Why the request was refused, in words.

string

Example

{
  "error": "flash save failed"
}