Documentation

Pagination & Filtering

All endpoints that return collections of items support pagination, and most also support filtering.

Pagination

The API supports pagination for endpoints returning collections by supplying limit and offset query parameters.

Code
curl -X GET "https://api.securithings.com/v1/devices?limit=10&offset=0" \
     -H "Authorization: Bearer <token>"

By default, if no limit and offset are provided, the API will return the first 100 items.

Every collection response includes a total field with the number of items matching the request. Increase offset by the value of limit until total items have been retrieved.

Filtering

Filters are query parameters that restrict a collection to the items matching the specified criteria. Filtering is applied server-side, so filter in the request rather than retrieving the full collection and filtering client-side.

Code
curl -X GET "https://api.securithings.com/v1/devices?status=offline" \
     -H "Authorization: Bearer <token>"

Each endpoint supports its own set of filters. They are listed under Query Parameters for that endpoint in the API Reference, together with their accepted values.

Combining filters

Multiple filters can be combined in a single request. An item is returned only if it matches all of them.

Code
curl -X GET "https://api.securithings.com/v1/devices?status=offline&isFirmwareVulnerable=1&lifeCycleStatus=eos" \
     -H "Authorization: Bearer <token>"

This query returns all offline devices that are End of Support (EOS) and have known firmware vulnerabilities.

Filters combine with pagination, so total reflects the filtered result set rather than the whole collection.

Requests & Responses Errors