---
title: "Update a Capability"
method: PUT
path: "/capabilities/{capabilityId}/{capabilityVersion}"
tags: ["Capabilities"]
---

# Update a Capability

`PUT /capabilities/{capabilityId}/{capabilityVersion}`

## Request

- Base URL: `https://api.smartthings.com/v1`
- URL: `https://api.smartthings.com/v1/capabilities/{capabilityId}/{capabilityVersion}`
- Auth: OAuth 2
  - Implicit: `https://auth-global.api.smartthings.com`
  - Scopes: `w:customcapability`
- TypeScript: <https://skmtc.dev/smartthings/apis/smartthings-api/docs/capabilities/:capabilityId/:capabilityVersion/put.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Headers

- `X-ST-Organization` string, ^(?:([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}))$

## Request body

- UpdateCapabilityRequest
  - `attributes` object: A mapping of attribute names to their definitions. All attribute names are lower camelcase.
  - `commands` object: A mapping of command names to their definitions. All command names are lower camelcase.

## Response `200`

The custom Capability

- Capability
  - `id` string, required: A URL safe unique identifier for the capability.
  - `version` integer, 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.
  - `name` string, required: An alphanumeric English language name for the capability.
  - `ephemeral` boolean
  - `attributes` object: A mapping of attribute names to their definitions. All attribute names are lower camelcase.
  - `commands` object: A mapping of command names to their definitions. All command names are lower camelcase.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `409`: Conflict
- `415`: Unsupported Media Type
- `422`: Unprocessable Entity
- `429`: Too many requests
- `default`: Unexpected error

## Changes

- **2022-12-19** `adcacfc2749d`: 1 info
  - added the new optional `header` request parameter `X-ST-Organization`

[Operation history](https://skmtc.dev/smartthings/apis/smartthings-api/changes/capabilities/:capabilityId/:capabilityVersion/put.md)

---

[API](https://skmtc.dev/smartthings/apis/smartthings-api.md) - [All operations](https://skmtc.dev/smartthings/apis/smartthings-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smartthings/apis/smartthings-api/revisions/2788a4236800?raw)