> ## 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. # List > List devices. | Scope | Required | | -------------- | -------- | | `devices:read` | Yes | ## OpenAPI ````yaml /references/platform-api/2026-05-06.yaml get /devices openapi: 3.0.3 info: title: Miru Platform API description: The API between Miru and any external client version: 2026-05-06.rainier license: name: MIT url: https://opensource.org/licenses/MIT x-release-version: 2026-05-06.rainier-beta.3 x-git-commit: sha: 79734a65778aea4131f502774643d1d69a262542 url: >- https://github.com/mirurobotics/openapi/commit/79734a65778aea4131f502774643d1d69a262542 message: >- fix(release/stainless): publish stainless.yml asset for platform and device (#57) ## Summary The release workflow publishes a `stainless.yml` asset alongside each spec release for downstream Stainless SDK pipelines. It worked for `cli` and `frontend` audiences but silently skipped `platform` and `device`. **Root cause:** `STAINLESS_CONFIG` in `tools/release/stainless.py` pointed `device` and `platform` at a nested layout (`tools/stainless/{device,platform}/stainless.yml`) that never existed. The actual files have lived at the flat `tools/stainless/{device,platform}.yml` since commit `214bf44` (2026-03-04, "refactor(stainless): simplify config names to platform.yml and device.yml"). The mismatch was masked by `build_stainless_target` silently returning `None` when the source file was missing, so every platform and device release shipped without its `stainless.yml` asset. ## Changes 1. **Fix the two paths in `STAINLESS_CONFIG`** to point at the flat `tools/stainless/{platform,device}.yml` layout that exists on disk. 2. **Replace the silent `if not src.exists(): return None`** with `raise FileNotFoundError(...)` so a future mapped-but-missing config fails loudly. Audiences not in the dict (agent, mqtt, webhooks) still return `None` cleanly — that's the legitimate "no Stainless SDK for this audience" case. 3. **Add regression tests:** - `test_known_audiences_have_real_files_on_disk` — parametrized over `STAINLESS_CONFIG.items()`, asserts each path resolves to an existing file. This is the test that would have caught the original bug. - `test_missing_src_for_mapped_audience_raises` — replaces the old `test_missing_src_returns_none`, pins the new loud-error contract. - `test_unmapped_audience_returns_none_cleanly` — pins the preserved clean-skip behaviour for unmapped audiences. Two existing build-target tests in `tools/release/tests/test_release_build.py` were rewired to mock `build_stainless_target`; they had been silently riding on the old skip-on-missing-source behaviour and would have failed under the new contract. The functional integration is already covered by `test_build_target_calls_stainless`. No CI workflow edits, no file restructuring under `tools/stainless/`, no historical-tag backfilling. ## Test plan - [ ] Unit tests pass (`tools/release/tests/`) - [ ] Preflight passes - [ ] Manual `./build/build-release.sh --snapshot` validation produces `platform.stainless.yml` and `device.stainless.yml` under `build/dist/` --------- Co-authored-by: Claude Opus 4.7 (1M context) author: ben-miru branch: HEAD dirty: false x-build: built_at: '2026-05-06T22:31:02.715859+00:00' servers: - url: https://api.mirurobotics.com/beta description: Miru Platform API security: - ApiKeyAuth: [] paths: /devices: parameters: - $ref: '#/components/parameters/MiruVersion' get: tags: - Devices summary: List description: List devices. operationId: listDevices parameters: - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/device_order_bys' - $ref: '#/components/parameters/device_list_expansions' - $ref: '#/components/parameters/device_search_id' - $ref: '#/components/parameters/device_search_name' - $ref: '#/components/parameters/device_search_agent_version' - $ref: '#/components/parameters/device_search_current_release_id' responses: '200': description: Successfully listed the devices. content: application/json: schema: $ref: '#/components/schemas/DeviceList' x-codeSamples: - lang: Python source: |- import os from miru_platform_sdk import Miru client = Miru( api_key=os.environ.get("MIRU_API_KEY"), # This is the default and can be omitted ) device_list = client.devices.list() print(device_list) components: parameters: MiruVersion: name: Miru-Version in: header required: true schema: type: string example: 2026-05-06.rainier description: The API version the client was built against. offset: name: offset in: query required: false description: >- The offset of the items to return. An offset of 10 with a limit of 10 returns items 11-20. schema: type: integer default: 0 minimum: 0 example: 0 limit: name: limit in: query required: false description: >- The maximum number of items to return. A limit of 15 with an offset of 0 returns items 1-15. schema: type: integer default: 10 minimum: 1 maximum: 100 example: 10 device_order_bys: name: order_by in: query required: false style: form explode: false description: Sort order for the device results. schema: type: array items: $ref: '#/components/schemas/DeviceOrderBy' example: - created_at:desc device_list_expansions: name: expand in: query required: false description: Fields to expand on each device in the list. schema: type: array items: $ref: '#/components/schemas/DeviceListExpansion' example: - current_release device_search_id: name: id in: query required: false style: form explode: false description: The device IDs to filter by. schema: type: array items: type: string example: - dev_123 device_search_name: name: name in: query required: false style: form explode: false description: The device names to filter by. schema: type: array items: type: string example: - My Device device_search_agent_version: name: agent_version in: query required: false style: form explode: false description: The agent versions to filter by. schema: type: array items: type: string example: - v1.0.0 device_search_current_release_id: name: current_release_id in: query required: false style: form explode: false description: The release IDs to filter devices by their current release. schema: type: array items: type: string example: - rls_123 schemas: DeviceList: allOf: - $ref: '#/components/schemas/PaginatedList' - type: object required: - data properties: data: description: The list of devices. type: array items: $ref: '#/components/schemas/Device' DeviceOrderBy: type: string enum: - id:asc - id:desc - created_at:desc - created_at:asc x-enum-varnames: - DEVICE_ORDER_BY_ID_ASC - DEVICE_ORDER_BY_ID_DESC - DEVICE_ORDER_BY_CREATED_AT_DESC - DEVICE_ORDER_BY_CREATED_AT_ASC default: created_at:desc DeviceListExpansion: type: string enum: - total_count - current_deployment - current_release x-enum-varnames: - DEVICE_LIST_EXPAND_TOTAL_COUNT - DEVICE_LIST_EXPAND_CURRENT_DEPLOYMENT - DEVICE_LIST_EXPAND_CURRENT_RELEASE 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 Device: allOf: - $ref: '#/components/schemas/BaseDevice' - type: object properties: 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. 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' BaseDevice: title: Base Device type: object required: - object - id - name - status - agent_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. 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 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. Deployment: title: Deployment allOf: - $ref: '#/components/schemas/BaseDeployment' - type: object properties: 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. 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 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: /srv/miru/configs/v1/localization.json created_at: '2021-01-01T00:00:00Z' config_schema_id: cfg_sch_124 config_type_id: cfg_typ_124 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 created_at: '2024-01-01T00:00:00Z' updated_at: '2024-01-01T00:00:00Z' Release: title: Release allOf: - $ref: '#/components/schemas/BaseRelease' - type: object properties: 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 config_type_name: Motion Control instance_filepath: /srv/miru/configs/v1/motion-control.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 - object: config_schema id: cfg_sch_124 digest: sha256:1234567890 config_type_name: Localization instance_filepath: /srv/miru/configs/v1/localization.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 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' 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 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 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. ConfigInstance: title: Config Instance allOf: - $ref: '#/components/schemas/BaseConfigInstance' - type: object properties: 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 created_at: '2021-01-01T00:00:00Z' config_schema_id: cfg_sch_123 config_type_id: cfg_typ_123 BaseRelease: title: Base Release type: object required: - object - id - version - git_commit_id - 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. git_commit_id: type: string nullable: true example: git_commit_123 description: The ID of the git commit associated with this 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 properties: 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 config_type_name: Motion Control instance_filepath: /srv/miru/configs/v1/motion-control.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 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 BaseConfigInstance: title: Base Config Instance type: object required: - object - id - config_type_name - filepath - created_at - config_schema_id - config_type_id 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. 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' 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 updated_by_id: usr_123 InstanceContent: title: Instance Content type: object required: - format - data properties: format: $ref: '#/components/schemas/InstanceFormat' data: type: string description: The configuration values associated with the config instance. 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 } BaseConfigSchema: title: Base Config Schema type: object required: - object - id - digest - config_type_name - instance_filepath - created_at - updated_at - config_type_id - language - format 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. config_type_name: type: string example: Motion Control description: The name of the config type. instance_filepath: type: string description: >- The absolute file system path where config instances for this schema are written. example: /srv/miru/configs/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. language: $ref: '#/components/schemas/SchemaLanguage' format: $ref: '#/components/schemas/SchemaFormat' 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" } 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 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. InstanceFormat: title: Instance Format type: string enum: - json - yaml - jsonc x-enum-varnames: - INSTANCE_FORMAT_JSON - INSTANCE_FORMAT_YAML - INSTANCE_FORMAT_JSONC SchemaLanguage: title: Schema Language type: string example: jsonschema enum: - jsonschema - cue x-enum-varnames: - JSONSCHEMA - CUE 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" } 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" } securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: The API key to use for authentication. ````