General API

Last updated: March 12th, 2020

General

Please note - Upswift REST Api is open for all Upswift accounts. Although, some calls are available only for paying account.

Each device can send up to 3 API calls in a minute. If you reach the limit, you will receive an appropriate response code. Please check the response codes and send no more calls than the limit, otherwise your device may get banned for API calls.

All calls require user_token and some of them require device_token. The user_token you can find under Account category at the dashboard. The device_token you can find on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.

The API is working with Upswift Agent version 5.0 and above.

Devices

Log files

Send log files from your devices to the dashboard. You can then view the log files content at the dashboard or download the files. You can send text, as well as binary files. Keep in mind that at the dashboard you can view only the text files. All other files you won't be able to view at the dashboard and only download them.

Restrictions:
  • Max file size: 20Mb
  • Max calls per minute per device: 1
  • Max total files that are being saved on Upswift servers: 30. If you upload a file with a name that already exist, it will be overrided. If you upload more than 30 files in total, the oldest file uploaded will be deleted and replaced by the new file.
URL: https://api.upswift.io/v1/send_log_file
Request Type: POST
Payload Type: JSON

Request

  • json - Required - JSON
    • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
    • device_token - Required - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.
    • file - Required - File obj - application/octet-stream - This is the file that you would like to send.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
json_content = {'device_token': 'XXXXXXXXXXXXXXXXX',
                'user_token': 'YYYYYYYYYYYYYYY'}
file_name = "log.txt"
file_path = "/home/logs/log.txt"

json_payload = (None, json.dumps(json_content), 'application/json')
file_payload = (file_name, open(file_path, 'rb'), 'application/octet-stream')
final_payload = {'json': json_payload,'file': file_payload}

call_request = requests.post("https://api.upswift.io/v1/send_log_file", files=final_payload)
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["error_message"]
    print(error)
else:
    response_message = call_response["message"]

                                        

Update Trigger

When deploying Micro-update on devices, there are situations when your device state is not compatible for receiving new updates. If, for instance, your device is currently in use by the end-user, you would rather not deploy the new update at that time.
Using the Update Trigger call, you can manage from within your application when you would like to receive updates, and when not to.
After setting the update trigger, your device will not receive new updates until you unset the trigger.

URL: https://api.upswift.io/v1/set_update_trigger
Request Type: POST
Payload Type: JSON

Request

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_token - Required - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.
  • trigger_set - Required - Boolean - Set to true to NOT receive new updates. Set to false to receive new updates.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
json_content = {'device_token': 'XXXXXXXXXXXXXXXXX',
                'user_token': 'YYYYYYYYYYYYYYY',
                'trigger_set': True}

