SynLink Web HTTP(S) API

Table Of Contents

Overview

Control SynLink PDUs with the SynLink Web API (Application Programming Interface).

Examples within this guide use the curl command on Linux OS Ubuntu 18.04. curl is available for download via sudo apt install curl on Linux OS's that support Apt Package Manager. Testing the API is possible with Postman on Mac, Windows, or Linux Operating Systems. Endpoints Post bodys and output responses use JSON (Javascript Object Notation).

Libraries

NodeJS API Wrapper tools available via NPM

npm install synlink-pdu

Python API Wrapper tools available via PIP

pip install synlinkpy

Authentication

Session Based

Session Based Authentication involves using the /login route to generate a session token.

Sending a Post Request to /login with username and password will return a User Object and a session token inside the Token header

Example Request For Session Token

> curl 192.168.1.100/login -i -d '{"username":"admin","password":"admin"}'

HTTP/1.1 200 OK
Content-Type: application/json
Token: 4jDv3lag56ADoih2bzd
Set-Cookie: SPID=4jDv3lag56ADoih2bzd; path=/
Connection: close

{"username":"admin","id":"1","lastLogin":1325659007,"created":1617325133,"roleId":1,"role":{"id":1,"name":"Administrator","description":"All Permissions. At minimum need one administrator role at any time. Not Editable.","permissions":{"viewInletStats":true,"modifyInletStats":true,"viewBankStats":true,"modifyBankStats":true,"viewEventActions":true,"modifyEventActions":true,"viewNetworkSettings":true,"modifyNetworkSettings":true,"modifyLcdSettings":true,"modifyPortSettings":true,"modifyFirmwareVersion":true,"viewUsersList":true,"modifyUsers":true,"allowFactoryReset":true,"allowPduRestart":true,"modifyGlobalDeviceSettings":true,"viewGlobalDeviceSettings":true,"viewPortInfo":true,"viewOutletGroups":true,"modifyOutletGroups":true,"viewOutlets":["1-16777225","2-16777225","3-16777225","4-16777225","5-16777225","6-16777225","7-16777225","8-16777225"],"modifyOutlets":["1-16777225","2-16777225","3-16777225","4-16777225","5-16777225","6-16777225","7-16777225","8-16777225"]}}}

Personal Access Token Based

Personal Access Token authentication involves manually creating a personal access token and using it in each request to the SynLink HTTP API.

To create a personal access token via the web interface. Navigate to Settings-> Manage Users. Click on the user you would like to create a personal access token for. Click on the button named "Create Personal Access Token".

Example Request with Personal Access Token

Assuming your personal access token is 2bCDp4lqfKEFl8r6l4s, we could use it as shown below.

curl -H "Authorization: Bearer 2bCDp4lqfKEFl8r6l4s" http://192.168.1.100/api/device

Basic HTTP Authentication

Looking to have backwards compatibility with NetBooter products? Enable HTTP Basic Authentication

In the context of an HTTP transaction, basic access authentication is a method for an HTTP user agent (e.g. a web browser) to provide a user name and password when making a request. In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic ;

Default: Basic HTTP Authentication denied.

Navigate to Network -> Web (/network/web) to enable basic authentication.

basic-http-auth

WebSocket

Access live stream of power/energy data from a WebSocket Connection.

Authentication SynLink WebSocket must be sent a session token after successfull connection to begin sending data.

Authentication Object to Send to Begin Data Stream

{cookie: "4jDv3lag56ADoih2bzd"}

Examples

The following examples uses personal access token (PAT) authentication which can be configured as instructed in the authentication section of this manual. These examples assumes the IP address if 192.168.1.100, and the PAT is rKKHIKivalp6ihp6e09.

Turn an outlet OFF or ON

To modify an outlet's state or setting, all you need is the outlet number. Options for state are: "ON", "OFF", "REBOOT".

curl 'http://192.168.1.100/api/outlets/1' \
  --request "PUT" \
  --header 'Authorization: Bearer rKKHIKivalp6ihp6e09' \
  --data '{ "state":"ON" }'

Power cycle an outlet

To modify an outlet's state or setting, all you need is the outlet number. Options for state are: "ON", "OFF", "REBOOT".

curl 'http://192.168.1.100/api/outlets/1' \
  --request "PUT" \
  --header 'Authorization: Bearer rKKHIKivalp6ihp6e09' \
  --data '{ "state":"REBOOT" }'

Get inlet power consumption information

Inlet consumption information can be found with endpoint /api/inlets. This will return an array of inlets. For standard inlet PDU configurations, a single inlet object will be found inside this array. If the PDU is configured as an ATS pdu, or a dual circuit PDU, there will be two inlets.

curl 'http://192.168.1.100/api/inlets' \
  --header 'Authorization: Bearer rKKHIKivalp6ihp6e09'

[
  {
    "inletType": "single",
    "inletPlug": "IEC-320 C20",
    "inletPhase": "Single Phase",
    "inletName": "Example New Inlet Name",
    "id": "I1-1000016",
    "inletLineConfiguration": "L-N",
    "inletCurrentRms": 0,
    "inletVoltageRms": 114.69999694824219,
    "inletLineFrequency": 60.13800048828125,
    "inletPowerFactor": 1,
    "inletActivePower": 0,
    "inletApparentPower": 0,
    "inletEnergyAccumulation": 0
  }
]

Get outlet current consumption information

curl 'http://192.168.1.100/api/outlets' \
  --header 'Authorization: Bearer rKKHIKivalp6ihp6e09'

[
  {
    "outletName": "Example outlet Name 1",
    "id": "1-1200568",
    "outletIndex": 1,
    "bankId": 1200568,
    "receptacle": "NEMA 5-20R",
    "customRebootTimeEnabled": false,
    "customRebootTime": 5,
    "circuitVoltage": 114.69999694824219,
    "rebootStatus": "none",
    "currentRms": 0,
    "state": "OFF",
    "voltageDetection": false,
    "relayHealth": "OK",
    "pwrOnState": "ON"
  },
  ...
]

Set up Web Hook for Event Trigger

Set Up Web Hook Action

Setting up Web Hook Post Requests can be done via the Web Interface of the SynLink PDU. Navigate to the section via the side header called "Automation". Once on this page, click the button "Create New Action". You can also get to the section with url /events/actions/new. Under Action Type click "HTTP Post Request. You may include optional stats to send with the HTTP Request (such as Inlet Data, Circuit Data, Outlet Data, and more).

Link Action to Event

After creating an action, link the action to a particular event. Navigate to the "Automation" page once again and click on "Create New event". Or go to url events/triggers/new. Under event type choose a given event (such as inlet current thresholds, or any number of triggers.). Under the "Add Action" section include the previously created action.

Once the given event is triggered, a Post Request will be sent accordingly. The data structure for the contents of the web hook can be found in the web hook section of this documentation.

Example Web Hook JSON

{
  "eventCode": 15,
  "eventName": "Example Inlet Max Current",
  "enclosureSerialNumber": "1000016",
  "valueExceedingThreshold": 12.09,
  "inlets": [
    {
      "inletType": "single",
      "inletPlug": "IEC-320 C20",
      "inletPhase": "Single Phase",
      "inletName": "Example New Inlet Name",
      "id": "I1-1000016",
      "inletLineConfiguration": "L-N",
      "inletCurrentRms": 12.09,
      "inletVoltageRms": 114.69999694824219,
      "inletLineFrequency": 60.13800048828125,
      "inletPowerFactor": 1,
      "inletActivePower": 0,
      "inletApparentPower": 0,
      "inletEnergyAccumulation": 0
    }
  ]
}

Endpoints

 

Device

Device Object shows top level information about PDU power, energy, sensors, and etc. Attributes will differ depending on it's models.

Device Object

Key Type Description
numBanks number Number of banks: a section of outlets on a specific circuit
numOutlets number Number of outlets total
numInlets number Number of inlets. Either 1 or 2
inletPlug string Inlet Plug receptacle/plug. If multiple inlets, both are same plug type
outletPwrMeasurementsSupported boolean When true, each outlet can measure current draw in amps
outletSwitchingSupported boolean When true, each outlet can switch on or off with a relay
enclosureSerialNumber string Unique ID for PDU Enclosure.
modelNumber string Specific PDU model number
inletConfig string Either "standard", "dualcircuit", or "ats"
formFactor string Either "0U", "1U", or "2U"
controllerSerialNumber number Serial Number of SynLink Controller Module
controllerFirmwareVersion string Firmware version for controller
controllerHardwareVersion string Hardware version for controller
phase string Either "Single Phase", "Three Phase Delta", or "Three Phase Wye"
circuitBreakerProtection boolean True if circuit breaker protection exists
uptime number Number of seconds the PDU has been on.
time string Time in ISO8601 String Format. 
{
  "numBanks": 3,
  "numOutlets": 36,
  "numInlets": 1,
  "inletPlug": "L21-30P",
  "outletPwrMeasurementsSupported": true,
  "outletSwitchingSupported": true,
  "enclosureSerialNumber": 1024122712,
  "modelNumber": "SP-3001CA-HA",
  "inletConfig": "standard",
  "formFactor": "0U",
  "controllerSerialNumber": 1360604425,
  "controllerFirmwareVersion": "1.0.3",
  "phase": "Single Phase",
  "controllerHardwareVersion": "1.0.0",
  "circuitBreakerProtection": true,
  "uptime": 19284619
}

