Skip to main content

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.

The Miru API uses expansions to retrieve related objects in a single request rather than making multiple API calls. This simplifies code and minimizes the number of API calls. Response objects only include the core fields by default. Related objects (such as the device associated with a deployment) are included with their IDs, but not their complete object data. Using the expand query parameter, you can include related objects directly in the response. Expansions are powerful but add latency. As such, they should be used strategically to balance performance with the data needed in an individual request.

​
Object expansions

Many response objects reference objects that are not included in the default response. For example, a has the following default response structure: 
{
  "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"
}
The device, release, and config_instances objects are not included in the deployment response by default. To retrieve the device for a given deployment, you could make two separate requests:
  • First, fetch the using its ID (assuming you already know it).
  • Then, having obtained the device_id from the deployment response, fetch the using the device ID.
This is workable but adds both latency and complexity to your code. A better approach is to use the expand parameter to include the device object directly in the deployment response, avoiding a second request. The following request expands the device field using expand=device 
curl --request GET \
  --url https://api.mirurobotics.com/beta/deployments/dpl_123?expand=device \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-03-09.tetons'
With the expansion, the response includes the device that the deployment targets, reducing the request count from two to one. To see a complete list of expandable fields for an object, look for the expand parameter in the Query Parameters section of the API endpoint you are querying.

​
Multiple expansions

You can expand multiple fields by passing in multiple expand parameters separated by & . The following request expands both the device and release fields of the deployment using expand=device&expand=release. 
curl --request GET \
  --url https://api.mirurobotics.com/beta/deployments/dpl_123?expand=device&expand=release \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-03-09.tetons'

​
Nested expansions

When expanding an object, it’s often the case that the expanded object contains objects that can also be expanded. For example, deployments can expand their release, which in turn can expand its config schemas. To expand nested objects, use the dot (.) notation within the expand parameter. The following request expands the config_schemas inside the release of the deployment using expand=release.config_schemas 
curl --request GET \
  --url https://api.mirurobotics.com/beta/deployments/dpl_123?expand=release.config_schemas \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-03-09.tetons'
Expansions cannot be nested beyond four levels deep. expand=field1.field2.field3.field4 is the maximum depth.
When expanding nested fields, there’s no need to expand the parent field. Since the release must be expanded to expand its config schemas in the expand=release.config_schemas query parameter, the release field is automatically expanded as well.

​
List expansions

​
Items

When listing deployments, you can expand fields in the same way you would for a single deployment. By default, returns the following response structure. 
{
  "object": "list",
  "limit": 10,
  "offset": 0,
  "has_more": true,
  "data": [
    {
      "object": "deployment",
      "id": "dpl_123",
      ...
    },
    {
      "object": "deployment",
      "id": "dpl_456",
      ...
    },
    ...
  ]
}
To expand the device field for every deployment in a list response, use expand=device, just as you would for a single object. Unlike other APIs you may encounter, you don’t need to prefix the field with data. (e.g., expand=data.device). Miru automatically applies the expansion to each item in the list, not the list itself. The following request expands the device field for every deployment in the list using expand=device 
curl --request GET \
  --url 'https://api.mirurobotics.com/beta/deployments?expand=device' \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-03-09.tetons'

​
Total count

The total_count field in a list response represents the total number of items matching the query. Because Miru paginates list responses, this number is often greater than the number of items returned per page. If a list query matches 100 items but the limit parameter is set to 10, the list response would contain only 10 items despite the total count being 100. By default, Miru does not compute total_count to avoid performance overhead. Instead, the field is omitted from the response unless explicitly expanded. To include the actual total count in the response, add expand=total_count to the request: 
curl --request GET \
  --url 'https://api.mirurobotics.com/beta/deployments?expand=total_count' \
  --header 'X-API-Key: <api-key>' \
  --header 'Miru-Version: 2026-03-09.tetons'
Computing the total count can add significant latency, especially for large datasets. Only use it when necessary!
Last modified on April 23, 2026