Skip to main content
All list endpoints in the Miru API support filtering to help you retrieve specific resources. For example, when listing devices, you can filter by id, name, and other fields.

​
Single value filters

Each list endpoint supports its own set of filter names. To see the filters supported by a specific endpoint, look for the query parameters in the Query Parameters section containing filter by in their description. id is a common filter amongst all list endpoints. It allows you to filter by a resource’s unique identifier. For example, when listing devices, you can filter by the device id using id=<device-id> in the request URL. The following uses the id=dvc_123 filter to include only the device with the dvc_123 id: 
curl --request GET \
  --url 'https://configs.api.miruml.com/v1/devices?id=dvc_123' \
  --header 'X-API-Key: <api-key>'
Filtering by ID will return at most one resource, since IDs are unique. Other fields, like config instance activity status, can return multiple results.

​
Multi-value filters

To filter by multiple values, specify the filter values as a | separated list: <filter_name>=<value_1>|<value_2>|<value_3>. Thus, to filter devices by multiple ids, you can use the id filter with a | separated list of ids: id=dvc_123|dvc_456|dvc_789. 
curl --request GET \
  --url 'https://configs.api.miruml.com/v1/devices?id=dvc_123|dvc_456|dvc_789' \
  --header 'X-API-Key: <api-key>'

​
Combining filters

You can combine filters using &. All filters are combined with AND logic, so resources must match all criteria. The following request filters the device list to include only the devices with the IDs dvc_123 and dvc_456 and the name Robot A: id=dvc_123|dvc_456&name=Robot%20A. 
curl --request GET \
  --url 'https://configs.api.miruml.com/v1/devices?id=dvc_123|dvc_456&name=Robot%20A' \ 
  --header 'X-API-Key: <api-key>'

​
URL encoding

When using filters with special characters, ensure that you properly URL-encode the values. For example, spaces are URL encoded as %20. Browsers and client applications will automatically URL-encode the values for you, so you shouldn’t need to worry about it, but it’s good to know. The following request filters the device list to only include the device with the name My Device Name using the name=My%20Device%20Name filter. 
curl --request GET \
  --url 'https://configs.api.miruml.com/v1/devices?name=My%20Device%20Name' \
  --header 'X-API-Key: <api-key>'