> ## 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.

# Get

> Retrieve a deployment by its ID.

| Scope | Required |
| - | - |
| `deployments:read` | Yes |


## OpenAPI

````yaml /references/platform-api/2026-11-04.yaml get /deployments/{deployment_id}
openapi: 3.0.3
info:
  title: Miru Platform API
  description: The API between Miru and any external client
  version: 2026-11-04.everglades
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-release-version: 2026-11-04.everglades
  x-git-commit:
    sha: e1decbb4c54ce8a4bf2f78b8728b2b10654294c9
    url: >-
      https://github.com/mirurobotics/openapi/commit/e1decbb4c54ce8a4bf2f78b8728b2b10654294c9
    message: >-
      feat(platform): add archived and deleted list filters, and tidy
      descriptions (#446)
    author: Ben's Agent
    branch: HEAD
    dirty: false
  x-build:
    built_at: '2026-11-05T23:04:32.018858+00:00'
servers:
  - url: https://api.mirurobotics.com/beta
    description: Miru Platform API
security:
  - ApiKeyAuth: []
paths:
  /deployments/{deployment_id}:
    parameters:
      - $ref: '#/components/parameters/MiruVersion'
    get:
      tags:
        - Deployments
      summary: Get
      description: Retrieve a deployment by its ID.
      operationId: getDeployment
      parameters:
        - $ref: '#/components/parameters/deployment_id'
        - $ref: '#/components/parameters/deployment_expansions'
      responses:
        '200':
          description: Successfully retrieved the deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
components:
  parameters:
    MiruVersion:
      name: Miru-Version
      in: header
      required: true
      schema:
        type: string
        example: 2026-11-04.everglades
      description: The API version the client was built against.
    deployment_id:
      name: deployment_id
      in: path
      required: true
      description: The unique identifier of the deployment.
      schema:
        type: string
        example: dpl_123
    deployment_expansions:
      name: expand
      in: query
      required: false
      description: Fields to expand on the deployment resource.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/DeploymentExpansion'
        example:
          - device
  schemas:
    Deployment:
      title: Deployment
      allOf:
        - $ref: '#/components/schemas/BaseDeployment'
        - type: object
          required:
            - parent_id
            - staged_at
            - queued_at
            - deployed_at
            - archived_at
            - created_by_id
            - staged_by_id
            - queued_by_id
          properties:
            parent_id:
              type: string
              nullable: true
              example: dpl_123
              description: >-
                ID of the deployment that this deployment was patched from. Null
                if this deployment has no parent.
            staged_at:
              type: string
              format: date-time
              example: '2021-01-01T00:00:00Z'
              nullable: true
              description: >-
                Timestamp of when the deployment was staged. Null when the
                deployment was created already queued (`queued_at` is not after
                `created_at`); otherwise equal to `created_at`.
            queued_at:
              type: string
              format: date-time
              example: '2021-01-01T00:00:00Z'
              nullable: true
              description: >-
                Timestamp of when a principal last queued the deployment, i.e.
                requested that it be deployed to its device. Device status
                reports do not change it.
            deployed_at:
              type: string
              format: date-time
              example: '2021-01-01T00:00:00Z'
              nullable: true
              description: >-
                Timestamp of the last time the device's agent confirmed that the
                deployment was deployed. Set by the agent. A watermark of the
                latest transition; it is not cleared when the deployment later
                changes state.
            archived_at:
              type: string
              format: date-time
              example: '2021-01-01T00:00:00Z'
              nullable: true
              description: >-
                Timestamp of the last time the device's agent confirmed that the
                deployment was archived. Set by the agent. A watermark of the
                latest transition; it is not cleared when the deployment later
                changes state.
            created_by_id:
              type: string
              example: usr_123
              description: ID of the principal who created the deployment.
            staged_by_id:
              type: string
              example: usr_123
              nullable: true
              description: >-
                ID of the principal who staged the deployment. Null when the
                deployment was created already queued; otherwise equal to
                `created_by_id`.
            queued_by_id:
              type: string
              example: usr_123
              nullable: true
              description: >-
                ID of the principal who queued the deployment, i.e. requested
                that it be deployed to its device. Recorded at the same moment
                as `queued_at`. Null if the deployment was never queued or was
                queued before this field was recorded.
            created_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              description: >-
                The principal who created the deployment. Expand using
                `expand=created_by` in the query string.
            staged_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              nullable: true
              description: >-
                The principal who staged the deployment. Null if `staged_by_id`
                is null. Expand using `expand=staged_by` in the query string.
            queued_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              nullable: true
              description: >-
                The principal who queued the deployment. Null if `queued_by_id`
                is null. Expand using `expand=queued_by` in the query string.
            device:
              allOf:
                - $ref: '#/components/schemas/Device'
              description: Expand the device using `expand=device` in the query string.
            release:
              allOf:
                - $ref: '#/components/schemas/Release'
              description: Expand the release using `expand=release` in the query string.
            parent:
              allOf:
                - $ref: '#/components/schemas/Deployment'
              nullable: true
              description: >-
                The parent deployment that this deployment was patched from.
                Null if this deployment has no parent. Expand the parent using
                `expand=parent` in the query string.
            config_instances:
              type: array
              items:
                $ref: '#/components/schemas/ConfigInstance'
              description: >-
                Expand the config instances using `expand=config_instances` in
                the query string.
              example:
                - object: config_instance
                  id: cfg_inst_123
                  config_type_name: Motion Control
                  filepath: /srv/miru/configs/v1/motion-control.json
                  slot_key: default
                  created_at: '2021-01-01T00:00:00Z'
                  config_schema_id: cfg_sch_123
                  config_type_id: cfg_typ_123
                  created_by_id: usr_123
                - object: config_instance
                  id: cfg_inst_124
                  config_type_name: Localization
                  filepath: /srv/miru/configs/v1/localization/primary.json
                  slot_key: primary
                  created_at: '2021-01-01T00:00:00Z'
                  config_schema_id: cfg_sch_124
                  config_type_id: cfg_typ_124
                  created_by_id: usr_123
      example:
        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
        parent_id: null
        created_at: '2024-01-01T00:00:00Z'
        updated_at: '2024-01-01T00:00:00Z'
        staged_at: '2024-01-01T00:00:00Z'
        queued_at: null
        deployed_at: null
        archived_at: null
        created_by_id: usr_123
        staged_by_id: usr_123
        queued_by_id: null
    DeploymentExpansion:
      type: string
      enum:
        - device
        - release
        - parent
        - config_instances
        - created_by
        - staged_by
        - queued_by
      x-enum-varnames:
        - DEPLOYMENT_EXPAND_DEVICE
        - DEPLOYMENT_EXPAND_RELEASE
        - DEPLOYMENT_EXPAND_PARENT
        - DEPLOYMENT_EXPAND_CONFIG_INSTANCES
        - DEPLOYMENT_EXPAND_CREATED_BY
        - DEPLOYMENT_EXPAND_STAGED_BY
        - DEPLOYMENT_EXPAND_QUEUED_BY
    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
          x-stainless-const: true
          description: The object type, which is always `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: rls_123
          description: ID of the release.
        created_at:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
          description: Timestamp of when the deployment was created.
        updated_at:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
          description: Timestamp of when the deployment was last updated.
    Principal:
      title: Principal
      type: object
      required:
        - object
        - id
        - name
        - type
      properties:
        object:
          type: string
          enum:
            - principal
          example: principal
          x-stainless-const: true
          description: The object type, which is always `principal`.
        id:
          type: string
          example: api_key_123
          description: ID of the principal.
        name:
          type: string
          example: My CI/CD Key
          description: The display name of the principal.
        type:
          allOf:
            - $ref: '#/components/schemas/PrincipalType'
          description: >-
            The kind of principal. More types may be added, so handle unknown
            values.
      example:
        object: principal
        id: api_key_123
        name: My CI/CD Key
        type: api_key
    Device:
      allOf:
        - $ref: '#/components/schemas/BaseDevice'
        - type: object
          required:
            - group_id
            - created_by_id
            - archived_at
            - archived_by_id
          properties:
            group_id:
              type: string
              nullable: true
              example: grp_123
              description: >-
                ID of the group this device belongs to. Null if the device is
                unassigned.
            created_by_id:
              type: string
              example: usr_123
              description: ID of the principal who created the device.
            archived_at:
              type: string
              format: date-time
              example: '2021-01-01T00:00:00Z'
              nullable: true
              description: >-
                Timestamp of when the device was archived. Null if the device is
                not archived.
            archived_by_id:
              type: string
              example: usr_123
              nullable: true
              description: >-
                ID of the principal who archived the device. Null if the device
                is not archived or was archived before this field was recorded.
            created_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              description: >-
                The principal who created the device. Expand using
                `expand=created_by` in the query string.
            archived_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              nullable: true
              description: >-
                The principal who archived the device. Null if `archived_by_id`
                is null. Expand using `expand=archived_by` in the query string.
            current_deployment:
              allOf:
                - $ref: '#/components/schemas/Deployment'
              nullable: true
              description: The current deployment for the device.
            current_release:
              allOf:
                - $ref: '#/components/schemas/Release'
              nullable: true
              description: The current release for the device.
            group:
              allOf:
                - $ref: '#/components/schemas/Group'
              nullable: true
              description: >-
                The group this device belongs to. Null if the device is
                unassigned.
      example:
        object: device
        id: dvc_123
        name: My Device
        description: Welder on line 3
        status: online
        agent_version: v1.0.0
        os: linux
        hostname: robot-1.local
        arch: x86_64
        os_version: Ubuntu 22.04
        kernel_version: 5.15.0-91-generic
        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'
        group_id: grp_123
        created_by_id: usr_123
        archived_at: null
        archived_by_id: null
    Release:
      title: Release
      allOf:
        - $ref: '#/components/schemas/BaseRelease'
        - type: object
          required:
            - created_by_id
            - archived_at
            - archived_by_id
          properties:
            created_by_id:
              type: string
              example: usr_123
              description: ID of the principal who created the release.
            archived_at:
              type: string
              format: date-time
              example: '2021-01-01T00:00:00Z'
              nullable: true
              description: >-
                Timestamp of when the release was archived. Null if the release
                is not archived.
            archived_by_id:
              type: string
              example: usr_123
              nullable: true
              description: >-
                ID of the principal who archived the release. Null if the
                release is not archived or was archived before this field was
                recorded.
            created_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              description: >-
                The principal who created the release. Expand using
                `expand=created_by` in the query string.
            archived_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              nullable: true
              description: >-
                The principal who archived the release. Null if `archived_by_id`
                is null. Expand using `expand=archived_by` in the query string.
            config_schemas:
              type: array
              items:
                $ref: '#/components/schemas/ConfigSchema'
              description: >-
                Expand the config schemas using `expand=config_schemas` in the
                query string.
              example:
                - object: config_schema
                  id: cfg_sch_123
                  digest: sha256:1234567890
                  os: linux
                  config_type_name: Motion Control
                  instance_slots:
                    - key: default
                      name: Default
                      filepath: /srv/miru/configs/v1/motion-control.json
                      required: true
                  instance_format: json
                  created_at: '2021-01-01T00:00:00Z'
                  updated_at: '2021-01-01T00:00:00Z'
                  config_type_id: cfg_typ_123
                  language: jsonschema
                  format: json
                  created_by_id: usr_123
                - object: config_schema
                  id: cfg_sch_124
                  digest: sha256:1234567890
                  os: linux
                  config_type_name: Localization
                  instance_slots:
                    - key: primary
                      name: Primary
                      filepath: /srv/miru/configs/v1/localization/primary.json
                      required: true
                    - key: secondary
                      name: Secondary
                      filepath: /srv/miru/configs/v1/localization/secondary.json
                      required: false
                  instance_format: json
                  created_at: '2021-01-01T00:00:00Z'
                  updated_at: '2021-01-01T00:00:00Z'
                  config_type_id: cfg_typ_124
                  language: jsonschema
                  format: json
                  created_by_id: usr_123
      example:
        object: release
        id: rls_123
        version: v1.0.0
        description: Add lidar calibration to motion control
        git_commit_id: git_commit_123
        os: linux
        created_at: '2024-01-01T00:00:00Z'
        updated_at: '2024-01-01T00:00:00Z'
        created_by_id: usr_123
        archived_at: null
        archived_by_id: null
    ConfigInstance:
      title: Config Instance
      allOf:
        - $ref: '#/components/schemas/BaseConfigInstance'
        - type: object
          required:
            - created_by_id
          properties:
            created_by_id:
              type: string
              example: usr_123
              description: ID of the principal who created the config instance.
            created_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              description: >-
                The principal who created the config instance. Expand using
                `expand=created_by` in the query string.
            config_schema:
              allOf:
                - $ref: '#/components/schemas/ConfigSchema'
              description: >-
                Expand the config schema using `expand=config_schema` in the
                query string.
            config_type:
              allOf:
                - $ref: '#/components/schemas/ConfigType'
              description: >-
                Expand the config type using `expand=config_type` in the query
                string.
            content:
              allOf:
                - $ref: '#/components/schemas/InstanceContent'
              description: >-
                The configuration values associated with the config instance.
                Expand the content using `expand=content` in the query string.
      example:
        object: config_instance
        id: cfg_inst_123
        config_type_name: Motion Control
        filepath: /srv/miru/configs/v1/motion-control.json
        slot_key: default
        created_at: '2021-01-01T00:00:00Z'
        config_schema_id: cfg_sch_123
        config_type_id: cfg_typ_123
        created_by_id: usr_123
    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:
        - drifted
        - staged
        - queued
        - deployed
        - removing
        - archived
        - failed
        - retrying
      x-enum-varnames:
        - DEPLOYMENT_STATUS_DRIFTED
        - 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.


        `drifted` means the device's configurations have drifted since this
        deployment was staged, and the deployment needs to be reviewed before it
        can be deployed.


        `staged` means the deployment is ready to be deployed.


        `queued` means the deployment's config instances are waiting to be
        received by the device and will be deployed as soon as the device is
        online.


        `deployed` means the deployment's config instances are currently
        available for consumption on the device.


        `removing` means the deployment's config instances are being removed
        from the device.


        `archived` means the deployment is available for historical reference
        but cannot be deployed and is not active on the device.
      enum:
        - drifted
        - staged
        - queued
        - deployed
        - removing
        - archived
      x-enum-varnames:
        - DEPLOYMENT_ACTIVITY_STATUS_DRIFTED
        - 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` means there are no errors.


        `retrying` means an error has been encountered and the agent is retrying
        to reach the target status.


        `failed` means 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` means the deployment is ready to be deployed.


        `deployed` means all config instances in the deployment are available
        for consumption on the device.


        `archived` means 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
    PrincipalType:
      title: Principal Type
      type: string
      enum:
        - user
        - api_key
        - device
    BaseDevice:
      title: Base Device
      type: object
      required:
        - object
        - id
        - name
        - description
        - status
        - agent_version
        - os
        - hostname
        - arch
        - os_version
        - kernel_version
        - last_connected_at
        - last_disconnected_at
        - created_at
        - updated_at
      properties:
        object:
          type: string
          enum:
            - device
          example: device
          x-stainless-const: true
          description: The object type, which is always `device`.
        id:
          type: string
          example: dvc_123
          description: ID of the device.
        name:
          type: string
          example: My Device
          description: Name of the device.
        description:
          type: string
          nullable: true
          example: Welder on line 3
          description: A free-form description of the device.
        status:
          $ref: '#/components/schemas/DeviceStatus'
        agent_version:
          type: string
          example: v1.0.0
          description: The version of the agent the device is running.
          nullable: true
        os:
          allOf:
            - $ref: '#/components/schemas/OS'
          nullable: true
          description: >-
            The operating system family the device is running (`linux` or
            `windows`), reported by the agent. This is the machine-readable OS
            kind, distinct from the human-readable `os_version` string.
        hostname:
          type: string
          example: robot-1.local
          description: The hostname of the device as reported by the agent.
          nullable: true
        arch:
          allOf:
            - $ref: '#/components/schemas/Arch'
          nullable: true
          description: >-
            The CPU architecture the device is running (`x86_64` or `aarch64`),
            reported by the agent.
        os_version:
          type: string
          example: Ubuntu 22.04
          description: >-
            The human-readable long operating system version string reported by
            the agent (for example `Ubuntu 22.04` or `Windows 11 Pro`). Distinct
            from the machine-readable `os` family.
          nullable: true
        kernel_version:
          type: string
          example: 5.15.0-91-generic
          description: The operating system kernel version string reported by the agent.
          nullable: true
        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.
    Group:
      title: Group
      allOf:
        - $ref: '#/components/schemas/BaseGroup'
        - type: object
          required:
            - created_by_id
          properties:
            created_by_id:
              type: string
              example: usr_123
              description: ID of the principal who created the group.
            created_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              description: >-
                The principal who created the group. Expand using
                `expand=created_by` in the query string.
            parent:
              allOf:
                - $ref: '#/components/schemas/Group'
              nullable: true
              description: >-
                The parent group. Null for top-level groups. Expand using
                `expand=parent` in the query string.
      example:
        object: group
        id: grp_789
        name: line-3
        parent_id: grp_456
        created_at: '2026-01-01T00:00:00Z'
        updated_at: '2026-01-01T00:00:00Z'
        created_by_id: usr_123
    BaseRelease:
      title: Base Release
      type: object
      required:
        - object
        - id
        - version
        - description
        - git_commit_id
        - os
        - created_at
        - updated_at
      properties:
        object:
          type: string
          enum:
            - release
          example: release
          x-stainless-const: true
          description: The object type, which is always `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.
        description:
          type: string
          nullable: true
          example: Add lidar calibration to motion control
          description: A free-form description of the release.
        git_commit_id:
          type: string
          nullable: true
          example: git_commit_123
          description: The ID of the git commit associated with this release.
        os:
          allOf:
            - $ref: '#/components/schemas/OS'
          readOnly: true
          description: >-
            The operating system family this release targets, derived from its
            config schemas and file rules, which must all agree. A release with
            neither is `linux`. Read-only: clients cannot set it.
        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
          properties:
            created_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              description: >-
                The principal who created the config schema. Expand using
                `expand=created_by` in the query string.
            config_schema_git_commits:
              allOf:
                - $ref: '#/components/schemas/ConfigSchemaGitCommitList'
              description: >-
                The git commits the config schema was registered from, with the
                schema's file paths at each commit. Expand using
                `expand=config_schema_git_commits` in the query string.
            config_type:
              allOf:
                - $ref: '#/components/schemas/ConfigType'
              description: >-
                Expand the config type using `expand=config_type` in the query
                string.
      example:
        object: config_schema
        id: cfg_sch_123
        digest: sha256:1234567890
        os: linux
        config_type_name: Motion Control
        instance_slots:
          - key: default
            name: Default
            filepath: /srv/miru/configs/v1/motion-control.json
            required: true
        instance_format: json
        created_at: '2021-01-01T00:00:00Z'
        updated_at: '2021-01-01T00:00:00Z'
        config_type_id: cfg_typ_123
        language: jsonschema
        format: json
        created_by_id: usr_123
    BaseConfigInstance:
      title: Base Config Instance
      type: object
      required:
        - object
        - id
        - config_type_name
        - filepath
        - created_at
        - config_schema_id
        - config_type_id
        - slot_key
      properties:
        object:
          type: string
          enum:
            - config_instance
          example: config_instance
          x-stainless-const: true
          description: The object type, which is always `config_instance`.
        id:
          type: string
          example: cfg_inst_123
          description: ID of the config instance.
        config_type_name:
          type: string
          example: Motion Control
          description: The name of the config type.
        filepath:
          type: string
          example: /srv/miru/configs/v1/motion-control.json
          description: The absolute file system path where this config instance is written.
        slot_key:
          type: string
          example: controller_2
          description: >-
            The key of the config schema slot this instance is bound to. Must
            match the `key` of one of the slots declared by this instance's
            config schema.
        created_at:
          type: string
          format: date-time
          example: '2021-01-01T00:00:00Z'
          description: The timestamp of when the config instance was created.
        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:
      allOf:
        - $ref: '#/components/schemas/BaseConfigType'
        - type: object
          properties:
            created_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              description: >-
                The principal who created the config type. Expand using
                `expand=created_by` in the query string.
            archived_by:
              allOf:
                - $ref: '#/components/schemas/Principal'
              nullable: true
              description: >-
                The principal who archived the config type. Null if
                `archived_by_id` is null. Expand using `expand=archived_by` in
                the query string.
      example:
        object: config_type
        id: cfg_typ_123
        name: Motion Control
        slug: motion-control
        created_at: '2021-01-01T00:00:00Z'
        updated_at: '2021-01-01T00:00:00Z'
        created_by_id: usr_123
        archived_at: null
        archived_by_id: null
    InstanceContent:
      title: Instance Content
      type: object
      required:
        - format
        - data
      properties:
        format:
          $ref: '#/components/schemas/InstanceFormat'
        data:
          type: string
          description: The content's values, serialized in `format`.
          example: |
            {
              "enable_autonomy": true,
              "enable_remote_control": true,
              "max_payload_kg": 10.0
            }
      example:
        format: json
        data: |
          {
            "enable_autonomy": true,
            "enable_remote_control": true,
            "max_payload_kg": 10.0
          }
    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.)

        - Archived: The device has been archived. The agent's session has been
        revoked and the device no longer participates in workspace operations.
        See `archived_at` for when this occurred.
      enum:
        - inactive
        - activating
        - online
        - offline
        - archived
      x-enum-varnames:
        - DEVICE_STATUS_INACTIVE
        - DEVICE_STATUS_ACTIVATING
        - DEVICE_STATUS_ONLINE
        - DEVICE_STATUS_OFFLINE
        - DEVICE_STATUS_ARCHIVED
    OS:
      title: OS
      type: string
      description: >
        An operating system family, from the agent's build-time OS vocabulary.
        Shared across resources (devices, config schemas, file rules, releases).
        This is the machine-readable OS kind, distinct from a human-readable
        version string.

        - `linux`

        - `windows`
      example: linux
      enum:
        - linux
        - windows
      x-enum-varnames:
        - OS_LINUX
        - OS_WINDOWS
    Arch:
      title: Arch
      type: string
      description: >
        A CPU architecture, from the agent's build-time architecture vocabulary.
        Shared across resources (devices, config schemas, file rules). These are
        the canonical wire values.

        - `x86_64`

        - `aarch64`
      example: x86_64
      enum:
        - x86_64
        - aarch64
      x-enum-varnames:
        - ARCH_X86_64
        - ARCH_AARCH64
    BaseGroup:
      title: Base Group
      type: object
      required:
        - object
        - id
        - name
        - parent_id
        - created_at
        - updated_at
      properties:
        object:
          type: string
          enum:
            - group
          example: group
          x-stainless-const: true
          description: The object type, which is always `group`.
        id:
          type: string
          example: grp_123
          description: ID of the group.
        name:
          type: string
          example: production
          description: Name of the group.
        parent_id:
          type: string
          nullable: true
          example: grp_456
          description: ID of the parent group. Null for top-level groups.
        created_at:
          type: string
          format: date-time
          example: '2026-01-01T00:00:00Z'
          description: Timestamp of when the group was created.
        updated_at:
          type: string
          format: date-time
          example: '2026-01-01T00:00:00Z'
          description: Timestamp of when the group was last updated.
    BaseConfigSchema:
      title: Base Config Schema
      type: object
      required:
        - object
        - id
        - digest
        - os
        - config_type_name
        - instance_format
        - created_at
        - updated_at
        - created_by_id
        - config_type_id
        - language
        - format
        - instance_slots
      properties:
        object:
          type: string
          enum:
            - config_schema
          example: config_schema
          x-stainless-const: true
          description: The object type, which is always `config_schema`.
        id:
          type: string
          example: cfg_sch_123
          description: ID of the config schema.
        digest:
          type: string
          example: sha256:1234567890
          description: The digest of the config schema.
        os:
          allOf:
            - $ref: '#/components/schemas/OS'
          readOnly: true
          description: >-
            The operating system family this config schema targets, derived from
            its instance slot filepaths, which must all agree. A schema created
            without `instance_slots` gets a default slot at a Unix path, so it
            is `linux`. Read-only: clients cannot set it.
        config_type_name:
          type: string
          example: Motion Control
          description: The name of the config type.
        instance_slots:
          type: array
          minItems: 1
          description: >-
            The file system destinations this config schema writes to. Every
            config schema has at least one slot. Slots share the schema's
            validation and differ only in where the file is written; a file
            needing different validation is a different config type, not a slot.
            Slot keys and filepaths must each be unique within the schema, and
            slot filepaths must be unique across every config schema in a
            release.
          items:
            $ref: '#/components/schemas/InstanceSlot'
          example:
            - key: default
              name: Default
              filepath: /srv/miru/configs/v1/motion-control.json
              required: true
        instance_format:
          $ref: '#/components/schemas/InstanceFormat'
        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.
        language:
          $ref: '#/components/schemas/SchemaLanguage'
        format:
          $ref: '#/components/schemas/SchemaFormat'
        created_by_id:
          type: string
          example: usr_123
          description: ID of the principal who created the config schema.
        documents:
          allOf:
            - $ref: '#/components/schemas/SchemaDocuments'
          description: >-
            Expand the config schema documents using `expand=documents` in the
            query string.
          example:
            - id: doc_123
              name: main.json
              data: |
                {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object"
                }
    ConfigSchemaGitCommitList:
      title: Config Schema Git Commit List
      allOf:
        - $ref: '#/components/schemas/PaginatedList'
        - type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/ConfigSchemaGitCommit'
              description: The list of config schema git commits.
    BaseConfigType:
      title: Config Type
      type: object
      required:
        - object
        - id
        - name
        - slug
        - created_at
        - updated_at
        - created_by_id
        - archived_at
        - archived_by_id
      properties:
        object:
          type: string
          enum:
            - config_type
          example: config_type
          x-stainless-const: true
          description: The object type, which is always `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.
        created_by_id:
          type: string
          example: usr_123
          description: ID of the principal who created the config type.
        archived_at:
          type: string
          format: date-time
          example: '2021-01-01T00:00:00Z'
          nullable: true
          description: >-
            Timestamp of when the config type was archived. Null if the config
            type is not archived.
        archived_by_id:
          type: string
          example: usr_123
          nullable: true
          description: >-
            ID of the principal who archived the config type. Null if the config
            type is not archived or was archived before this field was recorded.
    InstanceFormat:
      title: Instance Format
      type: string
      description: >
        The serialization format of stored content, such as a config instance or
        a calibration. A config instance is written to the device filesystem in
        this format.

        - `json`: standard JSON.

        - `yaml`: YAML 1.2.

        - `jsonc`: JSON with comments (JSON plus `//` and `/* */` comment
        syntax).

        - `xml`: XML.

        - `csv`: comma-separated values (RFC 4180).

        - `text`: plain, unstructured text with no specific format.
      enum:
        - json
        - yaml
        - jsonc
        - xml
        - csv
        - text
      x-enum-varnames:
        - INSTANCE_FORMAT_JSON
        - INSTANCE_FORMAT_YAML
        - INSTANCE_FORMAT_JSONC
        - INSTANCE_FORMAT_XML
        - INSTANCE_FORMAT_CSV
        - INSTANCE_FORMAT_TEXT
    InstanceSlot:
      title: Instance Slot
      type: object
      required:
        - key
        - name
        - filepath
        - required
      properties:
        key:
          type: string
          pattern: ^[a-z0-9][a-z0-9_-]*$
          maxLength: 128
          example: controller_2
          description: >-
            An immutable, code-friendly identifier for this slot, unique within
            the schema. Lowercase alphanumerics, underscores, and hyphens; must
            start with an alphanumeric; at most 128 characters.
        name:
          type: string
          example: Controller 2
          description: The human-readable name of this slot.
        filepath:
          type: string
          example: >-
            /var/local/forge/configuration/robot_drivers/controller_2/topic_list.yaml
          description: >-
            The absolute file system path where instances bound to this slot are
            written. Must be unique within the schema, and unique across every
            config schema in a release.
        required:
          type: boolean
          example: true
          description: >-
            Whether every deployment of a release containing this schema must
            include an instance for this slot. A deployment includes at most one
            config instance per slot.
        description:
          type: string
          example: Topic list for the second motor controller.
          description: An optional human-readable description of this slot.
      example:
        key: controller_2
        name: Controller 2
        filepath: >-
          /var/local/forge/configuration/robot_drivers/controller_2/topic_list.yaml
        required: true
        description: Topic list for the second motor controller.
    SchemaLanguage:
      title: Schema Language
      type: string
      example: jsonschema
      enum:
        - jsonschema
        - cue
        - opaque
      x-enum-varnames:
        - JSONSCHEMA
        - CUE
        - OPAQUE
    SchemaFormat:
      title: Schema Format
      type: string
      enum:
        - json
        - yaml
        - cue
      x-enum-varnames:
        - SCHEMA_FORMAT_JSON
        - SCHEMA_FORMAT_YAML
        - SCHEMA_FORMAT_CUE
    SchemaDocuments:
      type: array
      items:
        $ref: '#/components/schemas/SchemaDocument'
      example:
        - id: doc_123
          name: main.json
          data: |
            {
              "$schema": "https://json-schema.org/draft/2020-12/schema",
              "type": "object"
            }
    PaginatedList:
      title: Paginated List
      type: object
      required:
        - object
        - limit
        - offset
        - has_more
      properties:
        object:
          type: string
          enum:
            - list
          example: list
          x-stainless-const: true
          description: The object type, which is always `list`.
        total_count:
          type: integer
          format: int64
          description: >-
            The total number of items in the list. By default the total count is
            not returned. The total count must be expanded (using
            expand=total_count) to get the total number of items in the list.
        limit:
          type: integer
          description: >-
            The maximum number of items to return. A limit of 15 with an offset
            of 0 returns items 1-15.
          default: 10
          minimum: 1
          maximum: 100
        offset:
          type: integer
          description: >-
            The offset of the items to return. An offset of 10 with a limit of
            10 returns items 11-20.
          default: 0
          minimum: 0
        has_more:
          type: boolean
          description: >-
            True if there are more items in the list to return. False if there
            are no more items to return.
          example: false
    ConfigSchemaGitCommit:
      title: Config Schema Git Commit
      allOf:
        - $ref: '#/components/schemas/BaseConfigSchemaGitCommit'
        - type: object
          required:
            - created_by_id
          properties:
            created_by_id:
              type: string
              example: usr_123
              description: ID of the principal who created the config schema git commit.
      example:
        object: config_schema_git_commit
        id: cfg_sch_git_com_123
        file_paths:
          - path/to/config/schema/robot1.cue
          - path/to/config/schema/robot2.cue
        git_commit_id: git_commit_123
        config_schema_id: cfg_sch_123
        created_at: '2021-01-01T00:00:00Z'
        created_by_id: usr_123
    SchemaDocument:
      title: Schema Document
      type: object
      required:
        - id
        - name
        - data
      properties:
        id:
          type: string
          description: The unique identifier for this document.
          example: doc_123
        name:
          type: string
          description: The document filename.
          example: main.json
        data:
          type: string
          description: The raw document content.
      example:
        id: doc_123
        name: main.json
        data: |
          {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object"
          }
    BaseConfigSchemaGitCommit:
      title: Base Config Schema Git Commit
      type: object
      required:
        - object
        - id
        - file_paths
        - git_commit_id
        - config_schema_id
        - created_at
      properties:
        object:
          type: string
          enum:
            - config_schema_git_commit
          example: config_schema_git_commit
          x-stainless-const: true
          description: The object type, which is always `config_schema_git_commit`.
        id:
          type: string
          example: cfg_sch_git_com_123
          description: ID of the config schema git commit.
        file_paths:
          type: array
          description: >-
            The file paths of the config schema files relative to the git
            repository root. JSON Schema only supports a single file for a
            schema. CUE supports multiple files via
            [packages](https://cuelang.org/docs/references/spec/#packages).
          items:
            type: string
          example:
            - path/to/config/schema/robot1.cue
            - path/to/config/schema/robot2.cue
        git_commit_id:
          type: string
          example: git_commit_123
          description: ID of the associated git commit.
        config_schema_id:
          type: string
          example: cfg_sch_123
          description: ID of the associated config schema.
        created_at:
          type: string
          format: date-time
          example: '2021-01-01T00:00:00Z'
          description: Timestamp of when the config schema git commit was created.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: The API key to use for authentication.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.