Get Device Info

Retrieve PDU device information.

GET    /api/device      Returns object describing top level device information

Example Request

curl 'http://192.168.1.100/api/device' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k'

Response Body

{
  "numBanks": 3,
  "numOutlets": 36,
  "numInlets": 1,
  "inletPlug": "L21-30P",
  "outletPwrMeasurementsSupported": true,
  "outletSwitchingSupported": true,
  "enclosureSerialNumber": "1024122712",
  "modelNumber": "SP-3001CA-HA",
  "inletConfig": "standard",
  "formFactor": "0U",
  "controllerSerialNumber": "1921218731",
  "controllerFirmwareVersion": "0.1.2",
  "controllerHardwareVersion": "1.0.1",
  "circuitBreakerProtection": true,
  "uptime": 19284619
}

Inlets

Inlets show information about inlet configuration and energy consumption if relevant.

Inlet Object

{
  "id": "17374353",
  "inletType": "single",
  "inletPlug": "NEMA L6-20P",
  "inletName": "NEMA L6-20P Inlet",
  "inletEnergyAccumulation": 89.03,
  "inletPhase": "Single Phase"
}
Key Type Description
id string Unique identifier for Inlet
inletType string Describes configuration of specific Inlet Object. Either "single", "dual", or "ats".
inletPlug string Connector type for Inlet
inletName string User defined name for inlet
inletEnergyAccumulation number kWH value to show energy consumption for inlet plug. If multiple inlets, value will stay same for all inlets.
inletPhase number Either "Single Phase", or "Three Phase"

Inlet Object - 3 Phase Attributes

The following attributes will be included if the PDU is a 3 phase PDU

{
  "inletPowerFactor": 0.8,
  "threePhaseBalance": "80%",
  "inletLines": [
    {
      "currentRms": 1.31,
      "id": "L1-17374353",
      "line": "L1"
    },  
    {
      "currentRms": 2.41,
      "id": "L2-17374353",
      "line": "L2"
    },
    {
      "currentRms": 1.31,
      "id": "L3-17374353",
      "line": "L3"
    }
  ]
}
Key Type Description
inletPowerFactor number Power factor value for inlet plug
threePhaseBalance string Percentage unbalance for 3 phase circuit
inletLines array Contains 3 line objects, each with "currentRMS" in amps, unique "id", and "line" it is associated with.

Inlet Object - Single Phase Attributes

For ATS inlets, the following attributes will exist in the inlet with atsInletActive = true. 

{
  "inletCurrentRms": 4.2,
  "inletVoltageRms": 202.4,
  "inletLineFrequency": 59.9,
  "inletPowerFactor": 0.8,
  "inletActivePower": 11,             
  "inletApparentPower": 10,
  "inletLineConfiguration": "L-L",
}
Key Type Description
inletCurrentRms number Inlet current draw in amps
inletVoltageRms number Inlet voltage RMS in volts
inletLineFrequency number Inlet line frequency in hertz
inletPowerFactor number Power factor ratio
inletActivePower number Inlet Active Power in watts
inletApparentPower number Inlet Apparent Power in Volt-amperes (VA)
inletLineConfiguration string Line configuration for outlets connected to this inlet.

Inlet Object - ATS (Auto Transfer Switch) Attributes

The following attributes will appear if the PDU has ATS functionality.

{
  "atsInletId": "A",
  "atsInletActive": true,
  "atsInletReady": true,
}
Key Type Description
atsInletId string Either "A" or "B". Matches label on PDU.
atsInletActive boolean true if inlet is used to power outlets.
atsInletReady boolean true if inlet has voltage potential

List All Inlets

Returns a list of all outlets that within any connected banks. Only available if outletSwitchingSupported or outletMeteringSupported are true. Return a list of all inlets. Maximum 2 inlets possible. "ats" and "dual" for inletType configurations will have 2 inlets. inletType: "standard" will always have a single inlet.

GET    /api/inlets        Returns list of all inlets

Example Request

curl 'http://192.168.1.100/api/inlets' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k'

Response (Varies on configuration)

[
  {
    "id": "17374353",
    "inletType": "single",
    "inletPlug": "NEMA L21-30P",
    "inletName": "NEMA L6-20P Inlet",
    "inletLineConfiguration": "L-L",
    "inletEnergyAccumulation": 89,
    "inletCurrentRms": 4.2,
    "inletVoltageRms": 202.4,
    "inletLineFrequency": 59.9,
    "inletPowerFactor": 0.8,
    "inletActivePower": 11,             
    "inletApparentPower": 10
  }
]

Expected reponse is an array of Inlet Object(s)

Modify Inlet

Endpoint to modify Outlet information, including the relay state to turn outlet on and off.

PUT    /api/inlets/:inlet_id                   Modifies individual inlet

Request

Follows Authentication Scheme. All request parameters are optional, but at least one is required.

{
  "inletName": "Primary Line Input",
  "inletEnergyAccumulation": 0
}

inletName optional Name string up to 100 characters.

inletEnergyAccumulation optional Only value accepted is 0. 0 will reset energy accumulation back to 0. Resetting energy accumulation for any inlet will reset for all inlets.

Example Request

curl 'http://192.168.1.100/api/inlets/17374354' \
  --header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
  --data '{ "inletName":"Primary Line Input", "inletEnergyAccumulation": 0 }'

Response

Expected response is an updated Inlet Object. Varies with configuration.

{
  "id": "17374353",
  "inletType": "single",
  "inletPlug": "NEMA L6-20P",
  "inletName": "Primary Line Input",
  "inletLineConfiguration": "L-L",
  "inletEnergyAccumulation": 0,
  "inletCurrentRms": 4.2,
  "inletVoltageRms": 202.4,
  "inletLineFrequency": 59.9,
  "inletPowerFactor": 0.8,
  "inletActivePower": 11,        
  "inletApparentPower": 10
}

Banks

Banks are representation of groups of outlets. Banks are often referred to as circuits as well. Each bank has it's own energy measurement capabilities. Individual Outlet Current Measurements or/and individual Outlet Switching are optional additions. Otherwise energy information can be found in Inlets

Bank Object

{
  "id": "286331153",
  "inletId": "I1-1000016",
  "firmwareVersion": "010100",
  "hardwareVersion": "010105",
  "outletSwitchingSupported": true,
  "outletMeteringSupported": true,
  "currentRms": 0.807,
  "voltageRms": 119.900,
  "lineFrequency": 60.138,
  "powerFactor": 0.810,
  "activePower": 0.009,
  "apparentPower": 0.930,
  "energyAccumulation": 42.21,
  "bankName": "Bank 1",
  "bankLines": "L1-L2",
  "circuitBreakerClosed": true,
  "hasCircuitBreakerProtection": true
}
Key Type Description
id string Unique identifier for the bank
inletId string ID of inlet which the bank is behind
firmwareVersion string Version for bank firmware
hardwareVersion string Version for hardware for bank
outletSwitchingSupported boolean true if bank outlets support individual outlet switching
outletMeteringSupported boolean true if bank outlets support individual outlet current metering
currentRms number The instantaneous current measured at the inlet in Amps
voltageRms number Instantaneous voltage reading at inlet and all outlets in volts
lineFrequency number Line Frequency measurement valid from 45-65 GHz
powerFactor number Power Factor reading. Value is signed value representing polarity of power factor
activePower number Active Power measured in KW (kiloWatts). Power consumed by electrical resistance
apparentPower number Power which is actually consumed or utilized
energyAccumulation number Number of kilowatt hours accumulated. Can be used as billing unit for energy delivered
bankName string User defined name for Bank
bankLines string Specific Lines or line configuration which this bank is utilizing
circuitBreakerClosed boolean State of circuit breakers. true if circuit breaker is closed and providing power correctly.

List All Banks

Returns a list of all banks that the SynLink Controller has connected to.

GET /api/banks    Returns all banks

Example Request

curl 'http://192.168.1.100/api/banks' \
  --header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k'

Response

Expected response is an array of Bank Objects

[
  {
    "id": 286331153,
    "firmwareVersion": "1.0.1",
    "hardwareVersion": "1.0.0",
    "outletSwitchingSupported": true,
    "outletMeteringSupported": true,
    "currentRms": 0.807,
    "voltageRms": 119.900,
    "lineFrequency": 60.138,
    "powerFactor": 0.810,
    "activePower": -0.009,
    "apparentPower": 0.930,
    "energyAccumulation": 42,
    "bankName": "Bank 1",
    "bankLines": "L1-L2",
    "circuitBreakerClosed": true,
    "hasCircuitBreakerProtection": true
  },
  ...
]

Modify Bank Info

The only value changeable for banks is a custom name field for banks.

PUT    /api/banks/:bank_id                       Modifies individual bank

Request

Follows Authentication Scheme.

{
  "bankName": "Critical Equipment Bank"
}

bankName required Name string up to 100 characters.

Example Request
curl 'http://192.168.1.100/api/banks/286331153' \
  -H 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
  --data '{"bankName":"Critical Equipment Bank"}'

Response

Expected response is newly modified Bank Object

