smartthings-catalog-api

name	smartthings-catalog-api
description	Query Samsung SmartThings compatible devices catalog via GraphQL API — fetch all categories, super categories, brands, and products for China and global regions.
version	1.0.0
author	hermes-agent
license	Apache-2.0
metadata	{"hermes":{"tags":["Smart-Home","SmartThings","Catalog","GraphQL","Samsung","API","China-Region"]}}
prerequisites	{"commands":["curl"]}

SmartThings Catalog API

Query the Samsung SmartThings compatible devices catalog directly via GraphQL, without needing a browser. Works for both China and global regions.

Discovery Method

The SmartThings compatible devices page (e.g. samsung.com.cn/smartthings/compatible-devices/) uses an embedded React frontend that calls a GraphQL API. The API endpoints are hardcoded in the page JavaScript.

China region endpoint:

https://api.samsungiotcloud.cn/catalogs/api/v3/malls/graphql

Global region endpoint:

https://api.smartthings.com/catalogs/api/v3/malls/graphql

GraphQL Queries

1. Get All Super Categories

{
  "query": "query { allSuperCategories { totalCount superCategories { id name localizations { locale displayName } childCategoryIds } } }"
}

2. Get All Categories (paginated)

{
  "query": "query allCategories { allCategories(pageNumber: 0, pageSize: 100) { totalCount pageInfo { hasNextPage hasPreviousPage currentPage totalPages } categories { id uuid name iconUrl localizations { locale displayName } dossierCategoryNames superCategoryIds } } }"
}

Pagination: use pageNumber: 1, pageSize: 100 for page 2, etc. Check pageInfo.hasNextPage.

3. Get All Brands (paginated)

{
  "query": "query allBrands { allBrands(pageNumber: 0, pageSize: 100) { totalCount brands { id name } } }"
}

4. Get Brands for Specific Categories

{
  "query": "query allBrands($categoryFilter: CategoryFilter) { allBrands(pageNumber: 0, pageSize: 100, filter: $categoryFilter) { totalCount brands { id name } } }",
  "variables": {
    "categoryFilter": {
      "filterByProductCatalog": {
        "categoryIds": [31, 36, 38]
      }
    }
  }
}

5. Search Products

⚠️ IMPORTANT (Verified 2026-04-21): The API schema has changed. The following filters are INVALID and will cause validation errors:

• filterByProductCatalog (not a valid field on ProductCatalogFilter)
• searchBy argument (removed from allProductCatalogs)

Working basic query:

{
  "query": "query { allProductCatalogs(pageNumber: 0, pageSize: 20) { totalCount productCatalogs { id modelName modelCode } } }"
}

To find specific products (e.g., Samsung refrigerators), you must scan all products and filter client-side:

{
  "query": "query { allProductCatalogs(pageNumber: 0, pageSize: 50) { totalCount productCatalogs { id modelName modelCode localizations { locale shopDisplayName } } } }"
}

Total catalog has ~2483 products. Use pagination (pageNumber, pageSize) and filter results by modelName patterns (e.g., RF* for refrigerators, WW* for washers).

Alternative: Use categories first, then correlate: Get category ID 36 (冰箱), then scan products looking for models matching Samsung fridge patterns.

Shell Usage

# Fetch all categories (China)
curl -s -X POST "https://api.samsungiotcloud.cn/catalogs/api/v3/malls/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query":"query allCategories { allCategories(pageNumber: 0, pageSize: 100) { totalCount categories { id uuid name localizations { locale displayName } superCategoryIds } } }"}' | jq .

# Fetch all brands (China)
curl -s -X POST "https://api.samsungiotcloud.cn/catalogs/api/v3/malls/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query":"query allBrands { allBrands(pageNumber: 0, pageSize: 100) { totalCount brands { id name } } }"}' | jq .

# Fetch super categories
curl -s -X POST "https://api.samsungiotcloud.cn/catalogs/api/v3/malls/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { allSuperCategories { totalCount superCategories { id name localizations { locale displayName } childCategoryIds } } }"}' | jq .

