Smartthings API - catalogs api v3

Developer Programs Support
1

I am new here and I am not sure if this is the right department, but I have a question. Do you know where I can find the API documentation? I have this URL: https://api.smartthings.com/catalogs/api/v3/categories

2
1 Like
3

@h0ckeysk8er Sorry, but I do not see information about catalogs api categories on this page.

4

The catalogue endpoints aren’t documented in the public API reference and I would imagine most users don’t know they are there. I do know they are there and I can see what they probably are, but what I don’t know is if they have any practical use for end users or developers as clearly they are closely associated with what we see in the client apps.

Anyone calling that endpoint will likely see a correlation with the categories of supported devices and so won’t be too surprised to know they can also look at:

https://api.smartthings.com/catalogs/api/v3/brands
and
https://api.smartthings.com/catalogs/api/v3/devicetypes?country=GB

You might find it particularly useful to filter the output with your country code to see what is available to you, unless you want to know what other countries get that you don’t.

Want to know the ‘featured brands’?

https://api.smartthings.com/catalogs/api/v3/featuredbrands?country=GB

Now you have the devices, surely there must be something for apps too? Oh yes.

https://api.smartthings.com/catalogs/api/v3/apps?visibility=public&country=GB&appType=automationApp

https://api.smartthings.com/catalogs/api/v3/apps?visibility=public&country=GB&appType=serviceApp

https://api.smartthings.com/catalogs/api/v3/apps?visibility=public&country=GB&appType=voiceApp

https://api.smartthings.com/catalogs/api/v3/apps?visibility=public&country=GB&appType=setupApp

The country code is essential if you want to know what your country gets, but you can leave it off to see what you are missing if you like. The visibility can be set to private too but I’ve never seen that populated.

You don’t need to use the appType filter but a setupApp is the app used to onboard a particular device and naturally there are hundreds of them. So the filtering is a good idea. In the UK there is only one automationApp (a stock app listed on the Routines page) and that is Smart lighting. In the US there are others.

Naturally you can list the ‘labs’ apps.

https://api.smartthings.com/catalogs/api/v3/labs?visibility=public&country=GB

Just to take a step backwards in case any of that was actually GB specific, you can use:

https://api.smartthings.com/catalogs/api/v3/appscatalog?country=GB
and
https://api.smartthings.com/catalogs/api/v3/devicescatalog?country=GB

In both cases you need the country code and you must also also send an Accept-Language header (Accept-Language: en-GB).

This is what you get:

{"country":"GB","language":"en-GB","categoriesUrl":"/catalogs/api/v3/categories","myAppsUrl":"/catalogs/api/v3/apps?visibility=private&country=GB","appsUrl":"/catalogs/api/v3/apps?visibility=public&country=GB"}

and

{"country":"GB","language":"en-GB","categoriesUrl":"/catalogs/api/v3/categories","myDeviceTypesUrl":"/catalogs/api/v3/devicetypes?country=GB&visibility=private","deviceTypesUrl":"/catalogs/api/v3/devicetypes?country=GB&visibility=public","myBrandsUrl":"/catalogs/api/v3/brands?visibility=private","brandsUrl":"/catalogs/api/v3/brands?visibility=public"}

There are some other things under /catalogs/api/v3 but I’ve not really delved into them.

5 Likes