{
  "id": 286331153,
  "firmwareVersion": "1.0.0",
  "hardwareVersion": "1.0.1",
  "outletSwitchingSupported": true,
  "outletMeteringSupported": true,
  "currentRms": 0.807,
  "voltageRms": 119.900,
  "lineFrequency": 60.138,
  "powerFactor": 0.810,
  "activePower": -0.009,
  "apparentPower": 0.930,
  "energyAccumulation": 42,
  "bankName": "Bank 1",
  "bankLines": "L1-L2",
  "circuitBreakerClosed": true,
  "hasCircuitBreakerProtection": true
}

Outlets

Outlets are representations of each individual outlet on the PDU. They show information related to outlets. They are only available of PDU has banks which support either Outlet Switching and/or Outlet Current Metering

 

Outlet Object

{
  "id": "1-16777225",
  "outletName": "Outlet 1",
  "pwrOnState": "ON",
  "outletIndex": 1,
  "receptacle": "NEMA 5-20R",
  "customRebootTimeEnabled": false,
  "customRebootTime": 5,
  "circuitVoltage": 116.80,
  "currentRms": 0.16,
  "state": "ON",
  "bankId": 16777225,
  "voltageDetection": true,
  "rebootStatus": "pendingOff",
  "relayHealth": "OK"
}
Key Type Description
id string Unique identifier for the Outlet.
outletName string User defined outlet name
pwrOnState string Initial State of outlet on boot. Value is either "ON", "OFF", or "PREV"
outletIndex number Which number outlet amongst total outlets
receptacle string Connector type for outlet receptacle. Value is either "nema 5-15", "nema 5-20", "IEC 320 C13", or "IEC 320 C19"
customRebootTimeEnabled boolean true if the time for reboot looks at customRebootTime instead of global reboot time
customRebootTime number Number of seconds for outlet reboot time if customRebootTimeEnabled is true
circuitVoltage number Voltage RMS of the circuit that the outlet is connected to.
currentRms number Key will exist if current_monitoring_supported value is true. return number value in amps for current load for outlet.
state string "ON", "OFF" are the available options. Only exists of outlet current metering supported
bankId number Unique identifier for bank that outlet is associated with
rebootStatus string If outlet has been set to cycle/reboot, this value will be: pendingOff or pendingOn. Otherwise it will be none
voltageDetection boolean Is true if there is voltage detected on outlet. If state not equal to voltageDetection then there is potential hardware issues with the relay
relayHealth string Either "OK" or "Failed". Compares state and voltageDetection and returns "OK" if they are equal

   

List All Outlets

Returns a list of all outlets that within any connected banks. Only available if outletSwitchingSupported or outletMeteringSupported are true.

GET    /api/outlets        Returns list of all outlets

Example Request

curl 'http://192.168.1.100/api/outlets' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k'

Response

Expected response is an array of Outlet Objects

[
  {
    "id": "1-286331153",
    "outletName": "Outlet 1",
    "pwrOnState": "PREV",
    "outletIndex": 1,
    "receptacle": "IEC 60320 C19",
    "currentRms": 1.1,
    "state": "ON",
    "bankId": "286331153",
    "customRebootTimeEnabled": false,
    "customRebootTime": 12,
    "rebootStatus": "none",
    "voltageDetection": true,
    "relayHealth": "OK"
  },
  {
    "id": "2-286331153",
    "outletName": "Outlet 2",
    "pwrOnState": "PREV",
    "outletIndex": 2,
    "receptacle": "IEC 60320 C19",
    "currentRms": 1.1,
    "state": "ON",
    "bankId": "286331153",
    "customRebootTimeEnabled": false,
    "customRebootTime": 12,
    "rebootStatus": "none",
    "voltageDetection": true,
    "relayHealth": "OK"
  },
  ...
]

Modify Outlet

Endpoint to modify Outlet information, including the relay state to turn outlet on and off.

PUT    /api/outlets/:outlet_id                   Modifies individual outlet

Request

Follows Authentication Scheme. All request parameters are optional, but at least one is required.

{
  "outletName": "NAS Server 1",
  "pwrOnState": "off",
  "state": "ON",
  "customRebootTimeEnabled": true,
  "customRebootTime": 10
}

outletName optional Name string up to 100 characters.

pwrOnState optional Power on State is the state of the relay for the specific outlet when the PDU powers on from an off/powerless state. Acceptable strings are "ON", "OFF", "PREV". "PREV" will set the relay to the state of the PDU when last lost power.

state optional State represents the relay status. Acceptable strings are "ON", "OFF", and "REBOOT".

customRebootTimeEnabled optional Setting to true will configure PDU to use customRebootTime when rebooting outlet.

customRebootTime optional Number of seconds outlet will be off when rebooting and customRebootTimeEnabled is true

Example Request

curl 'http://192.168.1.100/api/outlets/1-858993459' \
  --header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
  --data '{ "outletName":"NAS Server 1", "pwrOnState":"off", "state":"on" }'

Response

Expected response is an updated Outlet Object

{
  "id": "1-286331153",
  "outletName": "Nas Server 1",
  "pwrOnState": "OFF",
  "outletIndex": 1,
  "receptacle": "IEC 60320 C19",
  "currentRms": 1.1,
  "state": "ON",
  "bankId": "286331153",
  "customRebootTimeEnabled": false,
  "customRebootTime": 12,
  "voltageDetection": true,
  "relayHealth": "OK"
}

Groups

Groups are user created list of outlets. Outlets are designated by user. Groups can be used to manage sets of equipment together.

 

Group Object

{
  "groupName": "Modem/Router Equipment",
  "id": "1",
  "groupRebootSequenceDelay": 3,
  "outlets": [
    {
      "outletName": "Outlet 20",
      "id": "20-572662306",
      "pwrOnState": "PREV",
      "outletIndex": 8,
      "currentRms": 0,
      "state": "On",
      "bankId": 572662306,
      "watts": 0
    },
    {
      "outletName": "Outlet 21",
      "id": "21-572662306",
      "pwrOnState": "PREV",
      "outletIndex": 9,
      "currentRms": 4.20,
      "state": "On",
      "bankId": 572662306,
      "watts": 5.04
    },
    ...
  ]
}
Key Type Description
groupName string User defined name for group
id string Unique Identifier for Group
groupRebootSequenceDelay number When rebooting group of outlets, number of seconds to wait before each outlet turns on
outlets array Array of Outlet Objects

Get List of Groups

Returns a list of all groups that have been created.

GET    /api/groups       Returns list of all outlet groups

Example Request

curl 'http://192.168.1.100/api/groups' \
  --header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k'

Response

Expected response is an array of Group Objects

{
  "groupName": "Modem/Router Equipment",
  "id": "1",
  "groupRebootSequenceDelay": 3,
  "outlets": [
    {
      "outletName": "Outlet 20",
      "id": "20-572662306",
      "pwrOnState": "PREV",
      "outletIndex": 8,
      "currentRms": 0,
      "state": "On",
      "bankId": 572662306,
      "watts": 0
    },
    {
      "outletName": "Outlet 21",
      "id": "21-572662306",
      "pwrOnState": "PREV",
      "outletIndex": 9,
      "currentRms": 4.20,
      "state": "On",
      "bankId": 572662306,
      "watts": 5.04
    },
    ...
  ]
}

Create Group

POST   /api/groups         Creates a group of outlets.

Request

Follows Authentication Scheme.

{
  "groupName": "Example Group 1", // required
  "outlets": ["2-858993459", "7-858993459"] // required
}

groupName required Name string up to 100 characters

outlets optional Outlets array of outlet UUIDs. Required at least 1.

groupRebootSequenceDelay optional Sequence delay in seconds. When group outlets reboot, they boot consecutively and with this sequence delay. Maximum group reboot sequence delay is 99 seconds.

Example Request

curl 'http://192.168.1.100/api/groups' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
--data '{"groupName":"Example Group 1","outlets":["2-858993459","7-858993459"]}'

Response

Expected response is the newly created Group Object with new group uuid.

{
  "groupName": "Modem/Router Equipment",
  "id": "2",
  "groupRebootSequenceDelay": 3,
  "outlets": [
    {
      "outletName": "Outlet 20",
      "id": "20-572662306",
      "pwrOnState": "PREV",
      "outletIndex": 8,
      "currentRms": 0,
      "state": "On",
      "bankId": 572662306,
      "watts": 0
    },
    {
      "outletName": "Outlet 21",
      "id": "21-572662306",
      "pwrOnState": "PREV",
      "outletIndex": 9,
      "currentRms": 4.20,
      "state": "On",
      "bankId": 572662306,
      "watts": 5.04
    },
    ...
  ]
}

Modify Group

PUT    /api/groups/:group_id           Modifies individual group

Request

Follows Authentication Scheme. To modify the outlets inside of group, update the outlet array of outlet UUIDs. :group_id is to be replaced by Group UUID

{
  "groupName": "Storage Equipment 2",
  "outlets": ["7-858993459", "8-858993459", "3-858993459"]
}
Example Request
curl 'http://192.168.1.100/api/groups/0u912084N12dM5b05GU' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
--data '{"groupName":"Storage Equipment 2","outlets":["7-858993459","8-858993459","2-858993459"]}'

Response

Expected response is a Group Object

