Welcome to Altronix LinQ Product documentation¶

The following documentation outlines initial public release of Altronix LinQ product’s API. Please check back often as this documentation is expected to grow. Should you not find what you are looking for - please contact info@altronix.com for further inquiry and we can accelerate the documentation of specific parts of the API per your needs.

The Altronix LinQ api is divided into ‘Common’ parts and ‘Product’ specific parts.

Contents¶

HTTP API¶

Overview¶

The API is divided into two parts.

Common API contain RESTful endpoints common to all Altronix LinQ enabled products
Product API are unique RESTful endpoints per each product. Product API’s contain all of the common API plus the additional product specific API

Supported HTTPs Requests¶

GET: Retrieve a resource or collection of resources
POST: Edit or Create a resource or collection of resources
PUT: Same as POST. (–info) Note that resources are static and therefore PUT and POST are interpretted as the same)
DELETE: Remove or zero a resource

Supported HTTPs Responses¶

200 (OK) The request was successful, new state was accepted
400 (Bad Request) The request was not successful. The server rejected the request because of one of the following reasons
- The request had bad format
403 (Unauthorized) The credentials supplied with the request were not valid. Or the credentials supplied with the request are valid, but the user does not have access to the requested resource.
404 (Not found) The resource endpoint does not exist
500 (Internal Server Error) The server cannot process the request at this time.

Supported Authentication Scheme¶

All Altronix LinQ enabled products support Basic Authentication specification. Therefore the server expects the ‘Authorization’ header to be provided with each request requiring credentials.

| GET /ATX/userManagement/users\r\n
| Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l\r\n

Common¶

The following documentation outlines the Altronix API common to all Altronix LinQ products.

Saving settings to ROM¶

POST /ATX/exe/save¶

Save current state into persistent memory of the device. Without saving data, most of the state of the database will not persist across a reboot.

Example request:

POST /ATX/exe/save HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript
Content-Type: application/json

{
   "save":1
}

Request JSON Object:
	save (number) – Save profile index. (Currently only supports one profile)

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "error":200
}

Alert types¶

GET /ATX/alerts/types¶

Returns a list of all the supported alert types for the product. Different products may support different alert types. For a detailed list of each alert type per product please reference the product specific api notes for your specific product. Below describes the API format in general form for all products.

Example request:

GET /ATX/alerts/types HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
  "types": {
    "acFail": {
      "name": "acFail",
      "mesg": "AC input failure",
      "timer": 0
    },
    "acFailR": {
      "name": "acFailR",
      "mesg": "AC input return",
      "timer": 0
    },
    "battFail": {
      "name": "battFail",
      "mesg": "Battery fail",
      "timer": 0
    },
    "battFailR": {
      "name": "battFailR",
      "mesg": "Battery return",
      "timer": 0
    },
    "sysUp": {
      "name": "sysUp",
      "mesg": "System Startup",
      "timer": 0
    },
    "...continued": {
      "...": ""
    }
  }
}

Response JSON Object:
	name (string) – The name of alert. Is a KEY property to map alerts with a human readable message mesg (string) – The message describing the alert. timer (number) – A number in seconds used to filter alerts. When an alert condition only persists for less than x seconds, the alert will be filtered

Number of alerts since last power up¶

GET /ATX/alerts/count¶

Returns the number of alerts since last power up. The number is incremented per each alert as they occur.

Example request:

GET /ATX/alerts/count HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "count":25
}

Response JSON Object:
	count (number) – The number of alert events since last power up

Most recent alerts¶

GET /ATX/alerts/recent¶

Return a minimal set of the most recent alerts (Max 5)

Example request:

GET /ATX/alerts/recent HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "recent": [{
     "who": "system",
     "what": "Power Supply ID",
     "when": 1520445079,
     "name": "ihigh",
     "mesg": "Over current",
     "siteId": "Demo Laptop"
   }, {
     "who": "system",
     "what": "Power Supply ID",
     "when": 1520445079,
     "name": "ihigh",
     "mesg": "Over current",
     "siteId": "Demo Laptop"
   }, {
     "who": "admin",
     "what": "Power Supply ID",
     "when": 1520445407,
     "name": "psOff",
     "mesg": "Power supply off",
     "siteId": "Demo Laptop"
   }, {
     "who": "admin",
     "what": "Power Supply ID",
     "when": 1520445413,
     "name": "psOn",
     "mesg": "Power supply on",
     "siteId": "Demo Laptop"
   }]
}

