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.senetco.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.senetco.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.senetco.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 Default Value 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.senetco.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.

Resource URL

https://api.senetco.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.senetco.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.senetco.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.senetco.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.senetco.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"
      }
   ]
}