Update devices

patch/devices/v2beta1/devices

Update devices by passing one or more device IDs.

The API supports Device operations such as:

  • Assigning and unassigning devices to and from a service.
  • Adding, updating and removing tags to devices.
  • Archiving and un-archiving the devices.
The API endpoint supports subscription operations of applying and removing subscriptions to and from devices.

To remove an application, set the id under application to null and region to null. Set an empty array to the attribute subscription to remove a subscription. For each tag provided in the request body:
  • Tags are created and inserted into the specified devices if the provided tags do not map to null and are not already present.
  • Tags are updated with the provided if the provided tag key is already present in a device, but the provided value differs from the existing value.
  • Tags are removed from devices when a tag key is mapped to a null tag value. The tags are removed from any devices with a matching tag with the same key.
The endpoint only supports either a device or a subscription operation per API call. For example, you cannot assign devices to an application and assign subscriptions to devices in a single API call. You can achieve this with two separate API calls. However, a single API call can perform device operations together; for example, assigning an application and adding tags can be performed.

The archive device operation is incompatible with any other device operation in the same API call. For example, you cannot remove an application and archive a device using the same API call.

This is an asynchronous API endpoint and it returns the 202 Accepted response code and a Location header containing the URI of the asynchronous operation that can be used to track progress. For details about the status fetch URL, refer to the API Get progress or status of async operations in devices.

NOTE: You need edit permissions for the Devices and Subscription service to initiate this API call. Rate limits are enforced, and five requests per minute are supported per workspace. The API returns 429 if this threshold is breached.
SecurityBearer
Request
query Parameters
dry-run
boolean
Default: false

The dry-run query parameter is used to perform the resource update operation (POST, PUT, PATCH, DELETE) and return a response as if the operation had completed, but without actually creating, updating, or deleting the resource. This allows you to test if the request would succeed before making the change. If set to true, the request is validated but not executed.

id
required
Array of strings unique

Array of device resource IDs. Maximum twenty five devices per request.

Example: id=05fc0c47-e517-5709-976e-c0b726977477&id=08a42d07-b144-5602-9a82-7927d6e44616
Request Body schema: application/merge-patch+json
required
object (RequestApplication)
archived
boolean
region
string

The region of the application the device is provisioned in.

Array of objects (RequestSubscription)
object

Provide a map of tags to create or delete for the given DeviceID (or multiple DeviceID's). Tags are saved with the character casing preserved (uppercase, lowercase, mixed, and so on). For example, adding a new tag with the key Location will fail if the Device already has a tag with the key LOCATION as they are considered the same key. Tag keys and tag values can comprise letters, numbers, spaces (represented in UTF-8), and only the characters: _, ., :, =, +, -, and @. NOTE: Do not store sensitive data, such as personally identifiable information, in tags.

tenantWorkspaceId
string

The platform customer ID of the tenant.

Responses
202

Request accepted

400

Bad request

401

Unauthorized request

403

The operation is forbidden

422

Validation error

429

Too many requests

500

Internal server error

Request samples
application/merge-patch+json

The location tag is created with San Jose, the purchase month tag is created with April 2023 , and the Setup Option tag is created with Default.

{
  • "tags": {
    }
}
Response samples
application/json
{
  • "code": 0,
  • "status": "100 CONTINUE",
  • "transactionId": "string"
}