Power Strip Management endpoints

Create, list, update, delete, and test for characteristics of power strips.

functionality	method	endpoint
list power strips	GET	`/powerstrip/network/<network-id>/list`
create power strip	POST	`/powerstrip/network/<network-id>`
get power strip	GET	`/powerstrip/<powerstrip-id>`
update power strip	PUT	`/powerstrip/<powerstrip-id>`
delete power strip	DELETE	`/powerstrip/<powerstrip-id>`
get power strip usage	GET	`/powerstrip/<powerstrip-id>/usage`
checkin power strip	GET	`/powerstrip/<powerstrip-id>/checkin`
reboot power strip	GET	`/powerstrip/<powerstrip-id>/reboot`
pair power strip	GET	`/powerstrip/<powerstrip-id>/enable_pairing`
reset port	GET	`/powerstrip/<powerstrip-id>/port/<port-number>/reset`
list power-strip-related network settings	GET	`/powerstrip/network/<network-id>/settings`
update power-strip-related network settings	PUT	`/powerstrip/network/<network-id>/settings`
expedite upgrade for network power strip	GET	`/powerstrip/network/<networkid-id>/expedite_upgrade`
list allowed firmware	GET	`/powerstrip/network/<network-id>/firmware_versions`

list power strips

GET /powerstrip/network/<network-id>/list

Retrieve a list of all power strips belonging to the given network, with detailed information.

example request

GET https://api-v3.cloudtrax.com/powerstrip/network/12345/list

output

The API either returns HTTP status code 200 (success) or an HTTP error and JSON describing the error(s) in the case of failure. On success, the API returns a JSON package with a list of the switches.

example output

{
  "powerstrips": [
    {
      "powerstrip_id": 1,
      "mac": "ac:86:74:00:00:00",
      "name": "Pat's Desk MP60",
      "model": "P60",
      "ip": "",
      "created": "2018-03-23T17:12:16Z",
      "firmware_version": "6.4.6-c3b6f768496b73473b45a06b478bf2e75c6cdd5e",
      "enabled_ports": 6,
      "port_count": 6,
      "last_checkin": "2018-04-30T19:29:11.232Z",
      "need_pairing": false,
      "cloud_status": "up",
      "role": "repeater",
      "mesh_ip": "1.1.1.1",
      "surge_protection_active": true,
      "voltage_v": 116,
      "frequency_hz": 60,
      "uptime_seconds": 1024671,
      "active_ports": 3
    },
    {
      "powerstrip_id": 2,
      "mac": "ac:86:74:00:00:01",
      "name": "PS test 1",
      "model": "MP60",
      "ip": null,
      "created": "2018-04-23T23:08:41Z",
      "firmware_version": "",
      "enabled_ports": 6,
      "port_count": 6,
      "last_checkin": "",
      "need_pairing": false,
      "cloud_status": "down",
      "role": "repeater",
      "mesh_ip": "",
      "surge_protection_active": false,
      "voltage_v": 0,
      "frequency_hz": 0,
      "uptime_seconds": 0,
      "active_ports": 0
    }
  ]
}

create power strip

POST /powerstrip/network/<network-id>

Create a new power strip entry for the specified network, with characteristics defined by the JSON package in the body of the HTTP Request.

example request

POST https://api-v3.cloudtrax.com/powerstrip/network/12345

output

The API either returns HTTP status code 200 (success) or an HTTP error and JSON describing the error(s) in the case of failure. On success, the API returns a JSON package containing the id of the created switch.

example input

{
    "mac": "ac:86:74:00:00:01",
    "name": "garage",
    "description" : "some description",
    "model" : "model",
    "confirm_transfer":true
}

example output

{
 	"powerstrip_id" : 123456
}

get power strip

GET /powerstrip/<powerstrip-id>

Retrieve a power strip.

example request

GET https://api-v3.cloudtrax.com/powerstrip/123456

example output

