Presentations

Update a Capability Presentation

Changed on Dec 19, 2022

Update a Capability presentation. Note: This API functionality is in BETA

put/capabilities/{capabilityId}/{capabilityVersion}/presentation

Request

Base URL
https://api.smartthings.com/v1
Auth
OAuth 2
Implicithttps://auth-global.api.smartthings.com
Scopesw:customcapability
TypeScript
https://skmtc.dev/smartthings/apis/smartthings-api/docs/capabilities/:capabilityId/:capabilityVersion/presentation/put.ts
A function with typed inputs. Its response is checked against the schema.

Headers

X-ST-Organizationstring ^(?:([0-9a-fA-F]{32})|([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}))$

Organization id. If not provided, default user organization will be used.

Request body

Example request

{
  "dashboard": {
    "states": [
      {
        "label": "Motion: {{motion.value}}",
        "alternatives": [
          {
            "key": "detected",
            "value": "Detected",
            "type": "active"
          },
          {
            "key": "clear",
            "value": "None",
            "type": "inactive"
          }
        ]
      }
    ],
    "actions": [
      {
        "displayType": "switch",
        "switch": {
          "command": {
            "name": "setLock",
            "on": "locked",
            "off": "unlocked"
          },
          "state": {
            "value": "lock.value",
            "on": "locked",
            "off": "unlocked"
          }
        }
      }
    ],
    "panelItems": [
      {
        "label": "Volume",
        "displayType": "stepper",
        "stepper": {
          "command": {
            "name": "setVolume"
          },
          "state": {
            "value": "volume.value",
            "label": "{{volume.value}}"
          },
          "step": 1,
          "range": [
            0,
            100
          ],
          "supportedValues": "supportedVolumes.value",
          "availableSize": [
            "1x1",
            "2x1",
            "4x1"
          ]
        }
      }
    ]
  },
  "detailView": [
    {
      "label": "Front door",
      "toggleSwitch": {
        "command": {
          "name": "setLock",
          "on": "locked",
          "off": "unlocked"
        },
        "state": {
          "value": "lock.value",
          "on": "locked",
          "off": "unlocked"
        }
      },
      "standbyPowerSwitch": {
        "command": {
          "name": "setLock",
          "on": "locked",
          "off": "unlocked"
        },
        "state": {
          "value": "lock.value",
          "on": "locked",
          "off": "unlocked"
        }
      },
      "switch": {
        "command": {
          "name": "setLock",
          "on": "locked",
          "off": "unlocked"
        },
        "state": {
          "value": "lock.value",
          "on": "locked",
          "off": "unlocked"
        }
      },
      "slider": {
        "command": "setVolume",
        "value": "volume.value"
      },
      "pushButton": {
        "command": "setButton",
        "argument": "push"
      },
      "textButton": {
        "command": "setThermostatMode",
        "value": "switch.value",
        "buttons": [
          {
            "key": "cooling",
            "label": "Cooling",
            "state": "Cooling"
          }
        ],
        "supportedValues": "supportedThermostatModes.value"
      },
      "playPause": {
        "command": {
          "name": "setPlaybackState",
          "play": "play",
          "pause": "pause"
        },
        "state": {
          "value": "playbackState.value",
          "play": "playing",
          "pause": "paused",
          "alternatives": [
            {
              "key": "playing",
              "value": "Playing",
              "type": "active"
            },
            {
              "key": "paused",
              "value": "Paused",
              "type": "inactive"
            }
          ]
        }
      },
      "playStop": {
        "state": {
          "value": "playbackState.value",
          "play": "playing",
          "stop": "stopped",
          "alternatives": [
            {
              "key": "playing",
              "value": "Playing",
              "type": "active"
            },
            {
              "key": "stopped",
              "value": "Stopped",
              "type": "inactive"
            }
          ]
        }
      },
      "list": {
        "command": {
          "name": "setCleaningMode",
          "alternatives": [
            {
              "key": "spot",
              "value": "Spot cleaning mode"
            },
            {
              "key": "auto",
              "value": "Auto cleaning mode"
            }
          ]
        },
        "state": {
          "value": "cleaningMode.value",
          "alternatives": [
            {
              "key": "spot",
              "value": "Spot cleaning mode"
            },
            {
              "key": "auto",
              "value": "Auto cleaning mode"
            }
          ]
        }
      },
      "textField": {
        "command": "sendNotification",
        "value": "notification.value"
      },
      "numberField": {
        "value": "volume.value",
        "unit": "volume.unit",
        "command": "setVolume",
        "range": [
          0,
          100
        ],
        "supportedValues": "supportedVolumes.value"
      },
      "stepper": {
        "value": "volume.value"
      },
      "state": {
        "label": "{{temperatureMeasurement.value}}",
        "unit": "level.unit",
        "alternatives": [
          {
            "key": "on",
            "value": "Motion detected",
            "iconUrl": "icon://example_icon_url"
          }
        ]
      },
      "visibleCondition": {
        "value": "switch.value",
        "operator": "EQUALS",
        "operand": "on"
      }
    }
  ],
  "automation": {
    "conditions": [
      {
        "label": "Audio volume",
        "slider": {
          "value": "volume.value"
        },
        "list": {
          "value": "thermostatMode.value",
          "alternatives": [
            {
              "key": "spot",
              "value": "Spot cleaning mode",
              "iconUrl": "preload://ic_thermostatmode_spot"
            },
            {
              "key": "auto",
              "value": "Auto cleaning mode",
              "iconUrl": "preload://ic_thermostatmode_auto"
            }
          ],
          "multiSelectable": false
        },
        "dynamicList": {
          "value": "switch.value",
          "valueType": "string",
          "supportedValues": {
            "value": "supportedSwitchModes.value",
            "valueMap": {
              "key": "{{it.id}}",
              "value": "{{it.name}}"
            }
          },
          "alternatives": [
            {
              "key": "on",
              "value": "Motion detected",
              "iconUrl": "icon://example_icon_url"
            }
          ]
        },
        "numberField": {
          "value": "volume.value",
          "unit": "volume.unit",
          "range": [
            0,
            100
          ],
          "supportedValues": "supportedVolumes.value"
        },
        "textField": {
          "value": "notification.value"
        },
        "enumSlider": {
          "value": "dustHealthConcern.value",
          "alternatives": [
            {
              "key": "hazardous",
              "value": "Hazardous"
            },
            {
              "key": "veryUnhealthy",
              "value": "Very Unhealthy"
            },
            {
              "key": "unhealthy",
              "value": "Unhealthy"
            },
            {
              "key": "moderate",
              "value": "Moderate"
            },
            {
              "key": "good",
              "value": "Good"
            }
          ],
          "supportedOperators": [
            {
              "operator": "EQUALS",
              "label": "Equals to"
            },
            {
              "operator": "GREATER_THAN_OR_EQUALS",
              "label": "Greater than or equals to"
            }
          ]
        },
        "numberPicker": {
          "value": "volume.value",
          "unit": "volume.unit",
          "range": [
            0,
            100
          ],
          "supportedValues": "supportedVolumes.value"
        },
        "visibleCondition": {
          "value": "switch.value",
          "operator": "EQUALS",
          "operand": "on"
        }
      }
    ],
    "actions": [
      {
        "label": "Audio volume",
        "slider": {
          "command": "setTemperature"
        },
        "list": {
          "command": "setThermostatMode"
        },
        "dynamicList": {
          "command": "setSwitchMode",
          "argumentType": "string",
          "supportedValues": {
            "value": "supportedSwitchModes.value",
            "valueMap": {
              "key": "{{it.id}}",
              "value": "{{it.name}}"
            }
          },
          "alternatives": [
            {
              "key": "on",
              "value": "Motion detected",
              "iconUrl": "icon://example_icon_url"
            }
          ]
        },
        "textField": {
          "command": "sendNotification",
          "range": [
            0,
            20
          ]
        },
        "numberField": {
          "command": "setVolume",
          "unit": "volume.unit",
          "range": [
            0,
            100
          ],
          "supportedValues": "supportedVolumes.value"
        },
        "numberPicker": {
          "command": "setVolume",
          "unit": "volume.unit",
          "range": [
            0,
            100
          ],
          "supportedValues": "supportedVolumes.value"
        },
        "multiArgCommand": {
          "command": "playTrack",
          "arguments": [
            {
              "label": "Audio volume",
              "slider": {
                "name": "level",
                "range": [
                  0,
                  100
                ],
                "unit": "level.unit"
              },
              "list": {
                "name": "mode"
              },
              "textField": {
                "name": "uri",
                "range": [
                  5,
                  50
                ]
              },
              "numberField": {
                "name": "level",
                "unit": "level.unit",
                "range": [
                  0,
                  10
                ]
              }
            }
          ],
          "supportedValues": "supportedArguments.value"
        },
        "visibleCondition": {
          "value": "switch.value",
          "operator": "EQUALS",
          "operand": "on"
        }
      }
    ]
  },
  "presentationSettings": {
    "temperatureConversions": [
      {
        "value": "switch.value",
        "unit": "level.unit"
      }
    ]
  }
}

