Upsert an endpoint group

POST /endpoint-groups

Creates a server-identified group or replaces the complete customer document with If-Match. Provider truth remains authoritative; changes use the atomic group engine and advance each affected group once. BEST_EFFORT is the default. Inspect status and errors on HTTP 200. Retained terminal responses replay for 24 hours after provider attempts.

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. Requests rolled back before external provider attempts do not consume the key. Group mutations retain terminal failed responses after provider attempts together with received provider truth; their operation contract defines these replayable outcomes.

minLength: 1

maxLength: 255

If-Matchstring

Required for a full replacement when the request identifies an existing resource. Send that resource's quoted strong etag from its last GET. A missing condition on a replacement returns 428 PRECONDITION_REQUIRED; a stale condition returns 412 PRECONDITION_FAILED. Omit this header when creating a new resource without an id. Wildcards are accepted only where the operation explicitly permits them.

minLength: 1

Request body

Required

Fields

UpsertEndpointGroupRequest

Returns

200

Endpoint group created successfully

Fields

UpsertEndpointGroupResponse

Response headers

ETagstring: Opaque strong entity tag of the returned resource version. Send it back in `If-Match` on the next mutation of the same resource.

Errors

400 BAD_REQUEST

Bad request - invalid request payload

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 - insufficient permissions

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

404 NOT_FOUND

Named group does not exist

Verify the target identifier and that its endpoint or plugin route still exists.

409 IDEMPOTENCY_KEY_IN_FLIGHT

The same idempotency key is in flight

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

412 PRECONDITION_FAILED

The group version does not match If-Match

Inspect the returned code and family and follow the error handling guide.

422 IDEMPOTENCY_KEY_REUSED

The same idempotency key was used with another payload

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

428 PRECONDITION_REQUIRED

If-Match is required for replacement

Inspect the returned code and family and follow the error handling guide.

500 INTERNAL

Internal server error

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