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 jobs/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/job, you need to upload an artifact first. Use the artifact to submit a deployment/job on a specific device (DeviceId) or a group of devices (DeviceGroup) or a tag (Device Tags).

The idea behind separating the task of uploading artifacts and creating deployments is reusability and repeatability.

1. Upload an Artifact

Upload an artifact into the SocketXP Artifact Registry using the following API.

Note:

Each artifact must be less than 10MB in size to upload. Also, the artifact registry has a maximum storage limit set for each user based on the subscription plan. Delete any existing artifacts to create space in the registry to upload a new artifact.

Upload a tar.gz artifact using the following API.

curl https://api.socketxp.com/v1/artifact \
  -X POST \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -F "file=@/path/to/your/file" \
  -F "size=FILE_SIZE" \
  -F "version=FILE_VERSION" \
  -F "type=tar.gz" 

Upload a script artifact using the following API:

curl https://api.socketxp.com/v1/artifact \
  -X POST \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -F "file=@/path/to/your/file" \
  -F "size=FILE_SIZE" \
  -F "version=FILE_VERSION" \
  -F "destination=<folder-where-the-file-will-be-downloaded>" \
  -F "command=<command-to-execute-the-file>" \  
  -F "type=script" 

Sample Usage:

For a tar.gz artifact:

curl https://api.socketxp.com/v1/artifact \
  -X POST \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -F "file=@/home/user/app/ota_update_1.2.0.tar.gz" \
  -F "size=211" \
  -F "version=1.2.0" \
  -F "type=tar.gz" 

For a script artifact:

curl https://api.socketxp.com/v1/artifact \
  -X POST \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer <your-auth-token-goes-here>" \
  -F "file=@/home/user/myapp/update.sh" \
  -F "size=2294" \
  -F "version=1.0.0" \
  -F "destination=/usr/bin" \
  -F "command=/bin/bash update.sh" \  
  -F "type=script" 

Sample Response:

{"ArtifactId": "abc-1234-abcdef-5678-a1b2c3d4-abc"}

Use the ArtifactId to submit a job/deployment on a particular device or a group of devices.

2. Get an Artifact

Retrieve details about an artifact using the following API.

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

Sample Response

For a tar.gz artifact:

    {
        "ArtifactId": "abc-1234-abcdef-5678-a1b2c3d4-abc",
        "Name": "ota_update_1.2.0.tar.gz",
        "Version": "1.2.0",
        "Size": 211,
        "IsScript": false,
        "Command": "cd /tmp;curl -sO https://portal.socketxp.com/artifact/abc-1234-abcdef-5678-a1b2c3d4-abc/token/ota_update_1.2.0.tar.gz;chmod a+x ota_update_1.2.0.tar.gz;tar -xzf ota_update_1.2.0.tar.gz;cd ota_update_1.2.0;sh update.sh;cd ..;rm -f ota_update_1.2.0.tar.gz;rm -rf ota_update_1.2.0",
        "CreatedTime": "2025-02-20T17:34:22.476174+05:30"
    },

For a script artifact:

    {
        "ArtifactId": "abc-1234-abcdef-5678-a1b2c3d4-abc",
        "Name": "update.sh",
        "Version": "1.0.0",
        "Size": 2294,
        "IsScript": true,
        "Command": "cd /tmp;curl -sO https://portal.socketxp.com/artifact/abc-1234-abcdef-5678-a1b2c3d4-abc/token/update.sh;chmod a+x update.sh;/bin/bash update.sh",
        "CreatedTime": "2025-02-20T17:34:22.476174+05:30"
    },

Retrieve all artifacts in the registry for the user using the following API.

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

3. Delete an Artifact

Delete your old unused artifacts periodically to free up space in the registry to upload new artifacts.

To delete an artifact, use the following API.

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

Sample Response

200 OK

Legacy Method

Note:

The legacy method uses workflows to create OTA update deployments. We recommend all our users to use the artifact method mentioned above. We support workflow method for backward compatibility for legacy users.

In the legacy method, 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 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

Create a deployment using the "ArtifactId".

For the legacy method, create a deployment using the "WorkflowId"

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”, "ArtifactId": "abc-1234-abcdef-5678-a1b2c3d4-abc" }'

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”, "ArtifactId": "abc-1234-abcdef-5678-a1b2c3d4-abc" }'

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”, "ArtifactId": "abc-1234-abcdef-5678-a1b2c3d4-abc" }'

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