RemoteIoT

Article

Table of Contents

Introduction

The RemoteIoT API allows even more automation and integration of RemoteIoT service into your system. Use these web services to access your device from anywhere.

If you cannot find a method to achieve your objective or are struggling to use the API, please contact our support team with any questions you may have.

The API access is only available to the Business or Enterprise account.

Authorization

All requests through the API need to be authorized. Once the token is generated, it needs to be added as a header with the prefix Bearer.

The full http header looks like:

Authorization: Bearer json_web_token

Please go to the API access page to find your json_web_token.

Example request:

curl "api_endpoint_here"
  -H "Authorization: Bearer json_web_token"

Make sure to replace json_web_token with your token.


Devices

Devices services are an important feature of RemoteIoT. They allow for much more flexibility to access your device.

Retrieve Devices

Retrieve a list of your devices which have been registered. On success the API will respond with a list of your devices in JSONArray format.

The "Group" parameter filters these devices by device group. To retrieve all devices, leave it blank.

Example request:

curl https://remoteiot.com/portal/api/device \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "Group":"Group01"
  }'

JSON Body Parameters




Parameter
Data Type
Description





Group
String
The group of the device.

Example of server response:

[{
	"UnitId": "0000000088888888",
	"External_ip": "10.10.10.XXX",
	"Internal_ip": "192.168.0.101",
	"Mac": "88:88:88:88:88:88",
	"Notes": "Device Description",
	"Group": "Group01",
	"Name": "Raspberry pi 001",
	"Serial": "0000000012345678"
}]

JSON Response

The Response is a JSONArray object.




Parameter
Data Type
Description





UnitId
String
This is the device id.




External_ip
String
The address assigned to you by your Internet Service Provider that is how the Internet and all other computers outside your local network see you.




Internal_ip
String
The address that is assigned by your local network router. These IP addresses can only be seen by other computers in your local network and not by any computers connected in an external network such as on the Internet.




Mac
String
This is the MAC address of the device.




Group
String
This is the device group.




Name
String
This is the device name.




Serial
String
This is the serial number.

Rename Device

HTTP Request

Example request:

curl https://remoteiot.com/portal/api/rename \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "UnitId":"0000000088888888",
    "Name":"Test3",
    "Description":"Device Description"
  }'

JSON Body Parameters




Parameter
Data Type
Description





UnitId
String
This is the device id.




Name
String
This is the new name.




  Description
  String
  This is the device description.

JSON Response

On success the API will respond HTTP Status Code 200.

Retrieve Status

Retrieve the status of the device. The status is online or offline.

Example request:

curl https://remoteiot.com/portal/api/status \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '[{"UnitId":"0000000088888880"},{"UnitId":"0000000088888881"}]'

JSON Response

A list of unit id in JSONArray format

[{
    "UnitId": "0000000088888888",
    "LastOnlineTime": "20200101 00:00:00",      
    "Status": "Online"},
    {
    "UnitId": "0000000088888881",
    "LastOnlineTime": "20200101 00:00:00",       
    "Status": "Offline"
}]




Parameter
Data Type
Description





UnitId
String
This is the device id.




Status
String
This is the status of the device. This is Online or Offline.




  LastOnlineTime
  String
  This is last online time of the device.

Connect Device

Setup a remote connect with your device. On success the API will respond the Host name and Port number. You may login your device with it.

Example request:

curl https://remoteiot.com/portal/api/connect \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
	"UnitId":"0000000088888888",
	"LocalPort":"22",
	"Permanent":"true",
	"LocalHost":"",
	"LimitingAccessIP":"x.x.x.x"
  }'

JSON Body Parameters




Parameter
Data Type
Description





UnitId
String
This is the device id.




LocalPort
String
This is the local port in your device. For example, 22 for ssh login.




Permanent
boolean
Permanent tunnel(For Enterprise user only).




LimitingAccessIP
String
Limiting Access By IP(For Enterprise user only)




Host
String
Global proxy(For Enterprise user only). Please specify the following host:

    
   
  • proxy8
    • 
   
  • proxy7
    • 
   
  • europe
    • 
   
  • uk
    • 
   
  • india
    • 
   
  • sg
    • 
   
  • sydney
    • 
   
  • brazil
    • 