# Fetch product catalog (basic, no filter support verified)
curl -s -X POST "https://api.samsungiotcloud.cn/catalogs/api/v3/malls/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ allProductCatalogs(pageNumber: 0, pageSize: 20) { totalCount productCatalogs { id modelName modelCode } } }"}' | jq .

## 14 Super Categories (China Region)

| ID | Name (CN) | Key Sub-Category IDs |
|----|-----------|---------------------|
| 1 | 家用电器 | 31(洗衣机), 44(烘干机), 48(扫地机器人), 32(AirDresser) |
| 2 | 智能网关与连接 | 4(WLAN/集线器), 66(桥接器), 85(中继器) |
| 3 | 套件 | 37(ADT安全装置) |
| 4 | 厨房电器 | 36(冰箱), 7(洗碗机), 83(微波炉), 17(烤箱), 72(咖啡机) |
| 5 | 生活方式与其他 | 64(宠物喂食器), 110(猫砂盆), 73(EV充电器), 3(车库门) |
| 6 | 照明与能源 | (空壳大类) |
| 7 | 个人设备 | 92(手表), 111(智能戒指), 78(耳机) |
| 8 | 传感器与安全 | 34(门锁), 25(摄像头), 39(动作感应器), 124(温湿度传感器) |
| 9 | 电视与娱乐 | 41(电视), 57(投影机), 29(扬声器) |
| 10 | 用电 | 23(能耗监视), 26(恒温器), 52(插座) |
| 11 | 照明和开关 | 49(照明), 20(开关/调光器), 71(吊灯) |
| 12 | 空气护理设备 | 38(空调), 43(空气净化器), 18(加湿器), 75(抽湿机) |
| 13 | 可穿戴设备 | 92(手表), 111(智能戒指) |
| 14 | 健身与健康 | 107(体重秤), 61(健身垫) |

**Totals: 14 super categories, 140+ sub-categories, 52 brands**

## Category IDs Reference (China Region)

| Category Name | ID | Super Category |
|--------------|----|---------------|
| 冰箱 | 36 | 厨房电器(4) |
| 洗衣机 | 31 | 家用电器(1) |
| 空调 | 38 | 空气护理设备(12) |
| 电视 | 41 | 电视与娱乐(9) |
| 扫地机器人 | 48 | 家用电器(1) |
| 门锁 | 34 | 传感器与安全(8) |
| 空气净化器 | 43 | 空气护理设备(12) |
| 加湿器 | 18 | 空气护理设备(12) |
| 照明 | 49 | 照明和开关(11) |
| 开关/调光器 | 20 | 照明和开关(11) |
| 温湿度传感器 | 124 | (none) |
| 宠物喂食器 | 64 | 生活方式与其他(5) |
| EV充电器 | 73 | 生活方式与其他(5) |



| Brand | ID |
|-------|----|
| Samsung | 15 |
| Aqara | 22 |
| Yeelight | 24 |
| Philips Hue | 32 |
| Nanoleaf | 33 |
| Aeotec | 16 |
| ORVIBO | 1 |
| PETKIT | 30 |
| EZVIZ(萤石) | 48 |



1. **SSL verification**: The China API may have certificate issues  some environments. Use `ssl.CERT_NONE` or `curl -k`  needed.

2. **Browser not needed**: Playwright/browser automation will fail on Samsung pages due to complex React rendering and lazy loading. The GraphQL API is much faster and more reliable.

3. **Localization**: Category/brand names come  multiple locales. The Chinese display name is typically  the `localizations` array  `locale` starts with `` or ``. Fall back to the `name` field  no Chinese localization exists.

4. **Product filtering NOT supported**: As of 2026-04-21, `allProductCatalogs` does NOT accept `filter` or `searchBy` arguments. The `filterByProductCatalog` input  either doesndata{:}

Related Skills

• smartthings-cli — CLI tool for managing SmartThings devices
• appliance-fault-diagnosis — Diagnose appliance faults from local knowledge base