Skip to content

OTA Update APIs

Deploy software updates or container updates on your remote IoT devices via the OTA update REST API.

Note

OTA updates are deployed in the order in which they are submitted. For example, if a device was down for some reason when the OTA update job was submitted and later when it comes back up, OTA deployments waiting to be executed on the device will be executed one by one in the order in which they were submitted.

Before submitting a deployment or job, you need to define a workflow first. Use the workflow to submit a deployment/job on a specific device (DeviceId) or on a group of devices (DeviceGroup) or on a tag (Device Tags).

The idea behind separating workflow and deployment is reusability and repeatability.

1. Define a Workflow

curl https://api.socketxp.com/v1/workflow \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -d '{“Name”: "print-date-workflow”, “Command": "date"}'
A workflow could be a simple linux command or a shell script or a python program that needs to be run.

Name: Summarizes the nature of the workflow to be executed.
Command: The command that needs to be run on the device.

Sample inputs for the Command field are: 

“ls -l | grep myfile”
“date”
“sh /home/john/script.sh”
“python /home/john/check_temperature.py”
"reboot"
"service sshd restart"
Wherever possible provide full path names for files.

Sample Response:

{"WorkflowId": "678edc16-96d1-4ea2-a99c-0474c2449381"}
Use the above WorkflowId to submit a job on a particular device or a group of devices.

2. Get a Workflow

Retrieve details about a workflow using the following API.

curl https://api.socketxp.com/v1/workflow/:workflow_id \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

Sample Response

{
    "WorkflowId": "678edc16-96d1-4ea2-a99c-0474c2449381",
    "Name": "print-date-workflow",
    "Command": "date",
    "CreatedTime": "2002-01-19 10:05:22"
}

Retrieve all workflows of a user using the following API.

curl https://api.socketxp.com/v1/workflow \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

3. Delete a Workflow

To delete a workflow, use the following API.

curl https://api.socketxp.com/v1/workflow/:workflow_id \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

Sample Response

200 OK

Deployment

1. Submit a Deployment

Submit a deployment/job on a device using the DeviceId option.

curl https://api.socketxp.com/v1/job \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -d '{“Name”: “test-job-123”, “DeviceId”: "sensor-dev12345”, "WorkflowId": "678edc16-96d1-4ea2-a99c-0474c2449381" }'
Submit a deployment/job on a group of devices using the DeviceGroup option. 
curl https://api.socketxp.com/v1/job \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -d '{“Name”: “test-job-123”, “DeviceGroup”: "temp-sensor”, "WorkflowId": "678edc16-96d1-4ea2-a99c-0474c2449381" }'

Submit a deployment/job on a group of devices with a given tag using the TagId option.

curl https://api.socketxp.com/v1/job \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -d '{“Name”: “test-job-123”, “TagId”: "temp-sensor”, "WorkflowId": "678edc16-96d1-4ea2-a99c-0474c2449381" }'

Description:

Submit a deployment/job for execution.

Sample Response:

{"JobId": "4cad67dd-ab67-42ee-a293-4db493cab9ea"}
Use the above JobId to query the status and result of the job.

2. Get a Deployment with Result Summary

curl https://api.socketxp.com/v1/job/:job_id \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

Description:

Get the results summary of a submitted job using its JobId. It gives only the overall result of the deployment.

Sample Usage

curl https://api.socketxp.com/v1/job/4cad67dd-ab67-42ee-a293-4db493cab9ea \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

Sample Response:

{
    “JobId”: “4cad67dd-ab67-42ee-a293-4db493cab9ea”,
    “JobName”: “test-job-123”,
    “DeviceId”: “sensor-dev12345”,
    “Command”: “date”,
    “StartTime”: “Feb 8, 2002, 15:04:13 PST”,
    “EndTime”: “Feb 8, 2002, 15:04:14 PST”,
    “Result”: “Fri Feb 8 15:04:14 UTC 2002”
}

2.1 Get a Deployment With Detailed Results

curl https://api.socketxp.com/v1/job/:job_id/childjobs \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

Description:

When a deployment (parent job) is submitted for a device group or a tag, we internally create one child job for each of the device in the device group or tag name. This is required to track the execution and result (to store the stdout and stderr logs) of the deployment for each device separately.

This API will fetch the results of all the child jobs for a given parent job ID or deployment ID as a list.

Sample Usage

curl https://api.socketxp.com/v1/job/4cad67dd-ab67-42ee-a293-4db493cab9ea/childjobs \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

3. Get All Deployments with Results Summary

curl https://api.socketxp.com/v1/job \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

Description:

Get the results summary of all submitted deployments or jobs of a user.

Sample Usage

curl https://api.socketxp.com/v1/job \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

Sample Response

200 OK

[{
    “JobId”: “4cad67dd-ab67-42ee-a293-4db493cab9ea”,
    “JobName”: “test-job-123”,
    “DeviceId”: “sensor-dev12345”,
    “Command”: “date”,
    “StartTime”: “Feb 8, 2002, 15:04:13 PST”,
    “EndTime”: “Feb 8, 2002, 15:04:14 PST”,
    “Result”: “Fri Feb 8 15:04:14 UTC 2002”
}, 
{
    “JobId”: “5cad67eb-dk67-42ee-a293-4db493cab7wk”,
    “JobName”: “test-job-123”,
    “DeviceId”: “sensor-dev12345”,
    “Command”: “whoami”,
    “StartTime”: “Feb 8, 2002, 15:07:13 PST”,
    “EndTime”: “Feb 8, 2002, 15:07:14 PST”,
    “Result”: “john”
}]

4. Delete a deployment

curl https://api.socketxp.com/v1/job/:job_id \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

Description:

Delete a job. It is a good practise to delete all your executed jobs and keep your job queue short.

Sample Usage:

curl https://api.socketxp.com/v1/job/4cad67dd-ab67-42ee-a293-4db493cab9ea \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-auth-token-goes-here>"

Sample Response:

200 OK