LocalHost
String
Connect other computer on the local network (For Enterprise user only)

JSON Response

{
    "Host": "proxy7.remoteiot.com",
    "Port": 23401,
    }




Parameter
Data Type
Description





Host
String
This is the remote host name.




Port
integer
This is the remote port number.

Delete Device

Example request:

curl https://remoteiot.com/portal/api/DeleteDevice \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "UnitId":"0000000088888888"
  }'

JSON Body Parameters




Parameter
Data Type
Description





UnitId
String
This is the device id.

JSON Response

On success the API will respond HTTP Status Code 200.

Delete Connection

Example request:

curl https://remoteiot.com/portal/api/DeleteConnection \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "UnitId":"0000000088888888",
    "Port":"18000"
  }'

JSON Body Parameters




Parameter
Data Type
Description





UnitId
String
This is the device id.




Port
String
This is the remote port number.

JSON Response

On success the API will respond HTTP Status Code 200.

List Connection

List currently active connection.

Example request:

curl https://remoteiot.com/portal/api/ListConnection \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"

JSON Response

The Response is a JSONArray object.

[{
    "Name": "Test1"
    "UnitId": "0000000088888888",
    "LocalPort": "22",
    "LocalHost": "",
    "Host": "proxy8.remoteiot.com",
    "Port": "10000"
}]




Parameter
Data Type
Description





Name
String
This is the name of the device.




UnitId
String
This is the device id.




LocalPort
String
This is the local port in the device.




LocalHost
String
This is the local address of the device.




Host
String
This is the remote host in the server.




Port
String
This is the remote port in the server.

Get Log file

Get these device log files (Only those new log contents updated since the last api call are returned).

Example request:

curl https://remoteiot.com/portal/api/log \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "UnitId":"0000000088888888",
	"File":"System error"
  }'

JSON Body Parameters




Parameter
Data Type
Description





UnitId
String
This is the device id.




File
String
This is the file name.

JSON Response

The Response is a JSONArray object.

[{
    "Log": "[Wed Nov  3 03:31:43 2021] piix4_smbus "
}]




Parameter
Data Type
Description





Log
String
This is the content of the log file.

Change Group

Change Device Group.

Example request:

curl https://remoteiot.com/portal/api/ChangeGroup \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "UnitId":"0000000088888888",
    "Group":"Group Name"
  }'

JSON Body Parameters




Parameter
Data Type
Description





UnitId
String
This is the device id.




Group
String
This is the group name.

JSON Response

On success the API will respond HTTP Status Code 200.

Create Group

Create a new group.

Example request:

curl https://remoteiot.com/portal/api/AddGroup \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "Group":"Group Name"
  }'

JSON Body Parameters




Parameter
Data Type
Description





Group
String
This is the group name.

JSON Response

On success the API will respond HTTP Status Code 200.

Get Custom Field

Returns the values of these custom fields.

Example request:

curl https://remoteiot.com/portal/api/CustomField \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"
  -d '{
    "CustomField":"Custom001",
    "Unit":[{"UnitId":"0000000088888881"},{"UnitId":"0000000088888882"}]
  }'

JSON Body Parameters




Parameter
Data Type
Description







  CustomField
  String 
  The name of the custom field.




Unit
JSONArray
IDs of these devices (Up to 1000 IDs)

Response

The Response is a JSONArray object.


[{"UnitId":"0000000088888881","Custom":"custom value1"},{"UnitId":"0000000088888882","Custom":"custom value2"}]




Parameter
Data Type
Description





UnitId
String
IDs of these devices.




Custom
String
The value of the custom field.

Update Custom Field

Update the value of a custom field.

Example request:

curl https://remoteiot.com/portal/api/UpdateCustomField \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"
  -d '{
    "CustomField":"Custom001",
    "UnitId":"0000000088888881", 
    "Value":"custom value1"
  }'

JSON Body Parameters




