Agent API

This REST API enables connecting embedded RTOS, windows CE or any other edge-device to Upswift platform.
​
post
Register Device
https://api.upswift.io/v1/agent/register_device
This is the first call you would have to implement on your edge-device. This call will register your device to Upswift platform.
Request
Response
Request
Form Data Parameters
user_token
required
string
This is your account token. You can find it under the Settings category on the dashboard.
device_identifier
required
array
This is the identifier of your device. This parameter is a list of Strings. Each string represents an identifier for that device. You can use multiple identifiers for your devices. Usually, it is the MAC addresses of your device. Example: {"device_identifier": ["aa:bb:cc:dd:ee:11", "aa:bb:cc:dd:ee:22"]}
project_name
required
string
This is the name of the project you would like to register this device to.
device_os
optional
string
This is a string that represents your device operating system. The default value is Agent API.
upswift_version
optional
string
This is a string that represents the Upswift Agent. Since it is your own customization, the value of this MUST begin with: AgentAPI- . The default value is: AgentAPI-v1.
device_name
optional
string
This is the name of your device that will be displayed on the dashboard.
device_group
optional
string
This is the group that you would like to register your device to. This group MUST exist at the dashboard under your project. The default value is Production.
software_version
optional
string
This is the software version that is running on your device. This value will be displayed on the dashboard.
Response
200: OK
 Successfully registered the device. The value of the "message" parameter is a JSON object with the keys:
1. device_token - String - This is your device token. Save that value for all future calls.
{"message": {"device_token": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"}}
400: Bad Request
Error occurred.
{"error_message": "<ERROR_MESSAGE>"}
429: Too Many Requests
Rate limit reached.
{}
If you receive status code 350, it means the device has been deleted from the dashboard. You must STOP sending Device Registration and Device Status calls.
Example
Python
Python
import json
import requests
​
json_content = {'user_token': 'XXXXXXXXXXXXXXX',
                'device_identifier': ['aa:bb:cc:dd:ee:11', 'aa:bb:cc:dd:ee:22'],
                'project_name': 'TestProject',
                'device_os': 'Windows CE',
                'upswift_version': 'AgentAPI-v1',
                'device_name': 'MyDevice1',
                'device_group': 'Test',
                'software_version': '1.0'}
​
call_request = requests.post("https://api.upswift.io/v1/agent/register_device", json=json_content)
call_response = json.loads(call_request.text)
​
if call_request.status_code != 200:
    if call_request.status_code == 429:
        error = "API limit reached"
    elif call_request.status_code == 350:
        ### DEVICE IS DELETED
    else:
        error = call_response["message"]
        print(error)
else:
    device_token = call_response["message"]["device_token"]
​
​
get
Project Parameters
https://api.upswift.io/v1/agent/project_parameters
This is the second call you would have to implement on your edge-device. This call will provide you the timeout value which represents the timeout between Device Status calls.
Request
Response
Request
Form Data Parameters
device_token
required
string
This is your device token. You have received this value in the response payload of the Register Device call.
Response
200: OK
 Successfully registered the device. The value of the "message" parameter is a JSON object with the keys:
1. status_timeout - Integer - This is the timeout time between Device Status calls. (the value is in seconds).
{"message": {"status_timeout": 20}}
400: Bad Request
Error occurred.
{"error_message": "<ERROR_MESSAGE>"}
429: Too Many Requests
Rate limit reached.
{}
Example
Python
Python
import json
import requests
​
json_content = {'device_token': 'XXXXXXXXXXXXXXX'}
​
call_request = requests.get("https://api.upswift.io/v1/agent/project_parameters", json=json_content)
call_response = json.loads(call_request.text)
​
if call_request.status_code != 200:
    if call_request.status_code == 429:
        error = "API limit reached"
    else:
        error = call_response["message"]
    print(error)
else:
    status_timeout = call_response["message"]["status_timeout"]
​
​
post
Device Status
https://api.upswift.io/v1/agent/device_status
This is the third call you would have to implement on your edge-device. This call should be sent every X seconds (depends on the status_timeout value you have received at the Project Parameters API call). This call represents a keep-alive message to Upswift servers, this way the server knows your device is online.
Request
Response
Request
Form Data Parameters
device_token
required
string
This is your device token. You have received this value in the response payload of the Register Device call
ram
optional
integer
This is your current device RAM usage (percentage). For example: a value of 30, will represent 30% RAM usage.
cpu
optional
integer
This is your current device CPU usage (percentage). For example: a value of 88, will represent 88% CPU usage.
disk_usage_total
optional
integer
This is your total space of disk (MB). For example: a value of 400, will represent a total disk of 400MB.
disk_usage_current
optional
integer
This is your current usage of disk (MB). For example: a value of 182, will represent a current disk usage of 182MB.
process_monitor
optional
array
This is a dictionary object representing the processes you monitor. The dict syntax should be as follows: {"<process_name>": true, 
"<another_process_name>": false} 
Value of true represent a process that is currently running. false represents a process that is not running. Please make sure to create those processes in the Monitor Processes category before including this parameter.
Response
200: OK
 Successfully sent a keep-alive message.
{"message": {"device_token": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"}}
400: Bad Request
Error occurred.
{"error_message": "<ERROR_MESSAGE>"}
429: Too Many Requests
Rate limit reached.
{}
If you receive status code 301, it means that the Project Parameters have been changed. You have to call the Project Parameters call as soon as possible.
Example
Python
Python
import json
import requests
​
json_content = {'device_token': 'XXXXXXXXXXXXXXX',
                'ram': 33,
                'cpu': 12,
                'disk_usage_total': 1200,
                'disk_usage_current': 180,
                'process_monitor': {"mysql": true,
                                    "my_app": false}}
​
call_request = requests.post("https://api.upswift.io/v1/agent/device_status", json=json_content)
call_response = json.loads(call_request.text)
​
if call_request.status_code != 200:
    if call_request.status_code == 429:
        error = "API limit reached"
    elif call_request.status_code == 301:
        ### NEW PROJECT PARAMETERS
    else:
        error = call_response["message"]
        print(error)
​
Upswift Architecture - Previous
Security
Next - Troubleshooting
Device registration
Last updated 8 months ago
Agent API

postRegister Device

getProject Parameters

postDevice Status

post
Register Device

get
Project Parameters

post
Device Status