{
  "groupName": "Modem/Router Equipment",
  "id": "2",
  "groupRebootSequenceDelay": 3,
  "outlets": [
    {
      "outletName": "Outlet 20",
      "id": "20-572662306",
      "pwrOnState": "PREV",
      "outletIndex": 8,
      "currentRms": 0,
      "state": "On",
      "bankId": 572662306,
      "watts": 0
    },
    {
      "outletName": "Outlet 21",
      "id": "21-572662306",
      "pwrOnState": "PREV",
      "outletIndex": 9,
      "currentRms": 4.203895392974451e-44,
      "state": "On",
      "bankId": 572662306,
      "watts": 5.048878302815963e-42
    }...
  ]
}

Switch Group Outlets

PUT /api/groups/:group_id Modify (switch) a group

Request

Follows Authentication Scheme. To change the outlet states, use the key value state, and it's options: "ON", "OFF", "REBOOT"

{
  "state": "OFF"
}
Example Request
curl 'http://192.168.1.100/api/groups/0u912084N12dM5b05GU' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
--data '{"state": "OFF"}'

Response

Expected response is a Group Object

{
  "groupName": "Modem/Router Equipment",
  "id": "2",
  "groupRebootSequenceDelay": 3,
  "outlets": [
    {
      "outletName": "Outlet 20",
      "id": "20-572662306",
      "pwrOnState": "PREV",
      "outletIndex": 8,
      "currentRms": 0,
      "state": "OFF",
      "bankId": 572662306,
      "watts": 0
    },
    {
      "outletName": "Outlet 21",
      "id": "21-572662306",
      "pwrOnState": "PREV",
      "outletIndex": 9,
      "currentRms": 4.203895392974451e-44,
      "state": "OFF",
      "bankId": 572662306,
      "watts": 5.048878302815963e-42
    }...
  ]
}

Remove a Group

DELETE /api/groups/:group_id    Permanently remove group.

Request

Follows Authentication Scheme :group_id should be replaced with Group UUID

{} // no request parameters
Example Request
curl -X DELETE 'http://192.168.1.100/api/groups/0u912084N12dM5b05GU' \
--header 'Cookie: SPID=j2d36cG2ciHKDDqFc3k'

Response

Expected Response is a 200 HTTP Response code for successful permanent deletion of group.  

200

Configuration

Configuration endpoint represents all network configuration, and other global configurations.

Configuration Object

{
  "hostName": "SynLink",
  "macAddr": "3A:D2:21:D3:82:45",
  "webPort": 80,
  "webSslPort": 443,
  "telnetPort": 23,
  "sshPort": 22,
  "ipAssign": "static",
  "globalRebootTime": 5,
  "webEnabled": true,
  "webSslEnabled": true,
  "webRedirectHttp": false,
  "customSslCertEnabled": false,
  "telnetEnabled": true,
  "sshEnabled": true,
  "subnetMask": "255.255.255.0",
  "gatewayIp": "192.168.1.1",
  "staticIp": "192.168.1.100",
  "primaryDns": "8.8.8.8",
  "secondaryDns": "8.8.4.4",
  "ntpEnabled": true,
  "ntpHost": "pool.ntp.org",
  "disableSshPassLogin": false,
  "disableSshKeyLogin": false,
  "usbFwupdateControlEnabled":false,
  "sshIdleTimeout": 0,
  "webIdleTimeout": 0,
  "webMaxUsers": 0,
  "deviceSequentialPowerUpDelay": 3,
  "webApiPasswordEnabled": false,
  "smtpServer": "",
  "smtpPort": 0,
  "smtpTlsEnabled": 0,
  "smtpAuthRequired": 0,
  "smtpUsername": "",
  "syslogServerIp": "",
  "enableRemoteUserLogging":false,
  "enableRemoteEventLogging":false,
  "smtpPassword": "",
  "snmpv12Enabled": true,
  "snmpv12ReadString": "public",
  "snmpv12WriteString": "private",
  "snmp3AuthPass": "examplepassword",
  "snmp3PrivacyPass": "exampleprivacypass",
  "snmp3TrapAuthProtocol": "SHA",
  "snmp3TrapPrivacyProtocol": "AES",
  "snmp3TrapSecurity": "authPriv",
  "deviceName": "SynLink PDU",
  "lcdOrientation": 90,
  "lcdScreensaverTimeout": 60,
  "lcdBacklightBrightness": 2,
  "lcdScreensaverType": "power_info",
  "lcdBackgroundColor": "black",
  "lcdOutletControlEnabled": true,
  "lcdNetworkControlEnabled": true,
  "lcdRebootControlEnabled":false,
  "lcdFlushControlEnabled":false,
  "portAMode": "sensor",
  "portAComBaud": 115200,
  "portAModemBaud": 115200,
  "usbComBaud": 115200,
  "usbModemBaud":115200,
  "usbFwupdateControlEnabled":false,
  "daylightsavings": true,
  "timezone": "GMT+8",
  "customSslCertExists": false,
  "customSslKeyExists": false
}

Device Settings

{
  "deviceName": "Name for device not host name",
  "globalRebootTime": 5
}
Key Type Description
deviceName string Name for this PDU. Separate from hostname
globalRebootTime number Number of seconds the outlet is flipped before flipping back on a power cycle

IP Settings

{
  "macAddr": "80:1F:12:41:ED:28",
  "ipAssign": "dhcp",
  "staticIp": "192.168.1.100",
  "subnetMask": "255.255.255.0",
  "gatewayIp": "192.168.1.1",
  "primaryDns": "8.8.8.8",
  "secondaryDns": "8.8.4.4",
  "hostName": "SP-3001CA-HA",
}
Key Type Description
macAddr string Mac address string for network interface card
ipAssign string Either "dhcp" or "static" are valid strings. DHCP assignment will show IP through dhcpAssignedIp. Static IP is set with staticIp
staticIp string IP Address that the PDU will respond to if ipAssign is set to "static"
subnetMask string Subnet Mask that divides IP address into network address and host address
gatewayIp string IP Address of device on network which sends local network traffic to other networks
primaryDns string IP Address of Primary DNS Server
secondaryDns string IP Address of Secondary DNS Server
hostName string Label assigned to network connected device

The following attributes only apply when "ip_assign" is set to dhcp and a DHCP address has been properly assigned.

{
  
  "dhcpAssignedIp":"192.168.1.101",
  "dhcpPrimaryDns":"8.8.8.8",
  "dhcpSecondaryDns":"8.8.4.4",
  "dhcpGatewayIp":"192.168.1.1",
  "dhcpSubnetMask":"255.255.255.0",
}
Key Type Description
dhcpAssignedIp string IP Address assigned by DHCP server. Only available is ipAssign is "dhcp"
dhcpPrimaryDns string Primary DNS assigned by DHCP server. Only available is ipAssign is "dhcp"
dhcpSecondaryDns string Secondary DNS by DHCP server. Only available is ipAssign is "dhcp"
dhcpGatewayIp string Gateway IP assigned by DHCP server. Only available is ipAssign is "dhcp"
dhcpSubnetMask string Subnet Mask assigned by DHCP server. Only available is ipAssign is "dhcp"

Web Settings

{
  "webEnabled": true,
  "webPort": 80,
  "webRedirectHttp": true,
  "webSslEnabled": true,
  "webSslPort": 443,
  "webApiPasswordEnabled": false,
  "customSslCertEnabled": false,
  "customSslCertExists": false,
  "customSslKeyExists": false
}
Key Type Description
webEnabled boolean Turns on or off Webserver
webPort number Port to reach Webserver. Default port is 80
webRedirectHttp boolean If true then any requests to http will be redirected to https
webSslEnabled boolean Enables web server on HTTPS. Uses webSslPort port
webSslPort number Port to reach HTTPS webserver. Default port is 443
webApiPasswordEnabled boolean Enable or disable username-password access with every HTTP call. WARNING: Insecure
customSslCertEnabled boolean Set to true to use custom ssl cert and key instead of default. Requires customSslCertExists and customSslKeyExists to be true
customSslCertExists boolean true if user has successfully uploaded an SSL Certificate
customSslKeyExists boolean true if user has successfully uploaded an SSL Key

SSH Settings

{
  "sshEnabled": true,
  "sshPort": 23,
  "disableSshPassLogin": false,
  "disableSshKeyLogin": false,
  "sshIdleTimeout": 0,
}
Key Type Description
sshEnabled boolean Turns on or off SSH Server
sshPort number Port to reach SSH Server. Default port is 22
disableSshPassLogin boolean Disable or enable password based logins
disableSshKeyLogin boolean Disable or enable key based logins
sshIdleTimeout number Number of seconds before SSH server auto disconnects from idle connection

Telnet Settings

{
  "telnetEnabled": true,
  "telnetPort": 23,
}
Key Type Description
telnetEnabled boolean Turns on or off Telnet Server
telnetPort number Port to reach Telnet Server. Default port is 23

SNMP Settings

