Skip to main content
POST
/
deployments
Create
curl --request POST \
  --url https://{host}/{version}/deployments \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "target_status": "pending",
  "description": "Deployment for the motion control config instance",
  "release_id": "rls_123",
  "patch_source_id": "dpl_123",
  "device_id": "dvc_123",
  "new_config_instances": [
    {
      "config_schema_id": "cfg_sch_123",
      "relative_filepath": "/v1/motion-control.json",
      "content": {
        "direction": "forward",
        "speed": 100,
        "duration": 10
      }
    }
  ]
}'
{
  "object": "deployment",
  "id": "dpl_123",
  "description": "Deployment for the motion control config instance",
  "status": "validating",
  "activity_status": "validating",
  "error_status": "none",
  "target_status": "pending",
  "device_id": "dvc_123",
  "release_id": "v1.0.0",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "device": null,
  "release": null,
  "config_instances": [
    {
      "object": "config_instance",
      "id": "cfg_inst_123",
      "target_status": "created",
      "activity_status": "created",
      "error_status": "none",
      "status": "created",
      "relative_filepath": "/v1/motion-control.json",
      "created_at": "2021-01-01T00:00:00Z",
      "updated_at": "2021-01-01T00:00:00Z",
      "device_id": "dvc_123",
      "config_schema_id": "cfg_sch_123",
      "config_type_id": "cfg_type_123",
      "device": null,
      "config_schema": null,
      "config_type": null,
      "content": {
        "enable_autonomy": true,
        "enable_remote_control": false,
        "max_payload_kg": 8.5,
        "preferred_speed_mode": "normal",
        "emergency_stop_sensitivity": 0.9,
        "telemetry": {
          "upload_interval_sec": 45,
          "heartbeat_interval_sec": 15
        }
      }
    }
  ]
}

Authorizations

​
X-API-Key
string
header
required

The API key to use for authentication. Retrieve your API key from the Miru dashboard.

Query Parameters

​
expand[]
enum<string>[]

The fields to expand in the deployment.

Body

application/json
​
target_status
enum<string>
required

Desired state of the deployment.

  • Pending: staged for deployment but not yet approved. Deployments can only be staged if their release is not the current release for the device.
  • Approved: staged and approved 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.

If custom validation is enabled for the release, the deployment must pass validation before fulfilling the target status.

Available options:
pending,
approved,
deployed
​
description
string
required

The description of the deployment.

Example:

"Deployment for the motion control config instance"

​
release_id
string
required

The release ID which this deployment adheres to.

Example:

"rls_123"

​
device_id
string
required

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

Example:

"dvc_123"

​
new_config_instances
Create Config Instance Request · object[]
required

The new config instances to create for this deployment. A deployment must have exactly one config instance for each config schema in the deployment's release. If less config instances are provided than the number of schemas, the deployment will 'transfer' config instances from the deployment it is patched from. Archived config instances cannot be transferred.

​
patch_source_id
string

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

Example:

"dpl_123"

Response

200 - application/json

Successfully created the deployment.

​
object
enum<string>
required
Available options:
deployment
Example:

"deployment"

​
id
string
required

ID of the deployment.

Example:

"dpl_123"

​
description
string
required

The description of the deployment.

Example:

"Deployment for the motion control config instance"

​
status
enum<string>
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'.

Available options:
validating,
pending,
approved,
queued,
deployed,
removing,
archived,
failed,
retrying
​
activity_status
enum<string>
required

Last known activity state of the deployment.

  • Validating: the deployment's config instances are being validated with user's custom validation
  • Pending: staged for deployment but not yet approved; requires approval for deployment to occur
  • Approved: staged and approved for deployment
  • 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
  • Removing: the deployment's config instances are being removed from the device
  • Archived: the deployment is available for historical reference but cannot be deployed and is not active on the device
Available options:
validating,
pending,
approved,
queued,
deployed,
removing,
archived
​
error_status
enum<string>
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
Available options:
none,
failed,
retrying
​
target_status
enum<string>
required

Desired state of the deployment.

  • Pending: staged for deployment but not yet approved; requires approval for deployment to occur
  • Approved: staged and approved for deployment
  • 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
Available options:
pending,
approved,
deployed,
archived
​
device_id
string
required

ID of the device.

Example:

"dvc_123"

​
release_id
string
required

The version of the release.

Example:

"v1.0.0"

​
created_at
string<date-time>
required

Timestamp of when the device release was created.

Example:

"2024-01-01T00:00:00Z"

​
updated_at
string<date-time>
required

Timestamp of when the device release was last updated.

Example:

"2024-01-01T00:00:00Z"

​
device
object
required

Expand the device using 'expand[]=device' in the query string.

Example:

null

​
release
object
required

Expand the release using 'expand[]=release' in the query string.

Example:

null

​
config_instances
Config Instance · object[] | null
required

Expand the config instances using 'expand[]=config_instances' in the query string.

⌘I