Rename a label key

PATCH

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

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

• Development
• Production

Renames a label key on every device of the organization in one transaction. Deployment selectors and alert rules that reference the key are rewritten in the same transaction, so they keep targeting the same devices. Renaming onto a key that devices already carry, or that a selector or alert rule already references, fails with 409 and changes nothing.

Authorizations

• api-key
• bearer

Parameters

Path Parameters

key

required

string

Example

plant

The label key to rename

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

newKey

required

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

string

>= 1 characters <= 253 characters

Example

site

Responses

200

Label key 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 or new key

401

Unauthorized

403

Forbidden — caller lacks required permission

404

No device in the organization carries the key

409

The new key is already in use