Skip to main content
The Device API adheres to semantic versioning, which was chosen so that on-device applications can easily determine API version compatibility. The Device API is currently in beta, signified by the v0 prefix. There is no established release cadence for the Device API—features are simply released as soon as they are ready.

​
URL format

The Device API is served from the unix socket at /run/miru/miru.sock with the URL format http://localhost/{version}/, where {version} is the breaking change alias for the API version. Beta releases use breaking change aliases that include the major and minor version numbers (e.g. v0.2, v0.3, etc.). Stable releases use breaking change aliases that include the major version number only (e.g. v1, v2, etc.). Miru uses stable URL version aliases so clients can target a compatibility track. Targeting a fully specified version (e.g. v0.1.0) is not supported.
Semver release lineBreaking change aliasURL format
v0.1.xv1 (legacy)http://localhost/v1/
v0.2.xv0.2http://localhost/v0.2/
v0.3.xv0.3http://localhost/v0.3/
v1.y.xv1http://localhost/v1/
For historical reasons, API version v0.1.0 uses the breaking change alias of v1 instead of v0.1. API version v0.1.0 will be retired before the v1 release to prevent compatibility issues.

​
Agent compatibility matrix

Each Miru Agent is compiled with a set of one or more API versions, which is documented in the following table:
Agent VersionAPI Version(s)
v0.7.xv0.2.0
v0.6.xv0.1.0
v0.5.xv0.1.0
Be careful when updating your client application to a new API version. Even if API changes are backward-compatible, if the agent is not compiled with the new features, your client may not work as expected. As rule of thumb, use the API version of the oldest agent version that is deployed to your fleet in your client application. This ensures that the agent was compiled with all the features of the API version you are using.

​
Supported versions

The Device API does not have its own support policy—its support is inherited from the Miru Agent. If a supported Miru Agent uses an API version, that API version is supported. You can find the supported Miru Agent versions on the Agent Versions page. Below is a list of the currently supported versions:
API VersionReleasedStatus
2026-03-13
2025-09-21

​
Changelog and migrations

For a history of changes and migration steps for the Device API, visit the changelog below.

​
OpenAPI specifications

The Device API is defined using the OpenAPI 3.0 specification. Each version of the spec is available for download as a YAML file from the Device API changelog. Use the specs to generate client code, validate requests, or import into tools like Postman and Swagger UI.

​
Stability guarantees

During beta (v0.x.y)
  • Minor version bumps (e.g. v0.1.0 to v0.2.0) may include breaking changes
  • Patch version bumps (e.g. v0.2.0 to v0.2.1) are always backward-compatible
After stable (v1.0+)
  • Major version bumps (e.g. v1.x to v2.0) may include breaking changes
  • Minor version bumps (e.g. v1.0 to v1.1) are additive only—no breaking changes

​
Breaking changes

The following changes are considered breaking:
  • Removing an endpoint
  • Removing or renaming a response field
  • Changing the type of a response field
  • Adding a new required request parameter
  • Removing or renaming an enum value
  • Changing authentication requirements
  • Changing the structure of error responses

​
Non-breaking changes

The following changes are considered non-breaking:
  • Adding a new endpoint
  • Adding a new optional request parameter
  • Adding a new field to a response
  • Adding a new enum value
  • Adding a new optional header
  • Improving error messages without changing their structure
Last modified on March 15, 2026