Manage endpoint groups atomically

POST /endpoint-groups-manage

Applies a bounded list (max 20) of endpoint group management operations atomically in one transaction. The operations are CREATE_GROUP, DELETE_GROUP, SET_NAME, ADD_MEMBERS, REMOVE_MEMBERS and MERGE_INTO. Every operation that modifies an existing group carries the group's etag, which is compared inside the transaction. Item outcomes are returned with HTTP 200 in a status/results/errors envelope correlated by requestId; non-200 statuses are reserved for request-level failures. Idempotency-Key is required unless validateOnly is true; a committed response is replayed for 24 hours for the same principal, key and payload. Physical control is never part of this request; use POST /messages.

Required scope

group:manage

Header parameters

Idempotency-KeystringRequired

Client-chosen key that makes a non-idempotent request retry-safe, following draft-ietf-httpapi-idempotency-key-header. A committed response is stored for 24 hours and replayed for the same principal, operation, key and payload. Missing key returns 400 IDEMPOTENCY_KEY_REQUIRED, a key longer than 255 characters returns 400 IDEMPOTENCY_KEY_INVALID, the same key with a different payload returns 422, and the same key while the first request is still in flight returns 409. Failed (rolled-back) requests do not consume the key.

minLength: 1

maxLength: 255

Request body

Fields

validateOnlyboolean

When true, runs authorization and validation and returns what would happen, writing nothing. A validate-only request neither requires nor consumes an `Idempotency-Key`.

Default: false

operationsarray<EndpointGroupsManageOperation>Required

Returns

200

Batch evaluated. status is COMMITTED when every operation was applied (or would be, for validateOnly), otherwise FAILED with every failing operation in errors and nothing written.

Fields

statusstringRequired

Outcome of an atomic batch. `COMMITTED` means every operation was applied (or, for a validate-only request, would be applied); `FAILED` means nothing was written and `errors` lists every failing operation.

Allowed values: COMMITTED, FAILED.

resultsarray<EndpointGroupsManageResult>Required

errorsarray<BatchItemError>Required

Errors

400 IDEMPOTENCY_KEY_REQUIRED

Malformed request, unknown operation, duplicate `requestId`, or missing (`IDEMPOTENCY_KEY_REQUIRED`) or over-long (`IDEMPOTENCY_KEY_INVALID`) `Idempotency-Key`

Check the request fields and any validation details, then correct the payload.

401 UNAUTHORIZED

Unauthorized - invalid or missing authentication token

Obtain a valid access token, then retry.

403 FORBIDDEN

Forbidden - token lacks the group:manage scope

Check the linked account and its permissions for the device or resource.

409 IDEMPOTENCY_KEY_IN_FLIGHT

A request with the same `Idempotency-Key` is still in flight

Check the device’s current mode or state. Retry only after the conflict is resolved.

422 IDEMPOTENCY_KEY_REUSED

The `Idempotency-Key` was already used with a different payload

Correct the rejected value using the constraints in the error details or request schema.

500 INTERNAL

Internal server error

Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.