SMsmartthings
Capabilities

Update a Capability

Changed on

Update a Capability.

Capabilities with a proposed status can be updated at will.

Capabilities with a live, deprecated, or dead status are immutable and can't be updated.

Capability names cannot be changed.

put/capabilities/{capabilityId}/{capabilityVersion}

Request

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

attributesobject

A mapping of attribute names to their definitions. All attribute names are lower camelcase.

commandsobject

A mapping of command names to their definitions. All command names are lower camelcase.

Example request

{
  "attributes": {
    "colorTemperature": {
      "schema": {
        "type": "object",
        "properties": {
          "value": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30000
          },
          "unit": {
            "type": "string",
            "enum": [
              "K"
            ],
            "default": "K"
          }
        },
        "additionalProperties": false
      },
      "required": [
        "value"
      ]
    }
  },
  "commands": {
    "setColorTemperature": {
      "arguments": [
        {
          "name": "temperature",
          "optional": false,
          "schema": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30000
          }
        }
      ]
    }
  }
}

Response

The custom Capability

idstring required

A URL safe unique identifier for the capability.

versioninteger required

The version number of the capability.

status'proposed' | 'live' | 'deprecated' | 'dead' required

The status of the capability.

  • proposed - The capability is currently under development / in review. The capability definition may go through changes, some of which may currently not function properly.
  • live - The capability has been through review and the definition has been codified. Once a definition transitions from proposed to live, it cannot be altered.
  • deprecated - The capability is marked for removal in future versions. It should only be used during a short period of time to allow for existing integrations and automations to continue to work while the transition to a newer definition is made.
  • dead - A previously deprecated definition is now ready for removal. Usage of the deprecated definition had dropped to a sufficiently low enough level to warrant removal. The dead definition still exists but it can no longer be used or implemented by devices.
namestring required

An alphanumeric English language name for the capability.

ephemeralboolean
attributesobject

A mapping of attribute names to their definitions. All attribute names are lower camelcase.

commandsobject

A mapping of command names to their definitions. All command names are lower camelcase.

Example response

{
  "id": "namespace.colorTemperature",
  "version": 1,
  "name": "Color Temperature",
  "ephemeral": true,
  "attributes": {
    "colorTemperature": {
      "schema": {
        "type": "object",
        "properties": {
          "value": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30000
          },
          "unit": {
            "type": "string",
            "enum": [
              "K"
            ],
            "default": "K"
          },
          "required": [
            "value"
          ]
        }
      }
    }
  },
  "commands": {
    "setColorTemperature": {
      "arguments": [
        {
          "name": "temperature",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30000
          }
        }
      ]
    }
  }
}

Changes