API Reference

RAN Provider REST APIs provide direct data access to Base Station information for use in external monitoring and reporting. An API key is required to authenticate API usage. API keys are created and managed in the API Keys view.

To get started with the Base Station APIs, see the Swagger API Documentation.

Base Station Provisioning API

The Base Station Provisioning API is designed to allow a customer to provision a set of Base Stations. This is similar to the bulk provisioning workflow provided by the UI and allows them to setup a Base Station before deploying it. They can enter basic provisioning information such as; eui, serial number, Base Station type, and ISM Band.

Resource URL

https://api.senraco.io/rest/integration/bstn/provision

HTTP Method

POST

Parameters

None

Request Body(JSON)

Parameter	Description	Required	Default Value	Allowed Values
data	An array containing all the Base Stations you wish to provision. See Base Station object section below	Yes		A correctly formatted JSON Array

Base Station Object

See CSV File Format under Base Station Management.

Base Station Models

See Base Station Models under Base Station Management.

ISM Band Names

See ISM Band Names under Base Station Management.

Response

Field Description	Description
jobid	The ID of the currently executing Base Station provisioning job. Can be used with the base station task status API
responseMsg	The response message from the server indicating if the job was started
serverId	The ID of the server processing the request
statusCode	The status of the job being correctly started

HTTP Response Codes

Code	Reason	Description
200	Success	Request has been successfully processed
403	Authorization Failure	Access to this resource has been rejected due to an authorization issue.
400	Bad Request	Invalid request due to insufficient or malformed parameters.

Example request:

{
    "data": [
         {
            "eui" : "FAFFFFFFFFFF0001",
            "serialNum" : "F1F3F2F1",
            "ismBandName" : "US902-928:Default",
            "model" : "MULTITECH_CONDUIT",
            "channelConfig": [5], 
            "tags"  : "Docs Example,Portsmouth"
        },

        {
            "eui" : "FAFFFFFFFFFF0000",
            "serialNum" : "TF000000_000000001",
            "ismBandName" : "EU863-870:Default",
            "model" : "TEKTELIC_KONA_64",
            "tags"  : "Docs Example,Portsmouth"
        },

        {
            "eui" : "FAFFFFFFFFFF0002",
            "serialNum" : "0X0F0F0F3",
            "ismBandName" : "AU915-928:Default",
            "model" : "KERLINK_IOTS",
            "tags"  : "Docs Example,Portsmouth" 
        },
        {
            "eui" : "FAFFFFFFFFFF0003",
            "serialNum" : "1234567890ABCDEF4",
            "ismBandName" : "India865-867:Default",
            "model" : "SEMTECH_PKT_FORWARDER",
            "tags"  : "Docs Example,Portsmouth" 
        },
        {
            "eui" : "FAFFFFFFFFFF0004",
            "serialNum" : "TF000000_000000005",
            "ismBandName" : "AS923:Default",
            "model" : "TEKTELIC_KONA_8",
            "tags"  : "Docs Example,Portsmouth" 
        }
    ]

}

Example Success Response:

{
    "jobId": "BstnMgmtJobReq:90000",
    "responseMsg": "BstnMgmtJobReq job starting now: Tue Dec 17 12:16:50 EST 2019",
    "serverId": "networkserver:OnPrem:172.18.0.1:8081",
    "statusCode": 200
}

Curl Example

curl -X POST \
  https://api.senraco.io/rest/integration/bstn/provision \
  -H 'Authorization: <your API key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": [
         {
            "eui" : "FAFFFFFFFFFF0001",
            "serialNum" : "F1F3F2F1",
            "ismBandName" : "US902-928:Default",
            "model" : "MULTITECH_CONDUIT",
            "channelConfig": [5], 
            "tags"  : "Docs Example,Portsmouth"
        },

        {
            "eui" : "FAFFFFFFFFFF0000",
            "serialNum" : "TF000000_000000001",
            "ismBandName" : "EU863-870:Default",
            "model" : "TEKTELIC_KONA_64",
            "tags"  : "Docs Example,Portsmouth"
        },

        {
            "eui" : "FAFFFFFFFFFF0002",
            "serialNum" : "0X0F0F0F3",
            "ismBandName" : "AU915-928:Default",
            "model" : "KERLINK_IOTS",
            "tags"  : "Docs Example,Portsmouth" 
        },
        {
            "eui" : "FAFFFFFFFFFF0003",
            "serialNum" : "1234567890ABCDEF4",
            "ismBandName" : "India865-867:Default",
            "model" : "SEMTECH_PKT_FORWARDER",
            "tags"  : "Docs Example,Portsmouth" 
        },
        {
            "eui" : "FAFFFFFFFFFF0004",
            "serialNum" : "TF000000_000000005",
            "ismBandName" : "AS923:Default",
            "model" : "TEKTELIC_KONA_8",
            "tags"  : "Docs Example,Portsmouth" 
        }
    ]    
}'

