POST /v1/groups/<id>/pin

Pin specific nodes to a node group.

Request format

When Forming node classifier API requests to this endpoint, the URI path must contain a node group ID. For example:

POST https://localhost:4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65/pin

The request must also provide the names of the nodes you want to pin to the group. There are two ways to do this:

Append the node names to the URI path. If you are pinning more than one node, use encoded comma separation (%2C) between node names. For example, this request pins the nodes named foo, bar, and baz to the group:
```
POST https://localhost:4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65/pin?nodes=foo%2Cbar%2Cbaz
```
Supply the node names in the request body. For a single node, you can supply this in a simple JSON object. For multiple nodes, supply the node names in an array. For example, this JSON body pins a single node:
```
{"nodes": ["foo"]}
```
And this body pins three nodes:
```
{"nodes": ["foo", "bar", "baz"]}
```

While it's easier to append the nodes to the end of the URI path, if you want to pin a lot of nodes at once, the URI path might get truncated. Strings are truncated if they exceed 8,000 characters. In this case, you have to supply the nodes in a JSON body, which can be many megabytes in size.

Here is an example of a complete curl request to the POST /v1/groups/<id>/pin endpoint. If necessary, replace /etc/puppetlabs/puppet/ssl/certs/ca.pem with the correct path to your CA certificate file:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups/085e2797-32f3-4920-9412-8e9decf4ef65/pin"
data='{ "nodes": ["example-to-pin.example.vm"] }'

curl --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

Response format

If pinning is successful, the service returns a 204 No Content response with an empty body.

If the request contained a node that is already pinned to the group, the node's pinned status is unchanged –- The service only pins nodes that aren't already pinned to the specified node group.

Error responses

If there is an error, Node classifier API errors provide error information in the kind key.

If your request doesn't specify any nodes to pin, the service returns a 400 Malformed Request response.

If the request body is invalid JSON, is missing the nodes key, or contains any keys other than nodes, the service returns a 400 Malformed Request response.