{
  "snmpv12enabled": true,
  "snmpv12ReadString": "example_read_string",
  "snmpv12WriteString": "example_write_string",
  "snmpv3Enable": true,
  "snmpSysContact": "support@synaccess-net.com",
  "snmpSysName": "SP-3001CA-HA",
  "snmpSysLocation": "Rack #4",
  "snmp3AuthPass": "examplepassword",
  "snmp3PrivacyPass": "exampleprivacypass",
  "snmp3TrapAuthProtocol": "SHA",
  "snmp3TrapPrivacyProtocol": "AES",
  "snmp3TrapSecurity": "authPriv"

}
Key Type Description
snmpv12enabled boolean Enable or disables SNMP v1/v2c agent.
snmpv12ReadString string Passphrase for reading from agent SNMP 1/v2c
snmpv12WriteString string Passphrase for writing to agent SNMP 1/v2c
snmpSysContact string Primary contact for PDU SNMP node
snmpSysName string Assigned name for PDU SNMP node
snmpSysLocation string Physical location for PDU SNMP node
snmp3AuthPass string Auth Pass for SNMPv3 Traps. Minimum 8 characters
snmp3PrivacyPass string Privacy Pass for SNMPv3 Traps. Minimum 8 characters
snmp3TrapAuthProtocol string Type of auth protocol options: "MD5" or "SHA"
snmp3TrapPrivacyProtocol string Type of privacy protocol options: "DES" or "AES"
snmp3TrapSecurity string Options: "authPriv", "authNoPriv", "noAuthNoPriv"

SMTP Settings

{
  "smtpServer": "smtp.gmail.com",
  "smtpPort": 465,
  "smtpTlsEnabled": true,
  "smtpAuthRequired": true,
  "smtpUsername": "example_username",
  "smtpPassword": "example_password"
}
Key Type Description
smtpServer string IP/Domain name for SMTP server
smtpPort number Port to reach SMTP Server
smtpTlsEnabled boolean Enable or disable TLS Authentication
smtpAuthRequired boolean Enable or disable passing authentication with SMTP messages.
smtpUsername string Username for SMTP authentication
smtpPassword string Password for SMTP authentication

NTP & Time Settings

{
  "ntpEnabled": true,
  "ntpHost": "pool.ntp.org",
  "daylightsavings": false,
  "timeZone": "GMT+8"
}
Key Type Description
ntpEnabled boolean Turns on or off NTP time synchronization. Requires network connection
ntpHost string NTP Host URL/IP to reference for time synchronization
daylightsavings boolean Enable or disable day light savings adjustment
timezone string Format: GMTXXX where XXX is between -12 to +12 for timezone offsets from GMT. Ex: GMT+8 for PST

Remote Syslog Settings

{
  "syslogServerIp": "",
  "enableRemoteUserLogging":false,
  "enableRemoteEventLogging":false,
}
Key Type Description
syslogServerIp string Seting remote syslog server IP to send syslog messages
enableRemoteUserLogging boolean Enable or disable sending user activity logs to syslogServerIp
enableRemoteEventLogging boolean Enable or disable sending configured event triggers to syslogServerIp

LCD Front Panel Settings

{
  "lcdOrientation": 90,
  "lcdScreensaverTimeout": 60,
  "lcdBacklightBrightness": 2,
  "lcdScreensaverType": "power_info",
  "lcdBackgroundColor": "black",
  "lcdOutletControlEnabled": true,
  "lcdNetworkControlEnabled": true,
  "lcdRebootControlEnabled":false,
  "lcdFlushControlEnabled":false

}
Key Type Description
lcdOutletControlEnabled boolean Allow controlling of outlet relays (if applicable) through front panel LCD
lcdNetworkControlEnabled boolean Allow changing of IP assignment/Address through front panel LCD
lcdRebootControlEnabled boolean Allows user to reboot the control module from the LCD interface (outlet states are unchanged)
lcdFlushControlEnabled boolean Allows user to flush logs and issue a graceful shutdown
lcdOrientation number Degrees to rotate screen. Options are 0, 90, 180, or 270
lcdBacklightBrightness string Value between 0 and 7. 7 is brightest.
lcdScreensaverTimeout number Number of seconds before screensaver plays
lcdScreensaverType string Screensaver type. Options vary for each model.
lcdBackgroundColor string Options: black, navy, blue, teal, magenta, gray, maroon, purple, green, orange, navy, olive

Port Settings

Port A can switch between Modem Mode, COM mode, and Sensor Mode. This port cannot be multiple modes at the same time.

COM mode will allow a serial connection to the SynLink Command Line Interface.

Sensor mode allows useage with sensor accessories.

Modem mode provides out of band access to a connected serial device, such as a modem. For example: connect a modem's serial port to the Port A serial port set to modem mode. Then from the SynLink CLI, use command "modem connect". You will now be able to use the modem's serial port.

{
  "portAMode": "sensor",
  "portAComBaud": 115200,
  "portAModemBaud": 115200,
  "usbComBaud": 115200,
  "usbModemBaud":115200,
  "usbFwupdateControlEnabled":false
}
Key Type Description
portAMode string Options are: "sensor", "com", and "modem". COM will enable port for serial access. Modem will remote access to connected serial device.
portAModemBaud number Baud rate for RJ45 modem port for MODEM mode. Options are 1200, 2400, 4800, 9600, 19200, 38400, 57600 and 115200
portAComBaud number Baud rate for RJ45 modem port for COM mode. Options are 1200, 2400, 4800, 9600, 19200, 38400, 57600 and 115200
usbModemBaud number Baud rate for USB Port when a serial device is connected. Options are 1200, 2400, 4800, 9600, 19200, 38400, 57600 and 115200
usbComBaud number Baud rate for USB-serial port labeled "COM". Options are 1200, 2400, 4800, 9600, 19200, 38400, 57600 and 115200
usbFwupdateControlEnabled boolean Enable or Disable Power Sharing for Controller Power Redundancy

 

Modify Configurations

POST    /api/conf         Modifies configuration

Follows Authentication Scheme. Use any previously specified configuration values as a argument to modify configurations.

Example Request
curl 'http://192.168.1.100/api/conf' \
  -H 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
  --data '{"deviceName":"Closet PDU Primary"}'

Expected response is newly modified Conf Object

Sensors

SynLink PDUs support a variety of sensors. The most common being a temperature and humidity sensor.

Sensor Object

{
  "sensorPort": "B",
  "sensorName": "Temperature & Humidity Sensor",
  "sensorType": "temp_hum",
  "sensorId": "2" // temperature sensor ID's will correlate with their port. Smart IO Hubs will be unique per hub.
}
Key Type Description
sensorPort string "A" or "B" are the available options. Correspond with physical RJ45 ports.
sensorType string Specifies which type of sensor. Example: "temp_hum"
sensorName string Name for sensor. Not changeable.
sensorId string Unique identifier for sensor within a SynLink control module. Temperature/humidity sensors will be tied to the sensor port. Smart IO Hubs will be unique per hub.

Sensor Object - SPA-0010 Temperature & Humidity Attributes

If sensorType is "temp_hum" then the sensor object will have the following attributes.

{
  "sensorTempInC": 22.90574836730957,
  "sensorTempInF": 73.2303466796875,
  "sensorHumidity": 39.50677490234375,
}
Key Type Description
sensorTempInF number Temperature in fahrenheit
sensorTempInC number Temperature in celsius
sensorHumidity number Humidity as a relative percentage

Sensor Object - SPA-0140 Smart IO Hub Attributes

If sensorType is "dio_hub" then the sensor object will have the following attributes.

{
  "outputRelays": [
    {
      "outputRelayName": "Output Relay 1",
      "outputRelayDescription": "Output Relay 1",
      "rebootStatus": "none",
      "state": "OPEN",
      "index": 1
    }...
  ],
  "digitalInputs": [
    {
      "digitalInputName": "Digital Input 1",
      "digitalInputDescription": "Digital Input 1",
      "state": "HI",
      "index": 1
    }...
  ],
  "vdcOutputState": true,
  "userSwitchState": false
}
Key Type Description
outputRelays array Array of output relay objects. See Output Relay Object
digitalInputs array Array of digital input objects. See Digital Input Object
vdcOutputState boolean true is ENABLED, false is DISABLED. Changeable.
userSwitchState boolean true is ON, false is OFF. Read Only.

Output Relay Object

Key Type Description
outputRelayName string Unique ID for sensor within a SynLink PDU. Changeable.
outputRelayDescription string User editable description for Output Relay. Max 250 characters. Changeable.
state string "OPEN", "CLOSE". Changeable.
index number 1 through 6. Matches label on Smart IO Hub. Read Only.

Digital Input Object

Key Type Description
digitalInputName string Unique ID for sensor within a SynLink PDU
digitalInputDescription string User editable description for Digital Input. Max 250 characters
state string "HI", "LOW"
rebootStatus string "pendingHI", "pendingLOW", "none"
index number 1 through 6. Matches label on Smart IO Hub

 

List All Sensors

Returns list of all connected sensors.

GET /api/sensors    Returns all sensors

Example Request

curl 'http://192.168.1.100/api/sensors' \
  --header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k'

Response

Expected response is an array of Sensor Object(s).

[
  {
    "sensorId": "1",
    "sensorPort": "A",
    "sensorName": "Temperature & Humidity Sensor",
    "sensorDescription": "Temperature & Humidity Sensor",
    "sensorTempInC": 22.90574836730957,
    "sensorTempInF": 73.2303466796875,
    "sensorHumidity": 39.50677490234375,
    "sensorType": "temp_hum"
  },
  {
    "sensorId": "8279312",
    "sensorPort": "B",
    "sensorName": "Smart IO Hub",
    "sensorDescription": "Smart IO Hub",
    "sensorType": "dio_hub",
    "outputRelays": [
      {
        "outputRelayName": "Output Relay 1",
        "outputRelayDescription": "Output Relay 1",
        "rebootStatus": "none",
        "state": "OPEN",
        "index": 1
      }...
    ],
    "digitalInputs": [
      {
        "digitalInputName": "Digital Input 1",
        "digitalInputDescription": "Digital Input 1",
        "state": "HI",
        "index": 1
      }...
    ],
    "vdcOutputState": true,
    "userSwitchState": false
  }
]

 

