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 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.255",
    "Internal_ip": "192.168.0.101",
    "Notes": "Your Note",
    "Group": "Group01",
    "Name": "Raspberry pi 001"
}]

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.
Group string This is the device group.
Name string This is the device name.

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"
  }'

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.

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",
    "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.
Host string This is the remote host in the server.
Port string This is the remote port in the server.

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.

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.
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.

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"

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.

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.