Manage a device: Wi-Fi, settings, restarts and firmware

Much of what you do on a device's page in the partner portal, you can do from your own systems too: rename it, change its Wi-Fi, restart it, keep its firmware current, back it up and leave notes for your team.

Every call here takes the device's id, which you get from GET/v1/devices — see Track orders and the devices they ship.

Before you start

Reading a device's settings needs devices:read; changing anything needs devices:write. Your account needs the Devices module, and a few calls also need a capability switched on for your account:

Without a capability you get a 403 with the code not_entitled. GET/v1/me lists what your account has under entitlements.devices.

What an action response means

Restarts, firmware updates, resets and backups answer 202 with the same small body:

{
  "object": "device_action",
  "action": "restart",
  "device_id": "0d5102c1-b8d2-4ba4-b6aa-43ed91d768c0",
  "status": "accepted",
  "requested_at": "2026-08-04T21:15:40.000Z"
}

accepted means the request reached the device platform, not that the device has finished. Read the device again later to see the result.

Rename a device

Give a device a label your team will recognize with PATCH/v1/devices/{uuid}:

curl https://cloud.mergewifi.com/v1/devices/0d5102c1-b8d2-4ba4-b6aa-43ed91d768c0 \
  -X PATCH \
  -H "Authorization: Bearer $MERGEWIFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Warehouse dock 3" }'

The response is the device as we last synced it, so the new label can take up to 15 minutes to show. The same call changes a device's data plan or network group — that's covered in Start service.

Change the Wi-Fi name and password

GET/v1/devices/{uuid}/wifi reads the network name straight from the device. The password is never returned; password_set tells you whether there is one.

curl https://cloud.mergewifi.com/v1/devices/0d5102c1-b8d2-4ba4-b6aa-43ed91d768c0/wifi \
  -H "Authorization: Bearer $MERGEWIFI_API_KEY"

{ "object": "device_wifi", "ssid": "Acme-Warehouse", "password_set": true }

Change either or both with PATCH/v1/devices/{uuid}/wifi. Send ssid, password, or both:

curl https://cloud.mergewifi.com/v1/devices/0d5102c1-b8d2-4ba4-b6aa-43ed91d768c0/wifi \
  -X PATCH \
  -H "Authorization: Bearer $MERGEWIFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ssid": "Acme-Warehouse" }'

The change is applied to the hardware and takes effect when the device next checks in.

Restart it, now or on a schedule

POST/v1/devices/{uuid}/actions/restart reboots the device straight away. It's offline for a minute or so while it comes back.

curl https://cloud.mergewifi.com/v1/devices/0d5102c1-b8d2-4ba4-b6aa-43ed91d768c0/actions/restart \
  -X POST \
  -H "Authorization: Bearer $MERGEWIFI_API_KEY"

To restart it regularly, set a schedule with PATCH/v1/devices/{uuid}/restart_schedule. A device has one schedule at most, so this creates it or replaces the one there.

curl https://cloud.mergewifi.com/v1/devices/0d5102c1-b8d2-4ba4-b6aa-43ed91d768c0/restart_schedule \
  -X PATCH \
  -H "Authorization: Bearer $MERGEWIFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "frequency": "daily", "time": "03:00" }'

• frequency is daily or monthly.
• time is 24-hour HH:MM, in the device's local time.
• day is required for monthly: the day of the month. Months shorter than the day you pick may restart on the last day instead.

The device is offline for one to two minutes each time a scheduled restart runs, so pick a time when nobody's using it. To stop restarting, call DELETE/v1/devices/{uuid}/restart_schedule. It answers 204, even if there was no schedule.

Firmware, backups and factory reset

Update firmware with POST/v1/devices/{uuid}/actions/update_firmware. The device fetches the latest firmware on its own schedule and restarts to apply it, so expect it to be offline for a few minutes.

curl https://cloud.mergewifi.com/v1/devices/0d5102c1-b8d2-4ba4-b6aa-43ed91d768c0/actions/update_firmware \
  -X POST \
  -H "Authorization: Bearer $MERGEWIFI_API_KEY"

Back up its configuration with POST/v1/devices/{uuid}/config_backups. The backup finishes in the background, so check GET/v1/devices/{uuid}/config_backups for it afterwards. Taking a second backup does no harm, so retrying is safe.

curl https://cloud.mergewifi.com/v1/devices/0d5102c1-b8d2-4ba4-b6aa-43ed91d768c0/config_backups \
  -X POST \
  -H "Authorization: Bearer $MERGEWIFI_API_KEY"

Restoring a backup is a support operation and isn't available through the API. Contact support@mergewifi.com if you need one restored.

Reset to factory settings with POST/v1/devices/{uuid}/actions/factory_reset. This wipes the Wi-Fi name, LAN addressing and every networking rule on the device, and it can't be undone.

curl https://cloud.mergewifi.com/v1/devices/0d5102c1-b8d2-4ba4-b6aa-43ed91d768c0/actions/factory_reset \
  -X POST \
  -H "Authorization: Bearer $MERGEWIFI_API_KEY"

Keep notes on a device

Notes are a shared logbook for the device. Add one with POST/v1/devices/{uuid}/notes — it answers 204 with no body:

curl https://cloud.mergewifi.com/v1/devices/0d5102c1-b8d2-4ba4-b6aa-43ed91d768c0/notes \
  -X POST \
  -H "Authorization: Bearer $MERGEWIFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Relocated to dock 3" }'

Read them back with GET/v1/devices/{uuid}/notes. Each one comes as a reading with kind: "note", and the note itself is inside data. Notes can come from our team as well as yours, and who wrote each one isn't included.

Related: Start service · Port forwarding, dedicated IPs and bridged IPs · Diagnose a device · Track orders and the devices they ship