Modify Smart IO Hub Sensor Settings or VDC Output State

PUT /api/sensors/:sensorId                Modify Sensor Settings/State

Request

Follows Authentication Scheme

:sensorId may be replaced with :sensorPort if desired. Endpoint only applies to SPA-0140 Smart IO Hub.

{
  "sensorName": "Lab bench #2 sensor hub",
  "sensorDescription": "Under desk on right side.",
  "vdcOutputState": true
}

sensorName Name string up to 100 characters.

sensorDesription Description string up to 250 characters.

vdcOutputState true is ENABLED, false is DISABLED.

Example Request

curl 'http://192.168.1.100/api/sensors/875552' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
--data '{"sensorName":"Lab bench #2 sensor hub","sensorDescription":"Under desk on right side."}'

Response

Expected response is a Sensor Object.

{
  "sensorId": "8279312",
  "sensorPort": "B",
  "sensorName": "Smart IO Hub",
  "sensorDescription": "Smart IO Hub",
  "sensorType": "dio_hub",
  "outputRelays": [
    {
      "outputRelayName": "Output Relay 1",
      "outputRelayDescription": "Output Relay 1",
      "rebootStatus": "none",
      "state": "OPEN",
      "index": 1
    }...
  ],
  "digitalInputs": [
    {
      "digitalInputName": "Digital Input 1",
      "digitalInputDescription": "Digital Input 1",
      "state": "HI",
      "index": 1
    }...
  ],
  "vdcOutputState": true,
  "userSwitchState": false
}

Modify Smart IO Hub Output Relay Settings/State

PUT /api/sensors/:sensorId/outputRelay/:outputRelayIndex    Modify Sensor Hub Output Relay State

Request

Follows Authentication Scheme

:sensorId may be replaced with :sensorPort if desired. Endpoint only applies to SPA-0140 Smart IO Hub.

{
  "outputRelayName": "Solenoid valve DC-4",
  "outputRelayDescription": "Solenoid valve #2. Green tag.",
  "state": "OPEN"
}

outputRelayName Name string up to 100 characters.

outputRelayDescription Description string up to 250 characters.

state Valid options are "OPEN" or "CLOSE". Case insensitive.

Example Request

curl 'http://192.168.1.100/api/sensors/875552/outputRelay/1' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
--data '{"outputRelayName":"Solenoid valve DC-4","outputRelayDescription":"Solenoid valve #2. Green tag.","state":"OPEN"}'

Response

Expected response is a Output Relay Object.

Modify Smart IO Hub Digital Input Settings

PUT /api/sensors/:sensorId/digitalInputs/:digitalInputIndex   Modify Sensor Hub Digital Input State

Request

Follows Authentication Scheme

:sensorId may be replaced with :sensorPort if desired. Endpoint only applies to SPA-0140 Smart IO Hub.

{
  "digitalInputName": "Leak Detection Lab Bench #2",
  "digitalInputDescription": "On the ground, near the power strip.",
}

digitalInputName Name string up to 100 characters.

digitalInputDescription Description string up to 250 characters.

Example Request

curl 'http://192.168.1.100/api/sensors/875552/digitalInputs/1' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
--data '{"digitalInputName":"Leak Detection Lab Bench #2","digitalInputDescription":"On the ground, near the power strip."}'

Response

Expected response is a Digital Input Object.

Events

Events are specific triggers that will run specified actions. An example event would be an outlet current draw being greater than 5 amps. With an example action of emailing support@synaccess-net.com.

Event Object

{
  "name": "16A Warning Threshold for Banks/Circuit Breaker",
  "id": 2,
  "enabled": true,
  "code": 31,
  "numTicksBeyond": 0,
  "triggered": false,
  "params": [
    "any",
    "16",
    "10"
  ],
  "actions": [
    1,
    2
  ]
}
Key Type Description
name string Name for event
id number Unique identifier
enabled boolean Enable or disable event trigger
code number Event Code. see Event Codes Table
params array Array of strings for associated to particular event code. See event codes table.
actions array Array of action ID's
triggered boolean Describes whether or not the trigger has met it's threshold
numTicksBeyond number Number of steps beyond the threshold. For example, 3 ticks beyond for max current is 3 seconds beyond

 

List All Events

GET    /api/events     Returns list of events

Example Request

  curl 'http://192.168.1.100/api/events' \
  --header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k'

Expected response is an array of Event Objects

Create New Event

POST /api/events      Create a new Event

Request

Follows Authentication Scheme

{
  "name": "Outlet #2 Amperage Threshold",
  "code": 45,
  "params": [
    "8-286331153",
    "5",
    "3"
  ],
  "actions": [
    2
  ]
}

name required Name string up to 100 characters

code required Event code for particular trigger. See Event Code Table.

params required for certain triggers See Event Code Table. Array of strings, maximum 3 parameters.

actions required Array of action ID's.

Example Request

curl 'http://192.168.1.100/api/events' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
--data '{"name":"Outlet #2 Amperage Threshold","code":"45","params":["8-286331153",5,3],"actions":[2]}'

Expected response is an Event Object

Modify Event

POST  /api/events/:event_id    Modifies specific event

Request

Follows Authentication Scheme

{
  "name": "Outlet #2 Amperage Threshold",
  "code": 45,
  "params": [
    "8-286331153",
    "5",
    "3"
  ],
  "actions": [
    2
  ]
}

Same request body as Creating New Events

Example Request

curl 'http://192.168.1.100/api/events/1' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
--data '{"name":"Outlet #2 Amperage Threshold","code":"45","params":["8-286331153","6","3"],"actions":[2]}'

Expected response is an Event Object

Delete Event Permanently

DELETE  /api/events/:event_id   Permanently remove event

Request

Follows Authentication Scheme

{} // no request parameters

Example Request

curl -X DELETE 'http://192.168.1.100/api/events/1' \
--header 'Cookie: SPID=j2d36cG2ciHKDDqFc3k'

Response

Expected response is a 200 HTTP response for success.

200

 

Event Codes Table

