PUT /v1/groups/<id>

Create a node group with a specific ID.

Request format

When Forming node classifier API requests to this endpoint, the URI path must contain the ID you want to assign to the new group. The ID must be a valid type-4 (random) UUID. The regular expression used to validate node group UUIDs is [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}.

If you use an ID belonging to an existing node group, that node group is overwritten by the new group.

It is possible to overwrite an existing node group with a new node group definition that contains deleted classes or parameters.

The request body must be a JSON object describing the node group to be created. The request uses these keys (which are required unless otherwise noted):

Key	Definition
`name`	The name of the node group, as a string.
`environment`	The name of the node group's environment. This is optional. If omitted, the default value is `production`.
`environment_trumps`	When a node belongs to two or more groups, this Boolean indicates whether this node group's environment overrides environments defined by other node groups. This is optional. If omitted, the default value is `false`.
`description`	A string describing the node group. This is optional. If omitted, the node group has no description.
`parent`	The ID of the node group's parent. This is required.
`rule`	The condition that must be satisfied for a node to be classified into this node group. For rule formatting assistance, refer to Forming node classifier API requests.
`variables`	An optional object that defines the names and values of any top-level variables set by the node group. Supply key-value pairs of variable names and corresponding variable values. Variable values can be any type of JSON value. The `variables` object can be omitted if the node group does not define any top-level variables.
`classes`	A required object that defines the classes to be used by nodes in the node group. The `classes` object contains the parameters for each class. Some classes have required parameters. This object contains nested objects – The `classes` object's keys are class names (as strings), and each key's value is an object that defines class parameter names and their values. Within the nested objects, the keys are the parameter names (as strings), and each value is the parameter's assigned value (which can be any type of JSON value). If no classes are declared, then `classes` must be supplied as an empty object (`{}`). If missing, the server returns a `400 Bad request` response.

Response format

If the node group is successfully created, the service returns a 201 Created response and a JSON body describing the node group.

If the node group already exists, and the existing group is identical to the node group described in the request, then server takes no action, returns a 200 OK response, and a JSON body describing the node group.

Error responses

If there is an error, Node classifier API errors provide error information in the kind key, and are similar to the POST /v1/groups error responses. However, 422 responses to POST requests can include errors caused by a node group’s children, but a node group being created with a PUT request cannot have any children.