Parameter
Data Type
Description







  CustomField
  String 
  The name of the custom field.




  UnitId
  String 
  The ID of these devices.




  Value
  String
  The value of the custom field.

Response

On success the API will respond HTTP Status Code 200.

Submit Network Test Job

Submit a network test job.

Example request:

curl https://remoteiot.com/portal/api/SubmitSpeedTest \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "UnitId":"0000000088888888"
  }'

JSON Body Parameters




Parameter
Data Type
Description







UnitId
String
This is the device id.

JSON Response

On success the API will respond HTTP Status Code 200.

Get Network Test Result

Get network test results.

Example request:

curl https://remoteiot.com/portal/api/GetSpeedTestResult \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "UnitId":"0000000088888888"
  }'

JSON Body Parameters




Parameter
Data Type
Description







UnitId
String
This is the device id.

JSON Response

The Response is a JSONObect object.

{
    "Submission Time": "2024-01-01 00:00:00.0",
    "Ip": "xxx.xxx.xxx.xxx",
    "ISP": "ISP Name",
    "Ping": "11.502 ms",
    "Upload": "947.23 Mbit/s",
    "Download": "1723.05 Mbit/s",
    "Ip Location": "NJ, United States",
    "Wireless Quality": "(Prefect)",
    "Network RX errors": "0",
    "Network TX errors": "0"
}




Parameter
Data Type
Description





Submission Time
String
This is the submission time (GMT) for the network test job.




Ip
String
This is the IP of the device.




ISP
String
This is the ISP name of the device's network.




Ping
String
It is expressed in milliseconds (ms) and represents the round-trip time for the packet.




Upload
String
This is the upload speed of the device network.




Download
String
This is the download speed of the device network.




Ip Location
String
This is the IP location of the device network.




Wireless Quality
String
This is the wireless quality of the device network. (Prefect / Good / Medium / Weak)




Network RX errors
String
This is a reception error on the device network.




Network TX errors
String
This is a sending error from the device network.

Batch Job

Submit Job

Execute a bash script or a shell command in your device.

Example request:

curl https://remoteiot.com/portal/api/submitjob \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "JobName":"Job1",
    "UnitId":"0000000088888888",
    "ExecuteTime":"2017-05-19 00:00:00",
    "Script":"test1.sh",
    "Command":"ls"
  }'

JSON Body Parameters




Parameter
Data Type
Description





JobName
String
This is the job name.




UnitId
String
This is the device id.




ExecuteTime
String
Execute the script in a specific time (GMT).




Script
String
Execute a script file which has been uploaded in portal.




Command
String
Execute a Linux command. If the 'Script' field is not null, the field is ignored.

JSON Response

On success the API will respond HTTP Status Code 200.

Update file

Update the content of a file in your device.

Example request:

curl https://remoteiot.com/portal/api/UpdateFile \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "JobName":"Job1",
    "UnitId":"0000000088888888",
    "ExecuteTime":"2017-05-19 00:00:00",
    "Filename":"/tmp/test.sh",
    "Content":"ls"
  }'

JSON Body Parameters




Parameter
Data Type
Description





JobName
String
This is the job name.




UnitId
String
This is the device id.




ExecuteTime
String
Update the file in a specific time.




Filename
String
This is the full path of file.




Content
String
This is the content of file.

JSON Response

On success the API will respond HTTP Status Code 200.

Upload file

Upload a file with multipart form-data API.

Example request:

curl https://remoteiot.com/portal/api/FileUpload \
  -X POST \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer json_web_token" \
  -F File=@/tmp/test.txt \
  -F 'Data={
	"Folder":"/tmp/",
	"IsAll":"false",
	"Group":"",
	"Unit":[{"UnitId":"0000000088888881"},{"UnitId":"0000000088888882"}],
	"ExecuteTime":"2023-01-12 08:01:37",
	"PreScript":"",
	"AfterScript":""}'

JSON Body Parameters




Parameter
Data Type
Description





File
form-data
This is the multipart form-data.




Data
Json
This is a request in json format.




Folder
String
Upload the file to a folder on the device.




IsAll
Boolean
Upload file to all devices. Default is false.




