Create - Miru

Scope	Required
`deployments:write`	Yes
`deployments:stage`	Required if staging a deployment.
`deployments:deploy`	Required if deploying a deployment.

Authorizations

X-API-Key

string

header

required

The API key to use for authentication.

Headers

Miru-Version

string

required

The API version the client was built against.

Example:

"2026-03-09.tetons"

Query Parameters

expand

enum<string>[]

Fields to expand on the deployment resource.

Available options:

device,

release,

config_instances

Example:

["device"]

Body

application/json

target_status

enum<string>

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.

Available options:

staged,

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"

config_instance_ids

string[]

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.

parent_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

The object type, which is always deployment.

Available options:

deployment

Example:

"deployment"

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:

drifted,

staged,

queued,

deployed,

archived,

failed,

retrying

activity_status

enum<string>

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

Available options:

drifted,

staged,

queued,

deployed,

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.

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

Available options:

staged,

deployed,

archived

device_id

string

required

ID of the device.

Example:

"dvc_123"

release_id

string

required

ID of the release.

Example:

"rls_123"

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

Base Device · object

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

Show child attributes

Example:

{
  "object": "device",
  "id": "dvc_123",
  "name": "My Device",
  "status": "online",
  "agent_version": "v1.0.0",
  "last_connected_at": "2021-01-01T00:00:00Z",
  "last_disconnected_at": null,
  "created_at": "2021-01-01T00:00:00Z",
  "updated_at": "2021-01-01T00:00:00Z"
}

release

Release · object

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

Show child attributes

Example:

{
  "object": "release",
  "id": "rls_123",
  "version": "v1.0.0",
  "git_commit_id": "git_commit_123",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

config_instances

Config Instance · object[]

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

Show child attributes

Example:

[
  {
    "object": "config_instance",
    "id": "cfg_inst_123",
    "config_type_name": "Motion Control",
    "filepath": "/v1/motion-control.json",
    "created_at": "2021-01-01T00:00:00Z",
    "config_schema_id": "cfg_sch_123",
    "config_type_id": "cfg_typ_123"
  },
  {
    "object": "config_instance",
    "id": "cfg_inst_124",
    "config_type_name": "Localization",
    "filepath": "/v1/localization.json",
    "created_at": "2021-01-01T00:00:00Z",
    "config_schema_id": "cfg_sch_124",
    "config_type_id": "cfg_typ_124"
  }
]