Sign in
Deployments

Create

Stage or deploy a new deployment.

post/deployments

Query parameters

expandDeploymentExpansion[]

Fields to expand on the deployment resource.

[
  "device"
]

Request body

target_status'staged' | 'deployed' required

Desired state of the deployment.

  • Staged: ready for deployment. Deployments can only be staged if their release is not the current release for the device.
  • Deployed: deployed to the device. Deployments can only be deployed if their release is the device's current release.
descriptionstring required

The description of the deployment.

release_idstring required

The release ID which this deployment adheres to.

parent_idstring

The ID of the deployment that this deployment was patched from.

device_idstring required

The ID of the device that the deployment is being created for.

config_instance_idsstring[] required

The IDs of the config instances to deploy. A deployment must have exactly one config instance for each config schema in the deployment's release.

Example request

{
  "description": "Deployment for the motion control config instance",
  "release_id": "rls_123",
  "parent_id": "dpl_123",
  "device_id": "dvc_123",
  "config_instance_ids": [
    "cfg_inst_123"
  ]
}

Response

Successfully created the deployment.

object'deployment' required

The object type, which is always deployment.

idstring required

ID of the deployment.

descriptionstring required

The description of the deployment.

status'drifted' | 'staged' | 'queued' | 'deployed' | 'archived' | 'failed' | 'retrying' required

This status merges the 'activity_status' and 'error_status' fields, with error states taking precedence over activity states when errors are present. For example, if the activity status is 'deployed' but the error status is 'failed', the status is 'failed'. However, if the error status is 'none' and the activity status is 'deployed', the status is 'deployed'.

activity_status'drifted' | 'staged' | 'queued' | 'deployed' | 'archived' required

Last known activity state of the deployment.

  • Drifted: device's configurations have drifted since this deployment was staged, and the deployment needs to be reviewed before it can be deployed
  • Staged: is ready to be deployed
  • Queued: the deployment's config instances are waiting to be received by the device; will be deployed as soon as the device is online
  • Deployed: the deployment's config instances are currently available for consumption on the device
  • Archived: the deployment is available for historical reference but cannot be deployed and is not active on the device
error_status'none' | 'failed' | 'retrying' required

Last known error state of the deployment.

  • None: no errors
  • Retrying: an error has been encountered and the agent is retrying to reach the target status
  • Failed: a fatal error has been encountered; the deployment is archived and (if deployed) removed from the device
target_status'staged' | 'deployed' | 'archived' required

Desired state of the deployment.

  • Staged: is ready to be deployed
  • Deployed: all config instances part of the deployment are available for consumption on the device
  • Archived: the deployment is available for historical reference but cannot be deployed and is not active on the device
device_idstring required

ID of the device.

release_idstring required

ID of the release.

created_atstring date-time required

Timestamp of when the device release was created.

updated_atstring date-time required

Timestamp of when the device release was last updated.

Example response

{
  "object": "deployment",
  "id": "dpl_123",
  "description": "Deployment for the motion control config instance",
  "status": "staged",
  "activity_status": "staged",
  "error_status": "none",
  "target_status": "staged",
  "device_id": "dvc_123",
  "release_id": "rls_123",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Changes