> ## Documentation Index > Fetch the complete documentation index at: https://docs.mirurobotics.com/llms.txt > Use this file to discover all available pages before exploring further. # Create > Stage or deploy a new deployment. This API version has reached end of life. See [supported versions](/developers/platform-api/versioning#supported-versions). | Scope | Required | | -------------------- | ----------------------------------- | | `deployments:write` | Yes | | `deployments:stage` | Required if staging a deployment. | | `deployments:deploy` | Required if deploying a deployment. | ## OpenAPI ````yaml /references/platform-api/2025-10-21.yaml post /deployments openapi: 3.0.3 info: title: Miru API version: 2025-10-21.zion license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://api.mirurobotics.com/beta description: Miru API security: - ApiKeyAuth: [] paths: /deployments: post: tags: - Deployments summary: Create description: Stage or deploy a new deployment. operationId: createDeployment parameters: - $ref: '#/components/parameters/parameters-expand' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDeploymentRequest' responses: '200': description: Successfully created the deployment. content: application/json: schema: $ref: '#/components/schemas/Deployment' x-codeSamples: - lang: Python source: |- from miru_server_sdk import Miru client = Miru( api_key="My API Key", ) deployment = client.deployments.create( description="Deployment for the motion control config instance", device_id="dvc_123", new_config_instances=[{ "config_schema_id": "cfg_sch_123", "content": { "direction": "forward", "speed": 100, "duration": 10, }, "relative_filepath": "/v1/motion-control.json", }], release_id="rls_123", target_status="staged", ) print(deployment.id) components: parameters: parameters-expand: name: expand[] in: query required: false schema: type: array items: $ref: '#/components/schemas/ExpandDeployment' description: The fields to expand in the deployment. schemas: CreateDeploymentRequest: title: Create Deployment Request type: object required: - target_status - description - release_id - device_id - new_config_instances properties: target_status: $ref: '#/components/schemas/CreateDeploymentTargetStatus' description: type: string example: Deployment for the motion control config instance description: The description of the deployment. release_id: type: string description: The release ID which this deployment adheres to. example: rls_123 patch_source_id: type: string description: The ID of the deployment that this deployment was patched from. example: dpl_123 device_id: type: string description: The ID of the device that the deployment is being created for. example: dvc_123 new_config_instances: type: array description: >- 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. items: $ref: '#/components/schemas/CreateConfigInstanceRequest' Deployment: title: Deployment allOf: - $ref: '#/components/schemas/BaseDeployment' - type: object required: - device - release - config_instances properties: device: allOf: - $ref: '#/components/schemas/Device' nullable: true example: null description: Expand the device using 'expand[]=device' in the query string. release: allOf: - $ref: '#/components/schemas/Release' nullable: true example: null description: Expand the release using 'expand[]=release' in the query string. config_instances: type: array items: $ref: '#/components/schemas/ConfigInstance' nullable: true description: >- Expand the config instances using 'expand[]=config_instances' in the query string. ExpandDeployment: type: string enum: - device - release - config_instances x-enum-varnames: - DEPLOYMENT_EXPAND_DEVICE - DEPLOYMENT_EXPAND_RELEASE - DEPLOYMENT_EXPAND_CONFIG_INSTANCES CreateDeploymentTargetStatus: type: string description: > 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. If custom validation is enabled for the release, the deployment must pass validation before fulfilling the target status. enum: - staged - deployed x-enum-varnames: - CREATE_STAGED_DEPLOYMENT - CREATE_DEPLOYED_DEPLOYMENT CreateConfigInstanceRequest: title: Create Config Instance Request type: object required: - config_schema_id - relative_filepath - content properties: config_schema_id: type: string description: >- The ID of the config schema which this config instance must adhere to. This schema must exist in the deployment's release. example: cfg_sch_123 relative_filepath: type: string example: /v1/motion-control.json description: >- The file path to deploy the config instance relative to `/srv/miru/config_instances`. `v1/motion-control.json` would deploy to `/srv/miru/config_instances/v1/motion-control.json`. content: type: object description: The configuration data. example: direction: forward speed: 100 duration: 10 BaseDeployment: title: Base Deployment type: object required: - object - id - description - status - activity_status - error_status - target_status - device_id - release_id - created_at - updated_at properties: object: type: string enum: - deployment example: deployment id: type: string example: dpl_123 description: ID of the deployment. description: type: string example: Deployment for the motion control config instance description: The description of the deployment. status: $ref: '#/components/schemas/DeploymentStatus' activity_status: $ref: '#/components/schemas/DeploymentActivityStatus' error_status: $ref: '#/components/schemas/DeploymentErrorStatus' target_status: $ref: '#/components/schemas/DeploymentTargetStatus' device_id: type: string example: dvc_123 description: ID of the device. release_id: type: string example: v1.0.0 description: The version of the release. created_at: type: string format: date-time example: '2024-01-01T00:00:00Z' description: Timestamp of when the device release was created. updated_at: type: string format: date-time example: '2024-01-01T00:00:00Z' description: Timestamp of when the device release was last updated. Device: allOf: - $ref: '#/components/schemas/BaseDevice' Release: title: Release allOf: - $ref: '#/components/schemas/BaseRelease' - type: object required: - config_schemas properties: config_schemas: type: array items: $ref: '#/components/schemas/ConfigSchema' nullable: true description: >- Expand the config schemas using 'expand[]=config_schemas' in the query string. example: [] ConfigInstance: title: Config Instance allOf: - $ref: '#/components/schemas/BaseConfigInstance' - type: object required: - device - config_schema - content properties: device: allOf: - $ref: '#/components/schemas/Device' nullable: true example: null config_schema: allOf: - $ref: '#/components/schemas/ConfigSchema' nullable: true description: >- Expand the config schema using 'expand[]=config_schema' in the query string. example: null config_type: allOf: - $ref: '#/components/schemas/ConfigType' nullable: true description: >- Expand the config type using 'expand[]=config_type' in the query string. example: null content: type: object description: >- The configuration values associated with the config instance. Expand the content using 'expand[]=content' in the query string. example: 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 nullable: true DeploymentStatus: type: string description: > 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'. enum: - validating - needs_review - staged - queued - deployed - removing - archived - failed - retrying x-enum-varnames: - DEPLOYMENT_STATUS_VALIDATING - DEPLOYMENT_STATUS_NEEDS_REVIEW - DEPLOYMENT_STATUS_STAGED - DEPLOYMENT_STATUS_QUEUED - DEPLOYMENT_STATUS_DEPLOYED - DEPLOYMENT_STATUS_REMOVING - DEPLOYMENT_STATUS_ARCHIVED - DEPLOYMENT_STATUS_FAILED - DEPLOYMENT_STATUS_RETRYING DeploymentActivityStatus: type: string description: > Last known activity state of the deployment. - Validating: the deployment's config instances are being validated with user's custom validation - Needs review: 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 - 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 enum: - validating - needs_review - staged - queued - deployed - removing - archived x-enum-varnames: - DEPLOYMENT_ACTIVITY_STATUS_VALIDATING - DEPLOYMENT_ACTIVITY_STATUS_NEEDS_REVIEW - DEPLOYMENT_ACTIVITY_STATUS_STAGED - DEPLOYMENT_ACTIVITY_STATUS_QUEUED - DEPLOYMENT_ACTIVITY_STATUS_DEPLOYED - DEPLOYMENT_ACTIVITY_STATUS_REMOVING - DEPLOYMENT_ACTIVITY_STATUS_ARCHIVED DeploymentErrorStatus: type: string description: > 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 enum: - none - failed - retrying x-enum-varnames: - DEPLOYMENT_ERROR_STATUS_NONE - DEPLOYMENT_ERROR_STATUS_FAILED - DEPLOYMENT_ERROR_STATUS_RETRYING DeploymentTargetStatus: type: string description: > 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 enum: - staged - deployed - archived x-enum-varnames: - DEPLOYMENT_TARGET_STATUS_STAGED - DEPLOYMENT_TARGET_STATUS_DEPLOYED - DEPLOYMENT_TARGET_STATUS_ARCHIVED BaseDevice: title: Base Device type: object required: - object - id - name - status - last_connected_at - last_disconnected_at - created_at - updated_at properties: object: type: string enum: - device example: device id: type: string example: dvc_123 description: ID of the device. name: type: string example: My Device description: Name of the device. status: $ref: '#/components/schemas/DeviceStatus' last_connected_at: type: string format: date-time example: '2021-01-01T00:00:00Z' nullable: true description: >- Timestamp of when the device was last made an initial connection (this is not the same as the last time the device was seen). last_disconnected_at: type: string format: date-time example: '2021-01-01T00:00:00Z' nullable: true description: >- Timestamp of when the device was last disconnected (this is not the same as the last time the device was seen). created_at: type: string format: date-time example: '2021-01-01T00:00:00Z' description: Timestamp of when the device was created. updated_at: type: string format: date-time example: '2021-01-01T00:00:00Z' description: Timestamp of when the device was last updated. BaseRelease: title: Base Release type: object required: - object - id - version - created_at - updated_at properties: object: type: string enum: - release example: release id: type: string example: rls_123 description: ID of the release. version: type: string example: v1.0.0 description: The version of the release. created_at: type: string format: date-time example: '2024-01-01T00:00:00Z' description: Timestamp of when the release was created. updated_at: type: string format: date-time example: '2024-01-01T00:00:00Z' description: Timestamp of when the release was last updated. ConfigSchema: title: Config Schema allOf: - $ref: '#/components/schemas/BaseConfigSchema' - type: object required: - config_type properties: config_type: allOf: - $ref: '#/components/schemas/ConfigType' nullable: true description: >- Expand the config type using 'expand[]=config_type' in the query string. example: null BaseConfigInstance: title: Base Config Instance type: object required: - object - id - target_status - activity_status - error_status - status - relative_filepath - created_at - updated_at - device_id - config_schema_id - config_type_id properties: object: type: string enum: - config_instance example: config_instance id: type: string example: cfg_inst_123 description: ID of the config instance. target_status: $ref: '#/components/schemas/ConfigInstanceTargetStatus' activity_status: $ref: '#/components/schemas/ConfigInstanceActivityStatus' error_status: $ref: '#/components/schemas/ConfigInstanceErrorStatus' status: $ref: '#/components/schemas/ConfigInstanceStatus' relative_filepath: type: string example: /v1/motion-control.json description: >- The file path to deploy the config instance relative to `/srv/miru/config_instances`. `v1/motion-control.json` would deploy to `/srv/miru/config_instances/v1/motion-control.json`. created_at: type: string format: date-time example: '2021-01-01T00:00:00Z' description: The timestamp of when the config instance was created. updated_at: type: string format: date-time example: '2021-01-01T00:00:00Z' description: The timestamp of when the config instance was last updated. device_id: type: string example: dvc_123 description: ID of the device which the config instance is deployed to. config_schema_id: type: string example: cfg_sch_123 description: ID of the config schema which the config instance must adhere to. config_type_id: type: string example: cfg_type_123 description: >- ID of the config type which the config instance (and its schema) is a part of. ConfigType: title: Config Type allOf: - $ref: '#/components/schemas/BaseConfigType' DeviceStatus: type: string description: > The status of the device. - Inactive: The miru agent has not yet been installed / authenticated - Activating: The miru agent is currently being installed / authenticated (should only last for a few seconds) - Online: The miru agent has successfully pinged the server within the last 60 seconds. - Offline: The miru agent has not successfully pinged the server within the last 60 seconds (e.g. network issues, device is powered off, etc.) enum: - inactive - activating - online - offline x-enum-varnames: - DEVICE_STATUS_INACTIVE - DEVICE_STATUS_ACTIVATING - DEVICE_STATUS_ONLINE - DEVICE_STATUS_OFFLINE BaseConfigSchema: title: Base Config Schema type: object required: - object - id - version - digest - relative_filepath - created_at - updated_at - config_type_id - content properties: object: type: string enum: - config_schema example: config_schema id: type: string example: cfg_sch_123 description: ID of the config schema. version: type: integer example: 2 description: Config schema version for the config type. digest: type: string example: '1234567890' description: Hash of the config schema contents. relative_filepath: type: string example: /v1/motion-control.json description: >- The file path to deploy the config instance relative to `/srv/miru/config_instances`. `v1/motion-control.json` would deploy to `/srv/miru/config_instances/v1/motion-control.json`. created_at: type: string format: date-time example: '2021-01-01T00:00:00Z' description: Timestamp of when the config schema was created. updated_at: type: string format: date-time example: '2021-01-01T00:00:00Z' description: Timestamp of when the config schema was last updated. config_type_id: type: string example: cfg_typ_123 description: ID of the config type. content: type: object description: The config schema's JSON Schema definition. example: title: Robot Features type: object properties: enable_autonomy: type: boolean default: true enable_remote_control: type: boolean default: true max_payload_kg: type: number minimum: 0 maximum: 99 default: 10 preferred_speed_mode: type: string enum: - slow - normal - fast default: normal emergency_stop_sensitivity: type: number minimum: 0 maximum: 1 default: 0.8 telemetry: type: object properties: upload_interval_sec: type: integer minimum: 10 maximum: 600 default: 60 heartbeat_interval_sec: type: integer minimum: 1 maximum: 60 default: 10 required: - upload_interval_sec - heartbeat_interval_sec required: - enable_autonomy - enable_remote_control - max_payload_kg - preferred_speed_mode - emergency_stop_sensitivity - telemetry nullable: true ConfigInstanceTargetStatus: type: string description: > Desired state of the config instance. - Created: config instance is created and can be deployed in the future - Deployed: config instance is available for consumption on the device - Removed: config instance is available for historical reference but cannot be deployed and is not active on the device enum: - created - deployed - removed x-enum-varnames: - CONFIG_INSTANCE_TARGET_STATUS_CREATED - CONFIG_INSTANCE_TARGET_STATUS_DEPLOYED - CONFIG_INSTANCE_TARGET_STATUS_REMOVED ConfigInstanceActivityStatus: type: string description: > Last known activity state of the config instance. - Created: config instance has been created and can be deployed in the future - Queued: config instance is waiting to be received by the device; will be deployed as soon as the device is online - Deployed: config instance is currently available for consumption on the device - Removed: the config instance is available for historical reference but cannot be deployed and is not active on the device enum: - created - queued - deployed - removed x-enum-varnames: - CONFIG_INSTANCE_ACTIVITY_STATUS_CREATED - CONFIG_INSTANCE_ACTIVITY_STATUS_QUEUED - CONFIG_INSTANCE_ACTIVITY_STATUS_DEPLOYED - CONFIG_INSTANCE_ACTIVITY_STATUS_REMOVED ConfigInstanceErrorStatus: type: string description: > Last known error state of the config instance deployment. - None: there are no errors with the config instance deployment - Retrying: an error has been encountered and the agent is attempting to try again to reach the target status - Failed: a fatal error has been encountered; the config instance is archived and (if deployed) removed from the device enum: - none - failed - retrying x-enum-varnames: - CONFIG_INSTANCE_ERROR_STATUS_NONE - CONFIG_INSTANCE_ERROR_STATUS_FAILED - CONFIG_INSTANCE_ERROR_STATUS_RETRYING ConfigInstanceStatus: type: string description: > 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'. enum: - created - queued - deployed - removed - failed - retrying x-enum-varnames: - CONFIG_INSTANCE_STATUS_CREATED - CONFIG_INSTANCE_STATUS_QUEUED - CONFIG_INSTANCE_STATUS_DEPLOYED - CONFIG_INSTANCE_STATUS_REMOVED - CONFIG_INSTANCE_STATUS_FAILED - CONFIG_INSTANCE_STATUS_RETRYING BaseConfigType: title: Config Type type: object required: - object - id - name - slug - created_at - updated_at properties: object: type: string enum: - config_type example: config_type id: type: string example: cfg_123 description: ID of the config type. name: type: string example: My Config Type description: Name of the config type. slug: type: string example: my-config-type description: An immutable, code-friendly name for the config type. created_at: type: string format: date-time example: '2021-01-01T00:00:00Z' description: Timestamp of when the config type was created. updated_at: type: string format: date-time example: '2021-01-01T00:00:00Z' description: Timestamp of when the config type was last updated. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- The API key to use for authentication. Retrieve your API key from the [Miru dashboard](https://app.mirurobotics.com/settings/api-keys). ````