Code Name Parameter 1 Parameter 2 Parameter 3 Description
12 AutoPing Timeout Target IP Address # fails before action -- IP Address to Ping. Failure to ping creates trigger.
13 Inlet Line Max Current Threshold Inlet Line Amperage Threshold # secs past threshold Applies to 3 phase PDUs with line measurements. Amperage threshold in amps
14 Inlet Line Min Current Threshold Inlet Line Amperage Threshold # secs past threshold Applies to 3 phase PDUs with line measurements. Amperage threshold in amps
15 Inlet Max Current Threshold Inlet ID Amperage Threshold # secs past threshold Applies to single phase PDUs. Amperage threshold in amps
16 Inlet Min Current Threshold Inlet ID Amperage Threshold # secs past threshold Applies to single phase PDUs. Amperage threshold in amps
17 Inlet Max Voltage Threshold Inlet ID Voltage Threshold # secs past threshold Applies to single phase PDUs. Voltage threshold in volts
18 Inlet Min Voltage Threshold Inlet ID Voltage Threshold # secs past threshold Applies to single phase PDUs. Voltage threshold in volts
19 Inlet Max Line Frequency Threshold Inlet ID Line Frequency Threshold # secs past threshold Applies to single phase PDUs. Line frequency threshold in hertz
20 Inlet Max Line Frequency Threshold Inlet ID Line Frequency Threshold # secs past threshold Applies to single phase PDUs. Line frequency threshold in hertz
21 Inlet Min Power Factor Inlet ID Power Factor Threshold # secs past threshold Power Factor Threshold as a ratio
22 Inlet Active Energy Accumulation Max Inlet ID kWh Threshold -- --
24 Inlet Min Active Power Threshold Inlet ID Active Power Threshold # secs past threshold Active Power Threshold in watts
23 Inlet Max Active Power Threshold Inlet ID Active Power Threshold # secs past threshold Active Power Threshold in watts
25 Inlet Max Apparent Power Threshold Inlet ID Apparent Power Threshold # secs past threshold Apparent Power Threshold in volt-amperes (VA)
26 Inlet Min Apparent Power Threshold Inlet ID Apparent Power Threshold # secs past threshold Apparent Power Threshold in volt-amperes (VA)
29 Inlet 3 Phase Imbalance Inlet ID % Imbalance Threshold # secs past threshold --
30 Bank Circuit Breaker Trip Bank ID -- -- --
31 Bank Max Current Threshold Bank ID Amperage Threshold # secs past threshold Amperage threshold in amps
32 Bank Min Current Threshold Bank ID Amperage Threshold # secs past threshold Amperage threshold in amps
33 Bank Max Voltage Threshold Bank ID Voltage Threshold # secs past threshold Voltage threshold in volts
34 Bank Min Voltage Threshold Bank ID Voltage Threshold # secs past threshold Voltage threshold in volts
35 Bank Max Line Frequency Threshold Bank ID Line Frequency Threshold # secs past threshold Line Frequency threshold in hertz
36 Bank Min Line Frequency Threshold Bank ID Line Frequency Threshold # secs past threshold Line Frequency threshold in hertz
37 Bank Min Power Factor Bank ID Power Factor Threshold # secs past threshold
38 Bank Active Energy Accumulation Max Bank ID kWh Threshold --
39 Bank Max Active Power Threshold Bank ID Active Power Threshold # secs past threshold Active Power Threshold in watts
40 Bank Min Active Power Threshold Bank ID Active Power Threshold # secs past threshold Active Power Threshold in watts
41 Bank Max Apparent Power Threshold Bank ID Apparent Power Threshold # secs past threshold Apparent Power Threshold in volt-amperes (VA)
42 Bank Min Apparent Power Threshold Bank ID Apparent Power Threshold # secs past threshold Apparent Power Threshold in volt-amperes (VA)
45 Outlet Max Current Threshold Outlet ID Amperage Threshold # secs past threshold Applies to PDUs with Outlet Current Measurements. Amperage threshold in amps
46 Outlet Min Current Threshold Outlet ID Amperage Threshold # secs past threshold Applies to PDUs with Outlet Current Measurements. Amperage threshold in amps
49 Temperature Max Threshold Sensor ID Temperature Threshold # secs past threshold Requires attached temperature/humidity sensor. Temperature threshold in celsius
50 Temperature Min Threshold Sensor ID Temperature Threshold # secs past threshold Requires attached temperature/humidity sensor. Temperature threshold in celsius
51 Humidity Max Threshold Sensor ID Humidity Threshold # secs past threshold Requires attached temperature/humidity sensor. Humidity threshold as relative humidity %
52 Humidity Min Threshold Sensor ID Humidity Threshold # secs past threshold Requires attached temperature/humidity sensor. Humidity threshold as relative humidity %
53 Scheduled Daily Time Time to trigger -- -- Time of day in military time. example: 13:01
54 Scheduled Time Interval -- -- -- Triggers every X seconds forever
55 ATS Switched to Secondary -- -- -- Applies to ATS PDUs. Triggers when Primary ATS Inlet has lost power and switches to Secondary
56 ATS Switched to Primary -- -- -- Applies to ATS PDUs. Triggers when Primary ATS Inlet has recovered and switches from Secondary to Primary
57 Secondary Power Source Lost -- -- -- Applies to ATS PDUs. Triggers when Secondary ATS Inlet has lost power.
58 Secondary Power Source Restored -- -- -- Applies to ATS PDUs. Triggers when Secondary ATS Inlet has recovered power.
59 System Power Recovery Event Bank ID -- -- Fires when the given Bank has booted up after having no power. Will fire with circuit breaker trip for supported devices. For single inlet devices, choose any bank. For Dual circuit devices, Banks are linked with inlets.
60 Monthly Scheduled Event Day of Month Hour Of Day Minute of Hour Day of month as a number between 1 and 28, hour of day as 0-23, minute as 0-59
61 Weekly Scheduled Event Day of Week Hour of Day Minute of hour Day of week as 0-6, hour of day as 0-23, minute at 0-59
62 Digital Input State High Sensor Port (A or B) Digital Input Index (1-6) # secs past threshold Requires SPA-0140 Smart IO Hub. Triggers an event when a hub's digital input senses high for # secs past threshold
63 Digital Input State Low Sensor Port (A or B) Digital Input Index (1-6) # secs past threshold Requires SPA-0140 Smart IO Hub. Triggers an event when a hub's digital input senses low for # secs past threshold
64 User Switch Triggered Sensor Port (A or B) State triggered to -- Requires SPA-0140 Smart IO Hub. If state is triggered OFF, then when user switch is turned off, event is triggered
65 Sensor Connected/Disconnected Sensor Port (A or B) Connect/Disconnect --

Actions

Actions are operations that are triggered from an event. Examples include email notifications, outlet reboots, send snmp traps.

Action Object

{
  "name": "Reboot Router Outlet",
  "id": 3,
  "enabled": true,
  "code": 12,
  "params": [
    "4-286331153"
  ]
}
Key Type Description
name string Name for action
id number Unique identifier for action
enabled boolean Enable or disable execution of action after trigger.
code number Code for action. See Action Code Table
params array Array of strings. Corresponds to action code. See Action Code Table

 

List All Actions

GET     /api/actions               Grab list of all actions

Example Request

  curl 'http://192.168.1.100/api/events' \
  --header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k'

Expected response is a list of Action Object

Create New Action

POST /api/actions      Create a new Action

Request

Follows Authentication Scheme

{
  "name": "Reboot Router Outlet",
  "code": 12,
  "params": [
    "4-286331153"
  ]
}

name required Name string up to 100 characters

code required Action code for particular action. See Action Code Table.

params required for certain triggers See Action Code Table. Array of strings, maximum 3 parameters.

Example Request

curl 'http://192.168.1.100/api/actions' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
--data '{"name":"Reboot Router Outlet","code":12,"params":["4-286331153"]}'

Expected response is an Action Object

Modify Action

POST  /api/actions/:action_id    Modifies specific action

Follows Authentication Scheme

Same request body as Creating New Action

Example Request

curl 'http://192.168.1.100/api/actions/1' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k' \
--data '{"name":"Reboot Router Outlet","code":12,"params":["5-286331153"]}'

Expected response is an Action Object

Delete Action Permanently

DELETE  /api/actions/:action_id   Permanently remove action

Request

Follows Authentication Scheme

{} // no request parameters

Example Request

curl -X DELETE 'http://192.168.1.100/api/actions/1' \
--header 'Cookie: SPID=j2d36cG2ciHKDDqFc3k'

Expected response is a 200 HTTP response for success.

Action Code Table

Code Name Parameter 1 Parameter 2 Parameter 3 Description
11 Switch Outlet Outlet ID State to switch to -- State to switch to. either "ON" or "OFF"
12 Reboot Outlet Outlet ID -- --
15 Email Recipient Email Address -- -- Must have SMTP settings configured.
16 Switch Outlet Group Group ID State to switch to -- State to switch to. Either "ON" or "OFF"
17 Powercycle Outlet Group Group ID -- --
18 SNMPv2 Trap Notification Trap Manager Host Trap Community String --
19 SNMPv3 Trap Notification Trap Manager Host -- --
20 HTTP Post Request URL/IP Address Optional Power Stats -- Using URL requires proper DNS Configuration. Stat Options: "none", "inlets", "sensors", "outlets", and "circuits"
22 Switch Output Relay Output Relay Name State to switch to -- Only available on PDUs with Output Relay
23 Reboot Output Relay Output Relay Name -- -- Only available on PDUs with Output Relay
24 Switch Off Other PDU Outlet IP of Other PDU Outlet ID or Index Personal Access Token from Other PDU Performs action on "Other" PDU on the same network
25 Switch On Other PDU Outlet IP of Other PDU Outlet ID or Index Personal Access Token from Other PDU Performs action on "Other" PDU on the same network
26 Switch Off Other PDU Outlet Group IP of Other PDU Group ID or Index Personal Access Token from Other PDU Performs action on "Other" PDU on the same network
27 Switch On Other PDU Outlet Group IP of Other PDU Group ID or Index Personal Access Token from Other PDU Performs action on "Other" PDU on the same network
28 Reboot Other PDU Outlet IP of Other PDU Outlet ID or Index Personal Access Token from Other PDU Performs action on "Other" PDU on the same network
29 Reboot Other PDU Outlet Group IP of Other PDU Group ID or Index Personal Access Token from Other PDU Performs action on "Other" PDU on the same network
30 Switch Secondary Network Interface -- -- Requires USB-to-Ethernet Accessory to enable Secondary NIC
31 Reset kWh Meter -- -- Only available on PDUs with Energy Metering.
32 Smart IO Hub Relay Switch Sensor Port (A or B) Output Relay Index (1-6) Output Relay State (OPEN/CLOSE) Requires SPA-0140 Smart IO Hub. Switches a output relay.

KWH History

KWH History shows kwh measurements taken at the first of every month. It works independently of the "reset energy accumulator" measurements. Stores up to 12 months worth of data. KWH History is available for each individual bank.

KWH History Object

Key Type Description
bankName string Name for bank/circuit which the kWh measurements are associated with
inletId string ID for inlet which the kWh measurements are associated with
serialNumber number Serial number for circuit where kWh measurement is taken
data array Array of data points with timestamps recorded one month apart. 0 value for timestamp should be ignored.
data[].timestamp number Unix timestamp for which kWh measurement was recorded. 0 values should be ignored.
data[].kwh number energy measurement as kWh value. 
[
    {
        "bankName": "Bank 1",
        "inletId": "I1-1502793",
        "serialNumber": 2001599,
        "data": [
            {
                "timestamp": 0,
                "kwh": 0
            },
            {
                "timestamp": 0,
                "kwh": 0
            },
            {
                "timestamp": 0,
                "kwh": 0
            },
            {
                "timestamp": 0,
                "kwh": 0
            },
            {
                "timestamp": 1632504072,
                "kwh": 0
            },
            {
                "timestamp": 1635096072,
                "kwh": 0
            },
            {
                "timestamp": 1637774472,
                "kwh": 0
            },
            {
                "timestamp": 1640366472,
                "kwh": 1.1
            },
            {
                "timestamp": 1643044872,
                "kwh": 3.33
            },
            {
                "timestamp": 1645723272,
                "kwh": 5.98
            },
            {
                "timestamp": 1648142472,
                "kwh": 8.87
            },
            {
                "timestamp": 1650820872,
                "kwh": 12.42
            },
            {
                "timestamp": 1652894420,
                "kwh": 18.87
            }
        ]
    }
]

