Manage endpoint groups atomically
/endpoint-groups-manageEvaluates at most 20 group operations with shared starting etags. Contradictory batch intent returns 400 before provider dispatch; operation order does not make incompatible edits valid. BEST_EFFORT is the default for create, delete, add, remove, move and rename. Merge and both enablement operations accept only PORTOS_ONLY. Declared providers are called before one transaction reconciles replies and saves permitted customer intent with final group etags. Item outcomes use HTTP 200 and requestId correlation. PARTIALLY_SUCCEEDED is saved with local fallback; FAILED can retain received provider truth and attempted dispatch outcomes while rejecting customer intent. Idempotency-Key is required unless validateOnly is true, and terminal responses after provider attempts replay for 24 hours without resending messages.
Required scope
group:manageHeader parameters
- Idempotency-Key
string Required when this request changes state; omitting it returns 400 IDEMPOTENCY_KEY_REQUIRED. The operation documents its read-only modes, which neither require nor consume a key. Committed responses replay for 24 hours for the same principal, operation, key and payload. Reusing a key with a different payload returns 422; an in-flight request returns 409. The key must contain between 1 and 255 characters when provided for a mutation.
minLength: 1
maxLength: 255
Request body
Returns
200
Batch evaluated. COMMITTED and PARTIALLY_SUCCEEDED save customer changes; FAILED rejects customer intent but retains valid provider truth and the failed receipt after provider attempts. Inspect operation status and providerDispatches, including on HTTP 200.
Errors
400 IDEMPOTENCY_KEY_REQUIREDMalformed request, unknown operation, duplicate `requestId`, or missing (`IDEMPOTENCY_KEY_REQUIRED`) or over-long (`IDEMPOTENCY_KEY_INVALID`) `Idempotency-Key` for a mutation. validateOnly requests neither require nor consume a key.
Check the request fields and any validation details, then correct the payload.
401 UNAUTHORIZEDUnauthorized - invalid or missing authentication token
Obtain a valid access token, then retry.
403 FORBIDDENForbidden - token lacks the group:manage scope
Check the linked account and its permissions for the device or resource.
409 IDEMPOTENCY_KEY_IN_FLIGHTA 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_REUSEDThe `Idempotency-Key` was already used with a different payload
Correct the rejected value using the constraints in the error details or request schema.
500 INTERNALInternal server error
Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.