Group
String
Upload files to a device group. Default is null.




Unit
Json Array
Upload files to these specified devices. Default is null.




ExecuteTime
String
Update the file in a specific time. Default is now.




PreScript
String
Execute script before upload. Default is null.




AfterScript
String
Execute script after upload. Default is null.

JSON Response

On success the API will respond HTTP Status Code 200.

List Jobs

Return the status and the output of these batch jobs.

Example request:

curl https://remoteiot.com/portal/api/listjob \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"
  -d '{
    "UnitId":"0000000088888888"
  }'

JSON Body Parameters




Parameter
Data Type
Description




UnitId
String
This is the device ID. If the device ID is empty, all jobs are returned.

JSON Response

The Response is a JSONArray object.

[{
    "Name": "Test1"
    "UnitId": "0000000088888888",
    "Status": "Executed",
    "SubmitTim": "2017-01-10 10:02:30.0"
    "ExecuteTim": "2017-01-10 10:02:30.0"
    "Script": "test.sh",
    "Command": ""
    "Result": ""
}]




Parameter
Data Type
Description





Name
String
This is the name of the job.




UnitId
String
This is the device id.




Status
String
This is the status of the batch job. This is "Executed" or "Pending".




SubmitTim
String
This is submit time of the job.




ExecuteTim
String
This is execution time of the job.




Script
String
This is the script file name.




Result
String
This is the output of the job.

Delete Job

Delete these jobs of the device.

Example request:

curl https://remoteiot.com/portal/api/DeleteJob \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token" \
  -d '{
    "UnitId":"0000000088888888"
  }'

JSON Body Parameters




Parameter
Data Type
Description







UnitId
String
This is the device id.

JSON Response

On success the API will respond HTTP Status Code 200.

Cloud Chart

List Chart

Return the id and name of these cloud charts.

Example request:

curl https://remoteiot.com/portal/api/ListChart \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"

JSON Response

The Response is a JSONArray object.

[{
  "Name": "Chart1"
  "ChartId": "12345678901234567890123456789012"
}]




Parameter
Data Type
Description





Name
String
This is the name of the chart.




ChartId
String
This is the id of the chart.

Update ChartId

For security reasons, you can update the chart ID regularly.

Example request:

curl https://remoteiot.com/portal/api/UpdateChartId \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"

JSON Response

On success the API will respond HTTP Status Code 200.

Export Historical Data

Return the historical data of these cloud charts.

Example request:

curl https://remoteiot.com/portal/api/ChartHistory \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"
  -d '{
    "UnitId":"0000000088888888",
    "ChartId":"12345678901234567890123456789012",
    "Hour":24
  }'

JSON Body Parameters




Parameter
Data Type
Description







UnitId
String
This is the device id.




  ChartId
  String
  This is the chart id.




  Hour
  integer
  Hours of historical data.

Response

The response is a history file in csv format.

Timestamp,Value
2020-12-27 05:25:00,188660
2020-12-27 05:30:00,188572
2020-12-27 05:35:00,188668




Parameter
Data Type
Description





Timestamp
String
This is the timestamp of historical data.




Value
integer
This is value of historical data.

Export Multi Historical Data

Returns historical data of cloud chart for these multi devices.

Example request:

curl https://remoteiot.com/portal/api/ChartHistoryMulti \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"
  -d '{
    "Unit":[{"UnitId":"0000000088888881"},{"UnitId":"0000000088888882"}],
    "ChartId":"12345678901234567890123456789012",
    "Hour":24
  }'

JSON Body Parameters




Parameter
Data Type
Description







Unit
JSONArray
IDs of these devices




  ChartId
  String
  This is the chart id.




  Hour
  integer
  Hours of historical data.

Response

The response is a history file in csv format.

UnitId,Timestamp,Value
0000000088888881,2020-12-27 05:25:00,188660
0000000088888881,2020-12-27 05:30:00,188572
0000000088888882,2020-12-27 05:35:00,188668




Parameter
Data Type
Description





UnitId
String
IDs of these devices.




Timestamp
String
This is the timestamp of historical data.




Value
integer
This is value of historical data.