{
  "powerstrip_id": 1,
  "network_id": 123,
  "mac": "ac:86:74:00:00:00",
  "name": "Pat's Desk MP60",
  "description": "",
  "model": "P60",
  "created": "2018-03-23T17:12:16Z",
  "firmware_version": "6.4.6-c3b6f768496b73473b45a06b478bf2e75c6cdd5e",
  "enable_pairing": false,
  "enable_power_switch": false,
  "enable_connection_check": false,
  "enable_connection_check_during_maintenance": false,
  "connection_check_max_retries": 0,
  "connection_check_time_between_retries": 60,
  "enable_mesh": false,
  "last_modified": "2018-04-30T20:29:17Z",
  "ip": "",
  "last_checkin": "2018-04-30T20:29:17.26Z",
  "need_pairing": false,
  "cloud_status": "up",
  "role": "repeater",
  "mesh_ip": "1.1.1.1",
  "surge_protection_active": true,
  "voltage_v": 115,
  "frequency_hz": 60,
  "uptime_seconds": 1028276,
  "active_ports": 3,
  "ports": [
    {
      "port_id": 1,
      "label": "Device A",
      "enable": true,
      "connection_check_name": null,
      "current_a": 0.1,
      "apparent_power_va": 16.4,
      "active_power_w": 8.5,
      "reactive_power_var": 1.7,
      "power_factor": 0.51
    },
    {
      "port_id": 2,
      "label": "2",
      "enable": true,
      "connection_check_name": null,
      "current_a": 0,
      "apparent_power_va": 0,
      "active_power_w": 0,
      "reactive_power_var": 0,
      "power_factor": 0
    },
    {
      "port_id": 3,
      "label": "Laptop Hub",
      "enable": true,
      "connection_check_name": null,
      "current_a": 0.2,
      "apparent_power_va": 31.4,
      "active_power_w": 19.3,
      "reactive_power_var": 2.4,
      "power_factor": 0.61
    },
    {
      "port_id": 4,
      "label": "Monitor ",
      "enable": true,
      "connection_check_name": null,
      "current_a": 0.3,
      "apparent_power_va": 35.9,
      "active_power_w": 25.5,
      "reactive_power_var": 3.1,
      "power_factor": 0.71
    },
    {
      "port_id": 5,
      "label": "More",
      "enable": true,
      "connection_check_name": null,
      "current_a": 0,
      "apparent_power_va": 0,
      "active_power_w": 0,
      "reactive_power_var": 0,
      "power_factor": 0
    },
    {
      "port_id": 6,
      "label": "6",
      "enable": true,
      "connection_check_name": null,
      "current_a": 0,
      "apparent_power_va": 0,
      "active_power_w": 0,
      "reactive_power_var": 0,
      "power_factor": 0
    }
  ],
  "schedule": [
    {
      "powerstrip_port_schedule_id": 67523,
      "port_ids": [
        3,
        4
      ],
      "days_of_week": [
        "fri"
      ],
      "hour": 18,
      "minute": 0,
      "action": "port_disable"
    },
    {
      "powerstrip_port_schedule_id": 349834,
      "port_ids": [
        3,
        4
      ],
      "days_of_week": [
        "mon"
      ],
      "hour": 7,
      "minute": 30,
      "action": "port_enable"
    },
    {
      "powerstrip_port_schedule_id": 876324234,
      "port_ids": [
        3
      ],
      "days_of_week": [
        "mon",
        "tue",
        "wed",
        "thu",
        "fri"
      ],
      "hour": 7,
      "minute": 45,
      "action": "port_reset"
    }
  ],
  "connection_checks": [
    {
      "connection_check_name": "  test",
      "hostname_1": "nist.gov",
      "hostname_2": null,
      "hostname_3": null,
      "hostname_4": null
    },
    {
      "connection_check_name": "Default List",
      "hostname_1": "google.com",
      "hostname_2": "amazon.com",
      "hostname_3": "datto.com",
      "hostname_4": "facebook.com"
    }
  ]
}

update power strip

