Remove a deployment from devices or a device group

POST

/api/v1/deployments/{id}/targets/remove

curl --request POST \
  --url http://localhost:3000/api/v1/deployments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/targets/remove \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "deviceIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "group": { "labelKey": "site", "labelValue": "berlin" } }'

• Development
• Production

Removes the deployment from the given devices (or from every current target in one label group) while it stays live on the others. The group is resolved once, at request time; devices that join it later are unaffected. A removed device stays excluded, even if it still matches the deployment selector, until it is re-included. Like DELETE /deployments/:id this only requests removal: the device confirms via the Margo status endpoint, and progress is visible in removal-status and awaiting-removal. When the request covers every remaining target, the whole deployment is removed and deploymentRemoved is true. Provide exactly one of deviceIds or group.

Authorizations

• api-key
• bearer

Parameters

Path Parameters

id

required

string format: uuid

Deployment UUID

Request Body^required

Media typeapplication/json

object

deviceIds

Devices to remove the deployment from. Mutually exclusive with group.

Array<string>

group

Device group (label key/value). Its members are resolved once, at request time. Mutually exclusive with deviceIds.

object

labelKey

required

Label key that defines the group

string

Example

site

labelValue

required

Label value that defines the group

string

Example

berlin

Responses

200

Removal requested

Media typeapplication/json

object

deploymentRemoved

required

True when the request covered every remaining target, so the whole deployment was removed (the same flow as DELETE /deployments/:id). False when the deployment stays live.

boolean

removedDeviceIds

required

Devices the removal was requested for (group members resolved at request time)

Array<string>

remainingTargets

required

Devices that remain targets of the deployment after this request

number

Example^generated

{
  "deploymentRemoved": true,
  "removedDeviceIds": [
    "example"
  ],
  "remainingTargets": 1
}

400

Neither or both of deviceIds/group given, the device was already removed, or the group has no current target

403

Forbidden — caller lacks required permission

404

Deployment not found, or the device is not a target