Response JSON Object:

who (string) – The name of the user who caused the reason for the alert
what (string) – The name of the port or power supply that is cause for alert
when (number) – The unix time stamp of when the alert was generated
name (string) – The alert [key] property used to map alert types to a human readable message
mesg (string) – A human readable message describing the alert
siteId (string) – The location of where the device that caused the alert

Reading entire event history¶

GET /ATX/alerts/all¶

Return the entire log history from the peristant storage of the device. Note the JSON properties are a minimal set of alert meta data. For additinal data referencing the alert you can map the alert name with the alert type to reference relavent alert meta-data.

Example request:

GET /ATX/alerts/all HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "log": [
     { "who": "system", "what": "log reset", "when": 0 },
     { "who": "admin", "what": "Power Supply ID", "when": 1519057709, "name": "psOff" },
     { "who": "admin", "what": "Power Supply ID", "when": 1519057713, "name": "psOn" },
     { "who": "admin", "what": "Power Supply ID", "when": 1519826227, "name": "psOff" },
     { "who": "admin", "what": "Power Supply ID", "when": 1519826485, "name": "psOn" },
     { "who": "system", "what": "test", "when": 1519840284, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519840292, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519840356, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519846949, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519846963, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519846967, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519846972, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519847044, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519847047, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519847067, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519847071, "name": "tmr" },
     { "who": "system", "what": "test", "when": 1519847075, "name": "battFail" },
     { "who": "system", "what": "test", "when": 1519847080, "name": "ilowR" },
     { "who": "system", "what": "test", "when": 1519847152, "name": "psOn" },
     { "who": "system", "what": "test", "when": 1519847160, "name": "psOff" },
     { "who": "system", "what": "test", "when": 1519847174, "name": "rOn" },
     { "who": "admin", "what": "Power Supply ID", "when": 1519847194, "name": "psOff" },
     { "who": "admin", "what": "Power Supply ID", "when": 1519847247, "name": "psOn" },
     { "who": "admin", "what": "Power Supply ID", "when": 1520445407, "name": "psOff" },
     { "who": "admin", "what": "Power Supply ID", "when": 1520445413, "name": "psOn" }
   ]
}

Response JSON Object:
	who (string) – The name of the user who caused the reason for the alert what (string) – The name of the port or power supply that is cause for alert when (number) – The unix time stamp of when the alert was generated name (string) – The alert [key] property used to map alert types to a human readable message

User Management¶

GET /ATX/userManagement/users¶

Returns an array of users permissioned to access the device at various restriction levels

Example request:

GET /ATX/userManagement/users HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "users": ["admin", "thomas"]
}

GET /ATX/userManagement/users/(string: user_id)¶

Returned detailed meta-data for a specific user

Example request:

GET /ATX/userManagement/users/thomas HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "thomas": {
     "user": "thomas",
     "fail": 0,
     "enable": 1,
     "realms": ["/ATX/userManagement/users/thomas/pass", "1:/ATX/userManagement/users", "3:/ATX/exe/save"]
   }
}

Response JSON Object:
	user (string) – The name of the user in reference fail (string) – The number of failed login attempts enable (number) – 1 - user is enabled, 0 - user is not enabled realms (object) – An array of URL endpoints that this user is allowed to have access too.

POST /ATX/userManagement/users¶

Create an additional user

Example request:

POST /ATX/userManagement/users HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript
Content-Type: application/json

{
   "user":"new user name",
   "pass":"new user password",
   "realms":["/"]
}

Request JSON Object:
	user (string) – The name of the new user pass (string) – The password of the new user realms (number) – An array of realms this new user shall have access too

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "error":200
}

Products¶

The following documentation outlines the Altronix API specific to the Altronix LinQ product. Product API’s include all of the LinQ HTTP API (common) resources plus the additional product specific API’s.

LinQ2¶

Alert types¶

GET /ATX/alerts/types¶

Returns a list of all the supported alert types for the LinQ2 product.

Example request:

GET /ATX/alerts/types HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "types": {
     "tmr": { "name": "tmr", "mesg": "Timer event trigger", "timer": 0 },
     "acFail": { "name": "acFail", "mesg": "AC input failure", "timer": 0 },
     "acFailR": { "name": "acFailR", "mesg": "AC input return", "timer": 0 },
     "battFail": { "name": "battFail", "mesg": "Battery fail", "timer": 0 },
     "battFailR": { "name": "battFailR", "mesg": "Battery return", "timer": 0 },
     "battServ": { "name": "battServ", "mesg": "Service Battery", "timer": 0 },
     "battServR": { "name": "battServR", "mesg": "Battery serviced", "timer": 0 },
     "psOn": { "name": "psOn", "mesg": "Power supply on", "timer": 0 },
     "psOff": { "name": "psOff", "mesg": "Power supply off", "timer": 0 },
     "ilow": { "name": "ilow", "mesg": "Under current", "timer": 0 },
     "ilowR": { "name": "ilowR", "mesg": "Under current clear", "timer": 0 },
     "ihigh": { "name": "ihigh", "mesg": "Over current", "timer": 0 },
     "ihighR": { "name": "ihighR", "mesg": "Over current clear", "timer": 0 },
     "rOn": { "name": "rOn", "mesg": "Relay engaged", "timer": 0 },
     "rOff": { "name": "rOff", "mesg": "Relay dis-engaged", "timer": 0 },
     "input": { "name": "input", "mesg": "Input trigger", "timer": 0 },
     "test": { "name": "test", "mesg": "this is an example alert", "timer": 0 },
     "sysUp": { "name": "sysUp", "mesg": "System Startup", "timer": 0 }
   }
}

Response JSON Object:

tmr (string) – The timer alert is recorded when a timer event expires
acFail (string) – The acFail alert is recorded when the AC failes below the eFlow specification AC input requirements
acFailR (string) – The acFailR alert is recorded when the AC recovers from an AC fail condition
battFail (string) – The battFail alert is recorded when the eFlow battery is presently installed but is reporting under voltage
battFailR (string) – The battFailR alert is recorded when the eFlow battery is presently installed and has recovered from an under voltage condition
psOn (string) – The psOn alert is recorded when a LinQ administrator turns on an eFlow Power Supply
psOff (string) – The psOff alert is recorded when a LinQ administrator turns off an eFlow Power Supply
iLow (string) – The iLow alert is recorded when a LinQ administrator has configured minimum load requirments, and the load to the eFlow Power Supply has dropped below limit the under current limit
iLowR (string) – The iLow alert is recorded when the eFlow Power Supply recoveres from an under current condition
iHigh (string) – The iHigh alert is recorded when a LinQ administrator has configured maximum load requirments, and the load to the eFlow Power Supply has exceeded the over current limit
iHighR (string) – The iHighR alert is recorded when the eFlow Power Supply recoveres from an over current condition
rOn (string) – The rOn alert is recorded when a LinQ administrator turns on a relay
rOff (string) – The rOff alert is recorded when a LinQ administrator turns off a relay
input (string) – The input alert is recorded when a LinQ2 module input trigger is engaged
test (string) – The test alert is recorded when a LinQ administrator activates a test alert. A test alert is used to simulate any of the other alert types and can be helpful when diagnosing alert notification configuration
sysUp (string) – The sysUp alert is recorded when the LinQ2 module first powers on (typically after a reboot or a power cycle event)
name (string) – The name of alert. Is a KEY property to map alerts with a human readable message
mesg (string) – The message describing the alert.
timer (number) – A number in seconds used to filter alerts. When an alert condition only persists for less than x seconds, the alert will be filtered

Device IO summary¶

GET /ATX/hardware¶

Returns a summary of the IO state of all hardware inputs, relays, and power supplies. For detailed information on JSON object properties, refer to the more explicit non-summary api, (IE: /ATX/hardware/eflows/eflow0)

Example request:

GET /ATX/hardware HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "hardware": {
     "exe": { "save": "application" },
     "eflows": {
       "eflow0": {
         "id": "Power Supply ID",
         "type": "",
         "psPresence": 1,
         "ps": 1,
         "pulse": -15,
         "status": "on",
         "ac": 0,
         "batt": 0,
         "vCal": 13863,
         "iCal": 4266,
         "v": 8000,
         "i": 13000,
         "vHigh": 28000,
         "iHigh": 5000,
         "iLow": 0,
         "service": 0,
         "reminder": 0,
         "battPresence": 1,
         "installation": 0,
         "timers": 500
       },
       "eflow1": {
         "id": "Power Supply ID",
         "type": "",
         "psPresence": 1,
         "ps": 1,
         "pulse": -15,
         "status": "on",
         "ac": 0,
         "batt": 0,
         "vCal": 13863,
         "iCal": 4266,
         "v": 7000,
         "i": 9000,
         "vHigh": 28000,
         "iHigh": 5000,
         "iLow": 0,
         "service": 0,
         "reminder": 0,
         "battPresence": 1,
         "installation": 0,
         "timers": 500
       },
       "mask": ""
     },
     "relays": {
       "relay0": { "id": "Relay ID", "status": 0, "pulse": -15 },
       "relay1": { "id": "Relay ID", "status": 0, "pulse": -15 },
       "mask": ""
     },
     "inputs": {
       "input0": { "id": "Input ID", "status": 0, "test": 0, "cmds": [] },
       "input1": { "id": "Input ID", "status": 0, "test": 0, "cmds": [] },
       "input2": { "id": "Input ID", "status": 0, "test": 0, "cmds": [] }
     },
     "temp": 0,
     "temp": 12205
   }
}

Power supplies¶

GET /ATX/hardware/eflows/(string: index)¶

Returns the state of the Eflow Power Supply at the respective index

Example request:

GET /ATX/hardware/eflows/eflow0 HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
  "eflow0": {
    "id": "Power Supply ID",
    "type": "",
    "psPresence": 1,
    "ps": 1,
    "pulse": -15,
    "status": "on",
    "ac": 0,
    "batt": 0,
    "vCal": 13863,
    "iCal": 4266,
    "v": 8000,
    "i": 13000,
    "vHigh": 28000,
    "iHigh": 5000,
    "iLow": 0,
    "service": 0,
    "reminder": 0,
    "battPresence": 1,
    "installation": 0
  }
}

Response JSON Object:

id (string) – The name of the resource (IE a relay or Eflow Power Supply can be named and are tagged with this name should an alert occur from this resource).
type (string) – The eflow type used to scale the voltage and current. IE: eFlow3NB
psPresense (string) – A boolean indicator to inform the system if the Eflow Power Supply is installed or not installed (1-installed, 0-not installed)
ps (string) – A boolean indicator to indicate if the Eflow Power Supply is on or off (1-on, 0-off)
pulse (number) – number of seconds to pulse the Eflow Power Supply, should a pulse command be executed. (<0 pulse off, >0 pulse on)
status (string) – Human readable string indicating the status of the Eflow Power Supply. (IE: “on”/”off”)
ac (number) – Boolean indicator for AC status. (0 - AC fail, 1 - AC OK)
batt (number) – Boolean indicator for Battery status. (0 - Battery fail, 1 - Battery OK)
vCal (number) – TODO - calibration
iCal (number) – TODO - calibration
v (number) – Voltage level in (mV)
i (number) – Current level in (mA)
vHigh (number) – Over voltage threshold settings (mV)
iHigh (number) – Over Current threshold setting (mA)
iLow (number) – Under Current threshold setting (mA)
service (number) – Unix date code when battery service is expected
reminder (number) – Should battery serice reach expirey, an alert will be generated every [reminder] intervals (days)
battPresence (number) – Boolean indicator representing the presence of a battery per this Eflow Power Supply. (0 - no battery installed, 1 - battery installed)
installation (number) – Unix date code when the battery was installed, set by the administrator

POST /ATX/hardware/eflows/(string: index)/status¶

Change the state of the Eflow Power Supply output

Example request:

POST /ATX/hardware/eflows/eflow0/status HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript
Content-Type: application/json

{
   "status":0
}

Request JSON Object:

status (string) – If the supplied property is a number, the Eflow Power Supply will either turn on (status=1), or turn off (status=0)
status – If the supplied property is a string, the Eflow Power Supply will either Pulse (status=’p’) or toggle (status=’t’), Where a “pulse” command will either pulse on for x seconds, or pulse off for x seconds, and where seconds is determined by the “pulse” property of the same eflow object.

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "error":200
}

Inputs¶

GET /ATX/hardware/inputs/(string: index)¶

Returns the state of the linq2 input at the respective index

Example request:

GET /ATX/hardware/inputs/input0 HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "input0": {
     "id": "Input ID",
     "status": 0,
     "test": 0,
     "cmds": [{
       "url": "/ATX/hardware/eflows",
       "data": {
         "mask": "px"
       }
     }]
   }
}

Response JSON Object:

id (string) – The name of the input resource. If an input event is triggered and the alert per this input is not masked, an alert will be recorded and the alerts ‘what’ property will contain this ID field
status (number) – The current state of the input. (1 - active, 0 - in-active). Note that the input triggers on the LinQ2 module are active low
cmds (object) – An array of commands to execute should the input go active. These commands can be any API command as supported by the device API. (Linq Common API + LinQ2 Product API)
url (string) – When the commands array is executed by the input trigger, the URL is the resource location per the API.
data (object) – When the commands array is executed by the input trigger, the data property contains POST data included with the URL.

Relays¶

GET /ATX/hardware/relays/(string: index)¶

Returns the state of the linq2 relays at the respective index

Example request:

GET /ATX/hardware/relays/relay0 HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "relay1": {
       "id": "Relay ID",
       "status": 0,
       "pulse": -15
   }
}

Response JSON Object:

id (string) – The name of the relay resource. If an relay event is triggered and the alert per this relay is not masked, an alert will be recorded and the alerts ‘what’ property will contain this ID field
status (number) – The current state of the relay. (1 - active, 0 - in-active).
pulse (number) – number of seconds to pulse the power supply, should a pulse command be executed. (<0 pulse off, >0 pulse on)

POST /ATX/hardware/relay/(string: index)/status¶

Change the state of the Relay

Example request:

POST /ATX/hardware/relay/relay0/status HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript
Content-Type: application/json

{
   "status":0
}

Request JSON Object:

status (string) – If the supplied property is a number, the relay will either turn on (status=1), or turn off (status=0)
status – If the supplied property is a string, the relay will either Pulse (status=’p’) or toggle (status=’t’), Where a “pulse” command will either pulse on for x seconds, or pulse off for x seconds, and where seconds is determined by the “pulse” property of the same relay object.

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "error":200
}

LinQ8¶

Netway / Ebridge¶

Device IO summary¶

GET /ATX/hardware¶

Returns a summary of the IO state of all PoE (power over ethernet) ports. For detailed information on JSON object properties, refer to the more explicit non-summary api, (IE: /ATX/hardware/eflows/eflow0)

Example request:

GET /ATX/hardware HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "TODO":"TODO"
}

PoE Output channels¶

GET /ATX/hardware/outputs/(string: index)¶

Returns the state of the PoE Channel at the respective index. TODO verify URL

Example request:

GET /ATX/hardware/outputs/ch2 HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "TODO":"TODO"
}

Response JSON Object:
	id (string) – The name of the resource (IE a relay or PoE Channel can be named and are tagged with this name should an alert occur from this resource). status (string) – Human readable string indicating the status of the PoE Channel. (IE: “on”/”off”) ... (string) – TODO

POST /ATX/hardware/outputs/(string: index)/status¶

Change the state of the PoE Chanenl output

Example request:

POST /ATX/hardware/outputs/ch3/status HTTP/1.0
Host: 192.168.168.168
Accept: application/json, text/javascript
Content-Type: application/json

{
   "status":0
}

Request JSON Object:

status (string) – If the supplied property is a number, the PoE Channel will either turn on (status=1), or turn off (status=0)
status – If the supplied property is a string, the PoE Channel will either Pulse (status=’p’) or toggle (status=’t’), Where a “pulse” command will either pulse on for x seconds, or pulse off for x seconds, and where seconds is determined by the “pulse” property of the same eflow object.

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
   "error":200
}

Welcome to Altronix LinQ Product documentation¶

Contents¶

HTTP API¶

Overview¶

Supported HTTPs Requests¶

Supported HTTPs Responses¶

Supported Authentication Scheme¶

Common¶

Saving settings to ROM¶

Alert types¶

Number of alerts since last power up¶

Most recent alerts¶

Reading entire event history¶

User Management¶

Products¶

LinQ2¶

Alert types¶

Device IO summary¶

Power supplies¶

Inputs¶

Relays¶

LinQ8¶

LinQ8¶

Netway / Ebridge¶

Device IO summary¶

PoE Output channels¶

ZMTP API¶

Overview¶