PUT /powerstrip/<powerstrip-id>

Change the settings for an existing power strip.

example request

PUT https://api-v3.cloudtrax.com/powerstrip/12345

example input

{
  "name": "Pat's Desk MP60",
  "description": "",
  "enable_pairing": false,
  "enable_power_switch": false,
  "enable_connection_check": false,
  "enable_connection_check_during_maintenance": false,
  "connection_check_max_retries": 0,
  "connection_check_time_between_retries": 60,
  "enable_mesh": false,
  "ports": [
    {
      "port_id": 1,
      "label": "Device A",
      "enable": true,
      "connection_check_name": "test"
    },
    {
      "port_id": 2,
      "label": "2",
      "enable": true,
      "connection_check_name": "Default List"
    },
    {
      "port_id": 3,
      "label": "Laptop Hub",
      "enable": true,
      "connection_check_name": null
    },
    {
      "port_id": 4,
      "label": "Monitor ",
      "enable": true,
      "connection_check_name": null
    },
    {
      "port_id": 5,
      "label": "More",
      "enable": true,
      "connection_check_name": null
    },
    {
      "port_id": 6,
      "label": "6",
      "enable": true,
      "connection_check_name": null
    }
  ],
  "schedule": [
    {
      "port_ids": [
        3,
        4
      ],
      "days_of_week": [
        "fri"
      ],
      "hour": 18,
      "minute": 0,
      "action": "port_disable"
    }
  ],
  "connection_checks": [
    {
      "connection_check_name": "  test",
      "hostname_1": "nist.gov",
      "hostname_2": null,
      "hostname_3": null,
      "hostname_4": null
    },
    {
      "connection_check_name": "Default List",
      "hostname_1": "google.com",
      "hostname_2": "amazon.com",
      "hostname_3": "datto.com",
      "hostname_4": "facebook.com"
    }
  ]
}

delete power strip

DELETE /powerstrip/<powerstrip-id>

Delete an existing power strip.

example request

DELETE https://api-v3.cloudtrax.com/powerstrip/123456

output

The API returns either an HTTP status code 200 on success or an HTTP error and JSON describing the error(s) in the case of a failure.

get power strip usage

GET /powerstrip/<powerstrip-id>/usage?period=<period>

Retrieve a power strip usage data.

query-string arguments

argument	allowable values	required	note
`period`	`2hours`, `day`, `week`, `month`	optional	default is `day`

example request

GET https://api-v3.cloudtrax.com/powerstrip/123456/usage?period=day

example output

{
  "usage": [
    {
      "time": "2018-04-29T23:00:00Z",
      "ports": {
        "1": {
          "active_power_w": 8,
          "voltage_v": 118,
          "current_a": 0.1
        },
        "2": {
          "active_power_w": 0,
          "voltage_v": 118,
          "current_a": 0
        },
        "3": {
          "active_power_w": 0,
          "voltage_v": 118,
          "current_a": 0
        },
        "4": {
          "active_power_w": 0,
          "voltage_v": 118,
          "current_a": 0
        },
        "5": {
          "active_power_w": 0,
          "voltage_v": 118,
          "current_a": 0
        },
        "6": {
          "active_power_w": 0,
          "voltage_v": 118,
          "current_a": 0
        }
      },
      "memory_available": 0,
      "role": ""
    },
    ...
  ]
}

checkin power strip

GET /powerstrip/<powerstrip-id>/checkin

Check in a power strip to the cloud.

example request

GET https://api-v3.cloudtrax.com/powerstrip/123456/checkin

output

The API returns either an HTTP status code 200 on success or 4xx in the case of a failure.

reboot power strip

GET /powerstrip/<powerstrip-id>/reboot

Reboot a power strip.

example request

GET https://api-v3.cloudtrax.com/powerstrip/123456/reboot

output

The API returns either an HTTP status code 200 on success or 4xx in the case of a failure.

pair power strip

GET /powerstrip/<powerstrip-id>/checkin

