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.

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.

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; Dynamic IP Restriction limit reached.
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.