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

# Report calibrations

This guide details how to report [calibrations](https://docs.mirurobotics.com/cfg-mgmt/concepts/calibrations.md) through the Miru Agent's [Device API](https://docs.mirurobotics.com/developers/device-api/overview.md).

## Overview

A **calibration** is a result a device reports to Miru after calibrating one of its [components](https://docs.mirurobotics.com/cfg-mgmt/concepts/components.md), such as the pose of a robot arm or the intrinsics of a RealSense D435.

Miru allows on-device applications to report calibrations using the [create calibration](https://docs.mirurobotics.com/references/device-api/latest/endpoints/calibrations/create.md) endpoint in the Device API.

When a calibration is reported, the agent saves it on the device and immediately returns a `200` response, regardless of whether the device is online or offline. Once a device is online, the agent uploads the calibration to Miru.

## Prerequisites

To follow this guide, you must have a device installed with a Miru Agent [v0.12.0](https://docs.mirurobotics.com/changelog/agent.md#v0-12-0) or later.

To provision a device, see the [Provision a device](https://docs.mirurobotics.com/provision-devices) guide.

## Components

A [component](https://docs.mirurobotics.com/cfg-mgmt/concepts/components.md) is a kind of hardware that devices report calibrations for, such as an arm, a camera, or a Robotiq 2F-85. A calibration names its component with a [slug](https://docs.mirurobotics.com/cfg-mgmt/concepts/components.md#param-slug), such as `kuka-arm`, `realsense-d435`, or `robotiq-2f-85`.

When a calibration is reported, Miru checks if its component exists and creates it if it doesn't.

### Roles

Oftentimes devices have multiple units of the same component, such as multiple arms.

Roles distinguish components that are identical except for their purpose in the overall system. For example, a device with two arms might distinguish them as `left` and `right`.

### Aspects

Separately, some components have multiple calibrations.

An [aspect](https://docs.mirurobotics.com/cfg-mgmt/concepts/components.md#param-aspects) distinguishes parts of a unit that are calibrated separately. For example, a camera might report both `intrinsics` and `extrinsics`. These calibrations belong to the same unit, but are used for different purposes within the unit itself.

Both aspects and roles are optional. A device with one arm, calibrated one way, reports only the component.

Each device keeps a separate history for a given component, role, and aspect. Miru creates a role or aspect the first time a calibration reports it.

## Send a calibration

Calibrations are sent to the Miru Agent via the [create calibration](https://docs.mirurobotics.com/references/device-api/latest/endpoints/calibrations/create.md) endpoint in the Device API.

We recommend using the official [Python Device SDK](https://pypi.org/project/miru-device-sdk/) to report calibrations. You can also generate your own client using the Device API's OpenAPI specification, located in the [Device API Changelog](https://docs.mirurobotics.com/changelog/device-api.md).

The following parameters are required.

### Required parameters

**component** `string` *required*

The [slug](https://docs.mirurobotics.com/cfg-mgmt/concepts/components.md#param-slug) of the calibrated component.

Example: `kuka-arm`

**content.format** `enum` *required*

The file format of `content.data`: `json`, `yaml`, `jsonc`, `xml` or `text`.

**content.data** `string` *required*

The calibration result, usually the full text of the calibration file. At most 1 MiB.

### File formatting

The Miru dashboard shows the `content.data` string exactly as it was uploaded. Pretty-print that string in the request, including indentation and line breaks, the way you want it to appear.

### Optional parameters

In addition to the required parameters, you can also set the following optional parameters:

**role** `string`

The slug of the unit's [role](https://docs.mirurobotics.com/cfg-mgmt/concepts/components.md#param-roles).

Example: `front-left`

**aspect** `string`

The slug of the calibrated [aspect](https://docs.mirurobotics.com/cfg-mgmt/concepts/components.md#param-aspects).

Example: `pose`

**serial\_number** `string`

The serial number of the calibrated unit. At most 255 characters.

Example: `SN-1234`

## Response

The agent saves the calibration on the device, then responds with `200 OK`, a new report ID and the time it received the calibration:

```json nocopy theme={null}
{
  "report_id": "0f8e7c2a-5b1d-4c3e-9a6f-2d4b8e1c7a90",
  "reported_at": "2026-03-10T12:00:00Z"
}
```

The agent responds the same way while the device is offline, and uploads the calibration once Miru is reachable. Miru records each report ID once, so the agent's own upload retries never record a calibration twice. Each request gets a new report ID, though, so don't resend one that got a `200`.

The agent holds up to 1,000 calibrations that haven't uploaded yet. When it's holding 1,000, it saves nothing and responds with `507 Insufficient Storage` and the error code `calibration_buffer_full`. Retry once the device is back online and the agent has uploaded some of them. A calibration that still hasn't uploaded 90 days after its `reported_at` is dropped.

## View calibrations

To view a device's calibrations, open the device and navigate to the **Calibrations** page on the left.


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