Pair a power strip to the cloud.

example request

GET https://api-v3.cloudtrax.com/powerstrip/123456/enable_pairing

output

The API returns either an HTTP status code 200 on success or 4xx in the case of a failure.

reset port

GET /powerstrip/<powerstrip-id>/port/<port-number>/reset

Reset a port.

example request

GET https://api-v3.cloudtrax.com/powerstrip/123456/port/1/reset

output

The API either returns HTTP status code 200 (success) or an HTTP error and JSON describing the error(s) in the case of failure.

list power-strip-related network settings

GET /powerstrip/network/<network_id>/settings

example request

GET https://api-v3.cloudtrax.com/powerstrip/network/123456/settings

output

The API either returns HTTP status code 200 (success) if the request is successful, along with a JSON package of the settings, otherwise an error explaining what prevented the operation in the case of failure.

example output

{
  "enable_power_switch": false,
  "enable_mesh": false,
  "enable_upgrade": false,
  "firmware_tag": "stable"
}

Top level properties

field	description
`enable_power_switch`	indicates whether the power switches on the power strips will function.
`enable_mesh`	indicates whether the power strips on this network will mesh.
`enable_upgrade`	indicates whether the power strips on this network will automatically upgrade their firmware.
`firmware_tag`	lists the firmware currently running on each switch model on this network.

output

On success the API responds with a status code 200. In the case of an error, the API responds with an explanation in JSON.

update power-strip-related network settings

PUT /powerstrip/network/<network_id>/settings

example request

PUT https://api-v3.cloudtrax.com/powerstrip/network/123456/settings

example input

{
  "enable_power_switch": false,
  "enable_mesh": false,
  "enable_upgrade": false,
  "firmware_tag": "stable"
}

JSON detail

fields	type	description	required
`enable_power_switch`	bool	If true, this network's power strips power switches will do something when pressed. 🔸Example value: `true` 🔸Allowed entries: `true/false`	optional
`enable_mesh`	bool	If true, this network's power strips will mesh. 🔸Example value: `true` 🔸Allowed entries: `true/false`	optional
`enable_upgrade`	bool	If true, this network's switches will automatically upgrade their firmware. 🔸Example value: `"comm1"` 🔸Allowed entries: `true/false`	optional
`firmware_tag`	string	Which firmware should run on the associated model of switch. 🔸Example value: `"phase1"` 🔸Allowed chars: `a-z, 0-9`	optional

expedite upgrade for switch

GET /powerstrip/network/<network-id>/expedite_upgrade

If upgrades are not disabled, this flag forces an update for all power strips on the network outside the normally scheduled maintenance window.

example request

GET https://api-v3.cloudtrax.com/powerstrip/network/123456/expedite_upgrade

output

The API either returns HTTP status code 200 (success) or an HTTP error and JSON describing the error(s) in the case of failure.

list allowed firmware

GET /powerstrip/network/<network_id>/firmware_versions

example request

GET https://api-v3.cloudtrax.com/powerstrip/network/123456/firmware_versions

output

The API returns a list of allowed firmware for the network.

example output

{
  "firmware_versions": [
    {
      "tag_id": "1",
      "tag": "stable",
      "build": ""
    },
    {
      "tag_id": "6",
      "tag": "beta",
      "build": ""
    }
  ]
}

Files

powerstrip_management.md

Latest commit

History

powerstrip_management.md

File metadata and controls

Power Strip Management endpoints

list power strips

example request

output

example output

create power strip

example request

output

example input

example output

get power strip

example request

example output

update power strip

example request

example input

delete power strip

example request

output

get power strip usage

query-string arguments

example request

example output

checkin power strip

example request

output

reboot power strip

example request

output

pair power strip

example request

output

reset port

example request

output

list power-strip-related network settings

example request

output

example output

Top level properties

output

update power-strip-related network settings

example request

example input

JSON detail

expedite upgrade for switch

example request

output

list allowed firmware

example request

output

example output