Base Station Deploy API

The Base Station Deploy API is designed to allow deployment of a Base Station dynamically post install. This API allows information about the Base Station deployment to be updated without using the web application. The information that can be updated includes, location, height, radius, address, and name.

Note

A Base Station must be created through the provisioning workflow, if the Base Station wasn't provisioned this way, the network administrator's support team should be contacted. If a Base Station was previously deployed, subsequent deployments will override previously provided information.

Resource URL

https://api.senraco.io/rest/integration/bstn/deploy

HTTP Method

POST

Parameters

Parameter	Description	Required	Default Value	Allowed Values
eui	The IEEE EUI-64 identifier for the LoRa Base Station.	Yes		Hexadecimal String

Request Body(JSON)

Parameter	Description	Required	Allowed Values
address	The street address of the site	No	A valid street address
city	The city of the site	No	A valid city name
stateProvince	The state or province of the site	No	A valid state or province
postalCode	The postal code of the site	No	A valid postal code
name	The name of the site	No	N/A
latitude	The latitude of the site in decimal degrees	Yes	A non-zero value between 90 and -90
longitude	The longitude of the site in decimal degrees	Yes	A non-zero value between 180 and -180
height	The height above ground level of the top of the antenna in feet	Yes	A value greater than 0
radius	The radius of the sites range in miles	Yes	A value greater than 0

Curl Example

curl -X POST \
  'https://api.senraco.io/rest/integration/bstn/deploy?eui=FEFFFFFFFFFF0001' \
  -H 'Authorization: <your api key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "100 Market Street",
    "city": "Portsmouth",
    "stateProvince": "NH",
    "postalCode": "03801",
    "name": "Provisioned BSTN",
    "latitude": 44.071568,
    "longitude": -70.762245,
    "height": 100,
    "radius": 10
}'

Example request:

{
    "address": "100 Market Street",
    "city": "Portsmouth",
    "stateProvince": "NH",
    "postalCode": "03801",
    "name": "Provisioned BSTN",
    "latitude": 44.071568,
    "longitude": -70.762245,
    "height": 100,
    "radius": 10
}

Response

Code	Reason	Description
200	Success	Request has been successfully processed
403	Authorization Failure	Access to this resource was rejected due to an authorization failure
400	Bad Request	Invalid request due to insufficient or malformed parameters
404	Base Station or File Not Found	Indicates that the given Base Station EUI doesn't exist

Example Success Response:

{
    "message": "Success!"
}

Base Station Status API

The Base Station Status API returns detailed information for a set of Base Stations. This may include details about the Base Station like model type, version and uptime as well as current connection information.

There are 2 status sources supported by this API, that are selected using the required parameter.

A status source of "alert" retrieve all Base Stations that have open alerts. This should be used in most cases when monitoring for failure conditions of Base Stations under your control.
The status source of "any" can be use to retrieve the status information of all the Base Stations under your control.

Resource URL

https://api.senraco.io/rest/integration/bstn/details

HTTP Method

GET

Parameters

Parameter Name	Description	Required	Default Value	Allowed Values
eui	The IEEE EUI-64 identifier for the Base Station. Used to limit the returned data to a specific EUI.	No
status	The type of status data to use as a source. Alert=Retrieve Base Stations only with open alerts. Any=Retrieve Base Stations with or without open alerts	Yes		alert, any
fields	A comma separated list of fields names to return in the data set. Used to return a smaller subset of data than the default. Supported Fields: "status,lastContact,lastPacket,name,model,ismBandName,channelConfig,version,uptime,radius,antennaHeight,alertLevel,deltaTime,address," "location,gpsLocation,gpsAltitude"	No	All Fields	Any combination of the supported fields

Field Descriptions

Field Name	Description
status	An object containing a color to indicate visual status, a "connIssues" string that describes the network connection state, and an alertCount
lastContact	The date of the last communication from the Base Station to the Network Server
lastPacket	The date when the last packet was received from the Base Station
name	The name of the Base Station
model	The model type of the Base Station
ismBandName	The ISM Band radio frequency name assigned to the Base Station
channelConfig	The Radio Channel Bank ID(s) assigned to the Base Station
version	The firmware version installed on the Base Station
uptime	The total time the Base Station has been active in seconds
radius	The radius of the Base Station's Viewshed in miles
height	The position height of the Base Station's Viewshed in feet. This is used to determine potential signal obstruction by intervening terrain.
alertLevel	The alert configuration for the Base Station See Alerts for more details
deltaTime	The time difference between a Base Station's current time and the Network Server's current time
address	The address set for Base Station's associated Site
location	An object containing the latitude and longitude set for the Base Station
gpsLocation	An object containing a GPS obtained latitude and longitude if the Base Station supports GPS
gpsAltitude	The GPS altitude, in meters, of the Base Station if the Base Station supports GPS