call_request = requests.post("https://api.upswift.io/v1/set_update_trigger", 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["error_message"]
    print(error)
else:
    response_message = call_response["message"]

                                        

Get device state

Using this call you will get the current device state - Online or Offline.

URL: https://api.upswift.io/v1/get_device_state
Request Type: GET
Payload Type: JSON

Request

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_id - Required - Integer - This is the device ID which you can find at the Devices category in the dashboard.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
    • The value of the message parameter is a JSON with the keys:
    • device_status - The value is String. It can be online or offline.
    • device_id - The value is Integer. This is the ID of the device which you have sent at the request.
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
json_content = {'device_id': 12345678,
                'user_token': 'YYYYYYYYYYYYYYY'}

call_request = requests.get("https://api.upswift.io/v1/get_device_state", 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["error_message"]
    print(error)

else:
    device_status = call_response["message"]["device_status"]
    device_id = call_response["message"]["device_id"]

                                        

Get multiple devices state

Using this call you will get the current device state of multiple devices - Online or Offline.

URL: https://api.upswift.io/v1/get_devices_state
Request Type: GET
Payload Type: JSON

Request

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • project_name - Optional - String - This is the project name of the project you would like get all its devices state.
  • group_name - Optional - String - This is the group name of the group you would like get all its devices state.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
    • The value of the message parameter is a list of JSONs. Each JSON represents a device. The JSON keys are:
    • device_status - The value is String. It can be online or offline.
    • device_id - The value is Integer. This is the ID of the device.
    • device_name - The value is String. This is the name of the device.
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
json_content = {'project_name': 'MYPROJECT',
                'group_name': 'Production'
                'user_token': 'YYYYYYYYYYYYYYY'}

call_request = requests.get("https://api.upswift.io/v1/get_devices_state", 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["error_message"]
    print(error)
else:
    for device in call_response["message"]:
        device_status = device["device_status"]
        device_id = device["device_id"]
        device_name = device["device_name"]

                                        

Get devices details

Using this call you will get all details of your devices. You can choose to get details of all devices or all devices in a specific project/group or get the details of just a single device.

URL: https://api.upswift.io/v1/devices_details
Request Type: GET
Payload Type: JSON

Request

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • project_name - Optional - String - This is the project name of the project you would like get all its devices details.
  • group_name - Optional - String - This is the group name of the group you would like get all its devices details. Using group_name parameter will work only if project_name is set
  • device_token - Optional - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json. If you set the device_token, other parameters will be ignored.
If no parameters are set, all devices of that user will be returned.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
    • The value of the message parameter is a list of JSONs. Each JSON represents a device. The JSON keys are:
    • device_id - The value is Integer. The ID of the device.
    • device_name - The value is String. The name of the device.
    • software_version - The value is String. Current software version.
    • upswift_version - The value is String. Upswift Agent version.
    • project - The value is String. The name of the project this device is registered to.
    • group - The value is String. The name of the group this device is registered to.
    • device_ip - The value is String. The IP of the device.
    • last_keepalive - The value is String(DATETIME). The last time a keep-alive message received from that device.
    • cpu_usage - The value is Integer. The current CPU usage of the device (Percentage - value can be 0-100).
    • ram_usage - The value is Integer. The current RAM usage of the device (Percentage - value can be 0-100).
    • disk_usage - The value is Float. The current Disk usage of the device (MegaBytes).
    • address - The value is String. The current address set for this device.
    • lat - The value is Float. The current Latitude parameter set for this device.
    • lng - The value is Float. The current Longitude parameter set for this device.
    • is_update_trigger_set - The value is Boolean. If the parameter update trigger is currently set. valid values true/false
    • description - The value is String. The description of that device.
    • updates - The value is List of JSONs. The last 3 updates of that device with information regarding those updates. Each JSON includes the next parameters:
      • update_id - The ID of the update.
      • update_status - The status of the update. Possible values are: pending - The update is pending and will be deployed at the scheduled time. in_progress - The update is in progress state, meaning it is currently being deployed. success - The update successfully finished the deployment. failed - The deployment failed.
      • update_version - The version of the update.
      • comment - The comment set to the update when it was created.
      • deployment_schedule_time - The time the deployment was scheduled to. By default this is the update creation time. Please note the value is UTC time with the next format: Year-Month-Day Hour:Minute:Second
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
json_content = {'project_name': 'MYPROJECT',
                'group_name': 'Production'
                'user_token': 'YYYYYYYYYYYYYYY'}

call_request = requests.get("https://api.upswift.io/v1/devices_details", 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["error_message"]
    print(error)
else:
    for device in call_response["message"]:
        device_name = device["device_name"]
        device_id = device["device_id"]
        software_version = device["software_version"]
        upswift_version = device["upswift_version"]
        project = device["project"]
        group = device["group"]
        device_ip = device["device_ip"]
        last_keepalive = device["last_keepalive"]
        cpu_usage = device["cpu_usage"]
        ram_usage = device["ram_usage"]
        address = device["address"]
        lat = device["lat"]
        lng = device["lng"]
        is_update_trigger_set = device["is_update_trigger_set"]
        description = device["description"]
        updates = device["updates"]



                                        

Change devices details

Using this call you can change details of your devices.

URL: https://api.upswift.io/v1/devices_details
Request Type: POST
Payload Type: JSON

Request

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_token - Required - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.
  • device_name - Optional - String - A new name for that device.
  • group - Optional - String - The name of the group you want to switch for that device (the group must exist at the dashboard).
  • software_version - Optional - String - A new software version.
  • address - Optional - String - Available only for Premium/Special plans - A new address for that device. Please note, the address will be validated using Google Maps.
  • lat - Optional - String - Available only for Premium/Special plans - A new Latitude for the device. (must be called with the lng parameter)
  • lng - Optional - String - Available only for Premium/Special plans - A new Longitude for the device. (must be called with the lat parameter)
  • description - Optional - String - The description of the device. Can be anything you want.
You can set whichever parameters you would like to change on each request.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
json_content = {'user_token': 'YYYYYYYYYYYYYYY',
                'device_token': 'XXXXXXXXXXXXXX',
                'device_name': 'new_device_name',
                'group': 'Production',
                'software_version': 'version1.1',
                'description': 'Some kind of description for that device'}

call_request = requests.post("https://api.upswift.io/v1/devices_details", 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["error_message"]
    print(error)



                                        

Application Logs Alerts

Send Application Log Alert

Depending on your application error handling, there may be situations when you would like to get notified if an error occurred in your application on your edge device. The Application Log tool let you send alerts which you will be able to view under the Application Logs category.

URL: https://api.upswift.io/v1/send_app_alert
Request Type: POST
Payload Type: JSON

Request

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_token - Required - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.
  • application_alert_message - Required - String - This is the message you want to send.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
    • The value of the message parameter is a JSON with the key: application_alert_id. The value is Integer. Save that ID, as when you would like to finish the alert from your application, you will have to send another POST request with that ID (see below).
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
json_content = {'device_token': 'XXXXXXXXXXXXXXXXX',
                'user_token': 'YYYYYYYYYYYYYYY',
                'application_alert_message': "Unable to connect to Bluetooth device"}

call_request = requests.post("https://api.upswift.io/v1/send_app_alert", 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["error_message"]
    print(error)
else:
    alert_id = call_response["message"]["application_alert_id"]

                                        

Finish Application Alert

Call this api to finish an Application Alert from within your application.

URL: https://api.upswift.io/v1/finish_app_alert
Request Type: POST
Payload Type: JSON

Request

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_token - Required - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.
  • application_alert_id - Required - Integer - This is the ID of the alert you have received in the response of the Send Application Alert call.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
alert_id = "Received the ID from the 'Send Application Alert' call"
json_content = {'device_token': 'XXXXXXXXXXXXXXXXX',
                'user_token': 'YYYYYYYYYYYYYYY',
                'application_alert_id': alert_id}

call_request = requests.post("https://api.upswift.io/v1/finish_app_alert", 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["error_message"]
    print(error)
else:
    response_message = call_response["message"]

                                        

Data Monitor

Send Data Monitor Records

Using this call, you can send Data Monitor metrics to the dashboard from your devices.

URL: https://api.upswift.io/v1/send_app_monitor
Request Type: POST
Payload Type: JSON

Request

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_token - Required - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.
  • app_parameters - Required - List - A list of JSONs that represents all the parameters you want to send and their new values. The parameter names must exist at the Data Monitor category in the dashboard. The value's type you send can be either String, Integer, Float or Boolean.
    • [{"app_parameter_name": "APP_PARAMETER_NAME", "app_parameter_value": "APP_PARAMETER_VALUE"}]

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
json_content = {'device_token': 'XXXXXXXXXXXXXXXXX',
                'user_token': 'YYYYYYYYYYYYYYY',
                'app_parameters': [{'app_parameter_name': "Temperature", 'app_parameter_value': "23c"},
                                   {'app_parameter_name': "Counter", 'app_parameter_value': "123"}]}

call_request = requests.post("https://api.upswift.io/v1/send_app_monitor", 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["error_message"]
    print(error)
else:
    response_message = call_response["message"]

                                        

Get Data Monitor Records

Using this call, you can get the last 100 Data Monitor records that were received from your devices.

URL: https://api.upswift.io/v1/app_monitor_details
Request Type: GET
Payload Type: JSON

Request

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_token - Optional - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.
  • project_name - Optional - String - This is the project name of the project you would like get all its device's Data Monitor records.
If you set device_token, you will receive the records for that device regardless if you set also the project_name. If only project_name is set, you will receive records from all devices of that project. If both of them are not set, you will receive records from all devices from all projects.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
    • The value of the message parameter is a list of JSONs with the keys:
    • device_id - The value is Integer. This is the ID of the device which the record belongs to.
    • app_parameter_name - The value is String. This is the Parameter name which this record belongs to.
    • app_parameter_value - The value is String. This is the record Value.
    • created_time - The value is String. This is the time the record was sent from your device.
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Example

Python

import json
import requests
json_content = {'device_token': 'XXXXXXXXXXXXXXXXX',
                'user_token': 'YYYYYYYYYYYYYYY',
                'project_name': "TestProject"}

call_request = requests.get("https://api.upswift.io/v1/app_monitor_details", 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["error_message"]
    print(error)
else:
    for record in call_response["message"]:
        device_id = record["device_id"]
        parameter_name = record["app_parameter_name"]
        record_value = record["app_parameter_value"]
        created_time = record["created_time"]