Skip to main content
GET
Search device catalog

Authorizations

Authorization
string
header
required

Your Leap API key as a Bearer token. Send it in the Authorization header: Authorization: Bearer <api-key>.

Query Parameters

q
string

Free-text query over manufacturer, model name and model number. Omit it to browse rather than search.

Minimum string length: 1
category
string

Device category, addressed by its stable name (case-insensitive): hvac, ev_charger, solar_storage, water_heater, smart_thermostat, weatherization, vehicle, meter, panel_make_ready, solar_panel. Address a category by name: the category's own id is specific to one Leap environment and is not accepted here. An unknown name is a 400 naming the categories that exist.

subcategory
string

Exact (case-insensitive) match on the device's subcategory. The stored vocabulary is uncontrolled today, so treat this as a filter on values you have already seen in subcategory on a response, not as an enum.

ids
string[]

Resolves specific catalog devices by id: a comma-separated list of catalog device UUIDs, at most 100 per request. Combines with the other filters by AND, so ids plus category returns only the named devices that also sit in that category.

Intended for resolving already-attached customer devices, where the caller holds device UUIDs and needs the full catalog record for each one. An id that matches no device currently in the catalog is simply absent from the results rather than an error, so match the responses back to the ids you asked for. A malformed UUID, an empty value, or more than 100 ids is a 400.

Maximum array length: 100
Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
page_size
integer

Rows per page, 1 to 500. Defaults to limit when only limit is given, else to 20. Cannot be combined with limit.

Required range: 1 <= x <= 500
page_token
string

Opaque cursor from a previous response's next_page_token. Only valid when replayed with the same q, category and subcategory; replaying it against different filters is a 400. Cannot be combined with offset.

limit
integer
default:20

Legacy alias for page_size, kept so existing callers keep working. The ceiling was raised from 50 to 500.

Required range: 1 <= x <= 500
offset
integer
default:0

Legacy row offset, kept so existing callers keep working. Prefer page_token.

Required range: x >= 0

Response

Ranked page of matching devices.

results
object[]
required
next_offset
integer | null

Offset for the next page, or null when this is the last page. Kept for callers still paging with limit + offset.

next_page_token
string | null

Cursor for the next page, or null when this is the last page. Pass it back as page_token. Present alongside next_offset whichever paging style the request used, so a caller can switch.