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.
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:Agent compatibility matrix
Each Miru Agent is compiled with a set of one or more API versions, which is documented in the following table:
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.
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.0tov0.2.0) may include breaking changes - Patch version bumps (e.g.
v0.2.0tov0.2.1) are always backward-compatible
v1.0+)
- Major version bumps (e.g.
v1.xtov2.0) may include breaking changes - Minor version bumps (e.g.
v1.0tov1.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