SMsmartthings
Capabilities

Create a Capability

Changed on

Create a Capability.

post/capabilities

Request

Query parameters

namespacestring

The namespace of the Capability

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

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. Required if no commands are specified.

commandsobject

A mapping of command names to their definitions. All command names are lower camelcase. Required if no attributes are specified.

Example request

{
  "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"
          }
        },
        "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