Export Device Uptime

Return the device uptime.

Example request:

curl https://remoteiot.com/portal/api/DeviceUptime \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"
  -d '{
    "Unit":[{"UnitId":"0000000088888881"},{"UnitId":"0000000088888882"}],
    "Hour":24
  }'

JSON Body Parameters




Parameter
Data Type
Description







Unit
JSONArray
IDs of these devices (Up to 1000 IDs)




  Hour
  integer
  Hours of uptime data.

Response

The response is a historical data file in csv format.

UnitId,Timestamp,Value
0000000088888881,2020-12-27 05:25:00,100
0000000088888881,2020-12-27 05:30:00,100
0000000088888882,2020-12-27 05:35:00,20




Parameter
Data Type
Description





UnitId
String
IDs of these devices.




Timestamp
String
This is the timestamp of uptime.




Value
integer
This is the percentage of uptime.

Export Network Uptime

Return the network uptime.

Example request:

curl https://remoteiot.com/portal/api/NetworkUptime \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"
  -d '{
    "Unit":[{"UnitId":"0000000088888881"},{"UnitId":"0000000088888882"}],
    "Hour":24
  }'

JSON Body Parameters




Parameter
Data Type
Description







Unit
JSONArray
IDs of these devices (Up to 1000 IDs)




  Hour
  integer
  Hours of uptime data.

Response

The response is a historical data file in csv format.

UnitId,Timestamp,Value
0000000088888881,2020-12-27 05:25:00,100
0000000088888881,2020-12-27 05:30:00,100
0000000088888882,2020-12-27 05:35:00,20




Parameter
Data Type
Description





UnitId
String
IDs of these devices.




Timestamp
String
This is the timestamp of uptime.




Value
integer
This is the percentage of uptime.

Export Network In Traffic

Return network input traffic.

Example request:

curl https://remoteiot.com/portal/api/NetworkIn \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"
  -d '{
    "Unit":[{"UnitId":"0000000088888881"},{"UnitId":"0000000088888882"}],
    "Hour":24
  }'

JSON Body Parameters




Parameter
Data Type
Description







Unit
JSONArray
IDs of these devices (Up to 1000 IDs)




  Hour
  integer
  Hours of uptime data.

Response

The response is a historical data file in csv format.

UnitId,Timestamp,Value
0000000088888881,2020-12-27 05:25:00,100
0000000088888881,2020-12-27 05:30:00,100
0000000088888882,2020-12-27 05:35:00,20




Parameter
Data Type
Description





UnitId
String
IDs of these devices.




Timestamp
String
This is the timestamp of uptime.




Value
integer
This is the network input traffic.

Export Network Out Traffic

Return network output traffic.

Example request:

curl https://remoteiot.com/portal/api/NetworkOut \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer json_web_token"
  -d '{
    "Unit":[{"UnitId":"0000000088888881"},{"UnitId":"0000000088888882"}],
    "Hour":24
  }'

JSON Body Parameters




Parameter
Data Type
Description







Unit
JSONArray
IDs of these devices (Up to 1000 IDs)




  Hour
  integer
  Hours of uptime data.

Response

The response is a historical data file in csv format.

UnitId,Timestamp,Value
0000000088888881,2020-12-27 05:25:00,100
0000000088888881,2020-12-27 05:30:00,100
0000000088888882,2020-12-27 05:35:00,20




Parameter
Data Type
Description





UnitId
String
IDs of these devices.




Timestamp
String
This is the timestamp of uptime.




Value
integer
This is the network output traffic.

API Rate Limits

The following API rate limits apply to all APIs:

  • 2,000 records per requests
  • 100 requests per 10 minutes

Errors

This section can detail the different error responses.




Error Code
Meaning





400
Bad Request – Your request sucks.




401
Unauthorized – Your API key is wrong.




403
Forbidden – Too many requests from the same client IP. Please refer API Rate Limits.




404
Not Found – The specified request or data could not be found.




500
Internal Server Error – We had a problem with our server. Try again later.




503
Service Unavailable – We are temporarily offline for maintenance. Please try again later.