Rename a label value

PATCH

/api/v1/groups/labels/{key}/values/{value}

curl --request PATCH \
  --url http://localhost:3000/api/v1/groups/labels/site/values/Plant-A \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "newValue": "Plant-1" }'

• Development
• Production

Renames one value of a label key (for example site=Plant-A to site=Plant-1) on every device of the organization in one transaction, rewriting the deployment selectors and alert rules that select it. Renaming onto a value already in use fails with 409.

Authorizations

• api-key
• bearer

Parameters

Path Parameters

value

required

string

Example

Plant-A

The value to rename

key

required

string

Example

site

The label key

Header Parameters

x-organization-id

string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Request Body^required

Media typeapplication/json

object

newValue

required

The new value for the label key. Must not already be carried under that key by any device of the organization, nor selected by any deployment selector or alert rule (409 otherwise).

string

>= 1 characters <= 253 characters

Example

Plant-1

Responses

200

Label value renamed

Media typeapplication/json

object

key

required

The label key that was renamed, or whose value was renamed

string

newKey

Key rename only: the new label key

string

value

Value rename only: the old value

string

newValue

Value rename only: the new value

string

affectedDevices

required

Number of devices whose labels were rewritten

number

updatedDeploymentIds

required

Deployments whose device selector referenced the renamed label and was rewritten to keep targeting the same devices

Array<string>

updatedAlertRuleIds

required

Alert rules whose label target referenced the renamed label and was rewritten to keep matching the same devices

Array<string>

Example

{
  "newKey": "site",
  "value": "Plant-A",
  "newValue": "Plant-1",
  "affectedDevices": 42
}

400

Invalid key, value or new value

401

Unauthorized

403

Forbidden — caller lacks required permission

404

No device in the organization carries the label

409

The new value is already in use