Connection Status

The status field of the response data contains collective connection status for a Base Station with a color indicating an overall state. Colors are based on a combination of Connection Status, Alert Severity and Case Priority. The coloring is hierarchical, with the color of the most severe state taking precedence. This color should be the same as the color displayed for the status column in the Base Station table, the Base Station Details view and the Maps in the UI.

Status Color

Source	Value	Color
Connection Status	2 - Fully Connected(Web Socket) 1 - Partially Connected (Web Socket) 0 - Not connected (no Web Socket)	Green Orange Red
Alert Severity	Low Moderate High Urgent	Orange Orange Orange Red
Case Priority	Low Moderate High Urgent	Green Orange Orange Red

Curl Examples

Status for Base Stations with open alerts.

curl -H "authorization: <API_KEY_TO_USE>" -X GET "https://api.senraco.io/rest/integration/bstn/details?status=alert"

Status for a specific Base Station with open alerts.

curl -H "authorization: <API_KEY_TO_USE>" -X GET "https://api.senraco.io/rest/integration/bstn/details?status=alert&eui=AAAAAAAAAAAAAAAA"

Status for Base Stations with or without open alerts.

curl -H "authorization: <API_KEY_TO_USE>" -X GET "https://api.senraco.io/rest/integration/bstn/details?status=any"

Status for a Base Station with or without open alerts, only return fields "status" and "lastContact".

curl -H "authorization: <API_KEY_TO_USE>" -X GET "https://api.senraco.io/rest/integration/bstn/details?status=any&eui=AAAAAAAAAAAAAAAA&fields=status,lastContact"

Response Examples

For a single Base Station all fields returned:

{
   "data":[
      {
         "eui":"AAAAAAAAAAAAAAAA",
         "status":{
            "color":"orange",
            "connIssues":"Connection Issues: No SSH",
            "alertCount":1
         },
         "lastContact":1550691020270,
         "lastPacket":1550691080252,
         "name":"Sample BSTN",
         "model":"MultiTech Conduit AP",
         "ismBandName":"US902-928:Default",
         "version":"02_04_04",
         "uptime":30187974,
         "radius":10,
         "antennaHeight":15.01,
         "alertLevel":"Level 1",
         "deltaTime":41,
         "location":{
            "latitude":43.083412,
            "longitude":-70.77599
         },
         "gpsLocation":{
            "latitude":"43.07851",
            "longitude":"-70.7583"
         },
         "gpsAltitude":"32.16134"
      }
   ]
}

Multiple Base Stations with only the "status" and "lastContact" fields returned:

{
   "data":[
      {
         "eui":"AAAAAAAAAAAAAAAA",
         "status":{
            "color":"orange",
            "connIssues":"Connection Issues: No SSH",
            "alertCount":1
         },
         "lastContact":1550691020270
      },
      {
         "eui":"BBBBBBBBBBBBBBBB",
         "status":{
            "color":"red",
            "connIssues":"No Issues",
            "alertCount":2
         },
         "lastContact":1550691020354
      }
   ]
}

Network Management Notification API

Network Management Notifications are administered by Operators and require their assistance to set up for use. This is a unique Notifier type that forwards alert status events for owned assets with alerting enabled. The type of the message determines the body of the message:

HTTP Method

POST

Field Descriptions

Field	Description	Values
type	The Type of message being sent.	BASE_STATION
subType	The format of the message body	ALERT
data	One or more messages of the subType format

Alert Type Field Descriptions

Alert type messages contain detailed information about the alert that was either raised or cleared.

Field	Description
count	The number of times the alert has been raised.
latestSystemInfo	The most recent information about why the alert was raised.
identifier	The identifier for the alert, this is usually the entity that is being alerted on i.e. Base Station EUI.
lastOccurrence	A timestamp in ISO format when the alert was last triggered.
status	The current status of the alert; Open, Cleared, and Closed.
severity	The severity of the alert; Low, Moderate, High, Urgent.
name	The name of the alert type, some Examples: No Connection, No SSH Connection, Device Count - Critical, etc. For the full list of alerts, see Base Station Alerts
notes	Optional notes provided by the system or Senet Operations.
firstOccurrence	A timestamp in ISO format when the alert was first triggered.

Example

{
   "type":"BASE_STATION",
   "subType":"ALERT",
   "data":[
      {
         "count":"3",
         "latestystemInfo":"Disconnected",
         "identifier":"00250C00010186DC",
         "lastOccurrence":"2019-05-09T19:01:56.765Z",
         "status":"cleared",
         "severity":"High",
         "name":"No Connection",
         "notes":"",
         "firstOccurrence":"2019-05-09T18:55:16.887Z"
      }
   ]
}