Calculate Energy Consumption for a single month

There is an internal KWH meter that never gets deleted. Once a month on the 1st, this internal KWH meter value is recorded.

To calculate the energy consumption for a single month, start with identifying the month you are interested in. Timestamps are saved in unix time stamp format. There are online converters to get human readable time information from unix time stamps.

Once you've identified the month you'd like, find the first time stamp after the month of interest. For instance, if you are interested in February's KWH consumption, identify the timestamp marked March 1.

Subtract March 1st's kwh value from the previous timestamp's kwh value. This will give you the KWH for March.

Calculate Energy Consumption for a Single Month

There is an internal KWH meter that never gets deleted. Once a month on the 1st, this internal KWH meter value is recorded.

To calculate the energy consumption for a single month, start with identifying the month you are interested in. Timestamps are saved in unix time stamp format. There are online converters to get human readable time information from unix time stamps.

Once you've identified the month you'd like, find the first time stamp after the month of interest. For instance, if you are interested in February's KWH consumption, identify the timestamp marked March 1.

Subtract March 1st's kwh value from the previous timestamp's kwh value. This will give you the KWH for March.

Calculate Month To Date (MTD) kWh

In order to calculate the Month-to-Date (MTD) kWh, you need two pieces of information from the PDU: 1. The kWh at the 1st of the current month. 2. The latest and current kWh

To get the kwh at the 1st of the current month, get the output of GET /api/kwhHist, access the last item inside the "data" array. To get the latest and current kWh, get the output of GET /api/diagnostics and access the lifetimeInletEnergyAccumulation value.

Subtract the latest from the kwh at the 1st of the month to calculate the month to date kwh.

Get KWH History

Retrieve PDU device information.

GET    /api/kwhHist      Returns object describing top level device information

Example Request

curl 'http://192.168.1.100/api/kwhHist' \
--header 'Authorization: Bearer j2d36cG2ciHKDDqFc3k'

Response Body

[
    {
        "bankName": "Bank 1",
        "inletId": "I1-1502793",
        "serialNumber": 2001599,
        "data": [
            {
                "timestamp": 0,
                "kwh": 0
            },
            {
                "timestamp": 0,
                "kwh": 0
            },
            {
                "timestamp": 0,
                "kwh": 0
            },
            {
                "timestamp": 0,
                "kwh": 0
            },
            {
                "timestamp": 1632504072,
                "kwh": 0
            },
            {
                "timestamp": 1635096072,
                "kwh": 0
            },
            {
                "timestamp": 1637774472,
                "kwh": 0
            },
            {
                "timestamp": 1640366472,
                "kwh": 1.1
            },
            {
                "timestamp": 1643044872,
                "kwh": 3.33
            },
            {
                "timestamp": 1645723272,
                "kwh": 5.98
            },
            {
                "timestamp": 1648142472,
                "kwh": 8.87
            },
            {
                "timestamp": 1650820872,
                "kwh": 12.42
            },
            {
                "timestamp": 1652894420,
                "kwh": 18.87
            }
        ]
    }
]

System Utility Endpoints

Requires Proper Permissions for user for each separate System Utility Endpoint. Configure permissions as admin user on web interface in Settings -> Manage Users section.

Factory Reset Configuration

Call this endpoint to return PDU to factory default

POST    /api/system/configReset  Reset all configuration to factory default

Reboot PDU

Call this endpoint to reboot the controller module of the PDU.

THIS DOES NOT AFFECT YOUR OUTLET RELAY STATES.

If you call this, your outlet states will not change.

POST    /api/system/reboot       Reboot PDU.

Upload Firmware Binary

With appropriate firmware files, update your SynLink PDU Operating System via HTTP API.

POST    /api/system/firmware     Upload firmware binary to firmware upgrade. If valid binary, upgrade occurs immediately

Example Request

  curl \
  -F filename=@/home/user/file_location \
  --header 'Cookie: SPID=j2d36cG2ciHKDDqFc3k'
  http://192.168.1.100/api/system/firmware

WebSocket

WebSocket Data Stream

When successfully connected AND authenticated. SynLink PDU's will output a data stream onto a WebSocket with the following WebSocket Data Stream Object at a rate of once every 2 seconds.

WebSocket Data Stream Object

Key Type Description
device object Object with uptime and time
banks array Array of WebSocket Bank Object(s)
inlets array Array of WebSocket Inlet Object(s)
outlets array Array of WebSocket Outlet Objects if applicable
sensors array Array of Sensor Outlet Object(s) if connected

WebSocket Device Object

Key Type Description
uptime number Number of seconds the PDU has been on.
time string Time in ISO8601 String Format.

WebSocket Bank Object

Key Type Description
id string Unique identifier for the bank
currentRms number The instantaneous current measured at the inlet in Amps
voltageRms number Instantaneous voltage reading at inlet and all outlets in volts
lineFrequency number Line Frequency measurement valid from 45-65 GHz
powerFactor number Power Factor reading. Value is signed value representing polarity of power factor
activePower number Active Power measured in KW (kiloWatts). Power consumed by electrical resistance
apparentPower number Power which is actually consumed or utilized
energyAccumulation number Number of kilowatt hours accumulated. Can be used as billing unit for energy delivered
hasCircuitBreakerProtection boolean true if PDU has circuit breaker protection.
circuitBreakerClosed boolean State of circuit breakers. true if circuit breaker is closed and providing power correctly.

WebSocket Inlet Object

Key Type Description
id string Unique identifier for Inlet
inletType string Describes configuration of specific Inlet Object. Either "single", "dual", or "ats".
inletPlug string Connector type for Inlet
inletName string User defined name for inlet
inletEnergyAccumulation number kWH value to show energy consumption for inlet plug. If multiple inlets, value will stay same for all inlets.

Conditional WebSocket Inlet Object Attributes

Is available when PDU is a three phase PDU

Key Type Description
inletPowerFactor number Power factor value for inlet plug
threePhaseBalance string Percentage unbalance for 3 phase circuit
inletLines array Contains 3 line objects, each with "currentRMS" in amps, unique "id", and "line" it is associated with.

Is available when PDU is a single phase PDU

Key Type Description
inletCurrentRms number Inlet current draw in amps
inletVoltageRms number Inlet voltage RMS in volts
inletLineFrequency number Inlet line frequency in hertz
inletPowerFactor number Power factor ratio
inletActivePower number Inlet Active Power in watts
inletApparentPower number Inlet Apparent Power in Volt-amperes (VA)
inletLineConfiguration string Line configuration for outlets connected to this inlet.

Is available when PDU is an ATS PDU

Key Type Description
atsInletId string Either "A" or "B". Matches label on PDU.
atsInletActive boolean true if inlet is used to power outlets.
atsInletReady boolean true if inlet has voltage potential

Data Stream Object

{
  "device": {
    "uptime": 251362,
    "time": "2012-01-03T22:34Z"
  },
  "banks": [
    {
      "id": 16777225,
      "currentRms": 0.007400000002235174,
      "voltageRms": 117.0999984741211,
      "lineFrequency": 60.1879997253418,
      "powerFactor": -0.465087890625,
      "activePower": 0.4000000059604645,
      "apparentPower": 0.8600000143051147,
      "hasCircuitBreakerProtection": false,
      "circuitBreakerClosed": true,
      "energyAccumulation": 0
    },
    ...
  ],
  "inlets": [
    {
      "id": "I1-9826498",
      "inletCurrentRms": 0.007400000002235174,
      "inletVoltageRms": 117.0999984741211,
      "inletLineFrequency": 60.1879997253418,
      "inletPowerFactor": 0.4651162922382355,
      "inletActivePower": 0.4000000059604645,
      "inletApparentPower": 0.8600000143051147,
      "inletEnergyAccumulation": 0
    }
  ],
  "outlets": [
    {
      "id": "1-16777225",
      "currentRms": 0.16098617017269135,
      "state": "ON",
      "voltageDetection": true,
      "relayHealth": "OK"
    },
    ...
  ],
  "sensors": [
    {
      "sensorPort": "B",
      "sensorName": "Temperature & Humidity Sensor",
      "sensorTempInC": 18.23232650756836,
      "sensorTempInF": 64.81819152832031,
      "sensorHumidity": 59.186912536621094,
      "sensorType": "temp_hum"
    },
    ...
  ]
}

Web Hook / Post HTTP Requests

Post HTTP Request Actions for Events

Post HTTP can be configured to send on a configured event

The following JSON object is the structure depending on optionally added stats.

Example Web Hook Data Structure

{
  "eventCode": 15,
  "eventName": "Example Inlet Max Current",
  "enclosureSerialNumber": "1000016",
  "valueExceedingThreshold": 0,
  "outlets": [ OUTLET OBJECTS ], // optional
  "inlets": [ INLET OBJECTS ], // optional
  "banks": [ BANK OBJECTS ], // optional
  "sensors": [ SENSORS ] // optional
}