Response

The custom Capability presentation

idstring required

versioninteger required

The version number of the capability.

Example response

{
  "id": "audioVolume",
  "version": 1,
  "dashboard": {
    "states": [
      {
        "label": "Motion: {{motion.value}}",
        "alternatives": [
          {
            "key": "detected",
            "value": "Detected",
            "type": "active"
          },
          {
            "key": "clear",
            "value": "None",
            "type": "inactive"
          }
        ]
      }
    ],
    "actions": [
      {
        "displayType": "switch",
        "switch": {
          "command": {
            "name": "setLock",
            "on": "locked",
            "off": "unlocked"
          },
          "state": {
            "value": "lock.value",
            "on": "locked",
            "off": "unlocked"
          }
        }
      }
    ],
    "panelItems": [
      {
        "label": "Volume",
        "displayType": "stepper",
        "stepper": {
          "command": {
            "name": "setVolume"
          },
          "state": {
            "value": "volume.value",
            "label": "{{volume.value}}"
          },
          "step": 1,
          "range": [
            0,
            100
          ],
          "supportedValues": "supportedVolumes.value",
          "availableSize": [
            "1x1",
            "2x1",
            "4x1"
          ]
        }
      }
    ]
  },
  "detailView": [
    {
      "label": "Front door",
      "toggleSwitch": {
        "command": {
          "name": "setLock",
          "on": "locked",
          "off": "unlocked"
        },
        "state": {
          "value": "lock.value",
          "on": "locked",
          "off": "unlocked"
        }
      },
      "standbyPowerSwitch": {
        "command": {
          "name": "setLock",
          "on": "locked",
          "off": "unlocked"
        },
        "state": {
          "value": "lock.value",
          "on": "locked",
          "off": "unlocked"
        }
      },
      "switch": {
        "command": {
          "name": "setLock",
          "on": "locked",
          "off": "unlocked"
        },
        "state": {
          "value": "lock.value",
          "on": "locked",
          "off": "unlocked"
        }
      },
      "slider": {
        "command": "setVolume",
        "value": "volume.value"
      },
      "pushButton": {
        "command": "setButton",
        "argument": "push"
      },
      "textButton": {
        "command": "setThermostatMode",
        "value": "switch.value",
        "buttons": [
          {
            "key": "cooling",
            "label": "Cooling",
            "state": "Cooling"
          }
        ],
        "supportedValues": "supportedThermostatModes.value"
      },
      "playPause": {
        "command": {
          "name": "setPlaybackState",
          "play": "play",
          "pause": "pause"
        },
        "state": {
          "value": "playbackState.value",
          "play": "playing",
          "pause": "paused",
          "alternatives": [
            {
              "key": "playing",
              "value": "Playing",
              "type": "active"
            },
            {
              "key": "paused",
              "value": "Paused",
              "type": "inactive"
            }
          ]
        }
      },
      "playStop": {
        "state": {
          "value": "playbackState.value",
          "play": "playing",
          "stop": "stopped",
          "alternatives": [
            {
              "key": "playing",
              "value": "Playing",
              "type": "active"
            },
            {
              "key": "stopped",
              "value": "Stopped",
              "type": "inactive"
            }
          ]
        }
      },
      "list": {
        "command": {
          "name": "setCleaningMode",
          "alternatives": [
            {
              "key": "spot",
              "value": "Spot cleaning mode"
            },
            {
              "key": "auto",
              "value": "Auto cleaning mode"
            }
          ]
        },
        "state": {
          "value": "cleaningMode.value",
          "alternatives": [
            {
              "key": "spot",
              "value": "Spot cleaning mode"
            },
            {
              "key": "auto",
              "value": "Auto cleaning mode"
            }
          ]
        }
      },
      "textField": {
        "command": "sendNotification",
        "value": "notification.value"
      },
      "numberField": {
        "value": "volume.value",
        "unit": "volume.unit",
        "command": "setVolume",
        "range": [
          0,
          100
        ],
        "supportedValues": "supportedVolumes.value"
      },
      "stepper": {
        "value": "volume.value"
      },
      "state": {
        "label": "{{temperatureMeasurement.value}}",
        "unit": "level.unit",
        "alternatives": [
          {
            "key": "on",
            "value": "Motion detected",
            "iconUrl": "icon://example_icon_url"
          }
        ]
      },
      "visibleCondition": {
        "value": "switch.value",
        "operator": "EQUALS",
        "operand": "on"
      }
    }
  ],
  "automation": {
    "conditions": [
      {
        "label": "Audio volume",
        "slider": {
          "value": "volume.value"
        },
        "list": {
          "value": "thermostatMode.value",
          "alternatives": [
            {
              "key": "spot",
              "value": "Spot cleaning mode",
              "iconUrl": "preload://ic_thermostatmode_spot"
            },
            {
              "key": "auto",
              "value": "Auto cleaning mode",
              "iconUrl": "preload://ic_thermostatmode_auto"
            }
          ],
          "multiSelectable": false
        },
        "dynamicList": {
          "value": "switch.value",
          "valueType": "string",
          "supportedValues": {
            "value": "supportedSwitchModes.value",
            "valueMap": {
              "key": "{{it.id}}",
              "value": "{{it.name}}"
            }
          },
          "alternatives": [
            {
              "key": "on",
              "value": "Motion detected",
              "iconUrl": "icon://example_icon_url"
            }
          ]
        },
        "numberField": {
          "value": "volume.value",
          "unit": "volume.unit",
          "range": [
            0,
            100
          ],
          "supportedValues": "supportedVolumes.value"
        },
        "textField": {
          "value": "notification.value"
        },
        "enumSlider": {
          "value": "dustHealthConcern.value",
          "alternatives": [
            {
              "key": "hazardous",
              "value": "Hazardous"
            },
            {
              "key": "veryUnhealthy",
              "value": "Very Unhealthy"
            },
            {
              "key": "unhealthy",
              "value": "Unhealthy"
            },
            {
              "key": "moderate",
              "value": "Moderate"
            },
            {
              "key": "good",
              "value": "Good"
            }
          ],
          "supportedOperators": [
            {
              "operator": "EQUALS",
              "label": "Equals to"
            },
            {
              "operator": "GREATER_THAN_OR_EQUALS",
              "label": "Greater than or equals to"
            }
          ]
        },
        "numberPicker": {
          "value": "volume.value",
          "unit": "volume.unit",
          "range": [
            0,
            100
          ],
          "supportedValues": "supportedVolumes.value"
        },
        "visibleCondition": {
          "value": "switch.value",
          "operator": "EQUALS",
          "operand": "on"
        }
      }
    ],
    "actions": [
      {
        "label": "Audio volume",
        "slider": {
          "command": "setTemperature"
        },
        "list": {
          "command": "setThermostatMode"
        },
        "dynamicList": {
          "command": "setSwitchMode",
          "argumentType": "string",
          "supportedValues": {
            "value": "supportedSwitchModes.value",
            "valueMap": {
              "key": "{{it.id}}",
              "value": "{{it.name}}"
            }
          },
          "alternatives": [
            {
              "key": "on",
              "value": "Motion detected",
              "iconUrl": "icon://example_icon_url"
            }
          ]
        },
        "textField": {
          "command": "sendNotification",
          "range": [
            0,
            20
          ]
        },
        "numberField": {
          "command": "setVolume",
          "unit": "volume.unit",
          "range": [
            0,
            100
          ],
          "supportedValues": "supportedVolumes.value"
        },
        "numberPicker": {
          "command": "setVolume",
          "unit": "volume.unit",
          "range": [
            0,
            100
          ],
          "supportedValues": "supportedVolumes.value"
        },
        "multiArgCommand": {
          "command": "playTrack",
          "arguments": [
            {
              "label": "Audio volume",
              "slider": {
                "name": "level",
                "range": [
                  0,
                  100
                ],
                "unit": "level.unit"
              },
              "list": {
                "name": "mode"
              },
              "textField": {
                "name": "uri",
                "range": [
                  5,
                  50
                ]
              },
              "numberField": {
                "name": "level",
                "unit": "level.unit",
                "range": [
                  0,
                  10
                ]
              }
            }
          ],
          "supportedValues": "supportedArguments.value"
        },
        "visibleCondition": {
          "value": "switch.value",
          "operator": "EQUALS",
          "operand": "on"
        }
      }
    ]
  },
  "presentationSettings": {
    "temperatureConversions": [
      {
        "value": "switch.value",
        "unit": "level.unit"
      }
    ]
  }
}

Changes

Dec 19, 2022adcacfc2749d Revision changes
- info
  added the new optional header request parameter X-ST-Organization

Operation history