Retrieve a single node

GET api/nodes/hostname

Retrieves the details about a specific node, specified by its hostname. The response includes all system properties and their respective virtual nodes for each node, as well as all dynamic properties.

Request syntax

get api/nodes/<hostname>

Request parameters

The request accepts the following data in JSON format.

Parameter	Type	Description	Required	Default value
`resolve_refs`	Boolean	This resolves property references.	No	`true`

Response syntax

{
    "id": integer,
    "installation_token": {
        "uuid": "d3cceEXAMPLE",
        "state": "string",
        "expires_at": "timestamp"
    },
    "node_name": "string",
    "node_group_id": integer,
    "store_number": integer,
    "instance_number": integer,
    "hostname": "string",
    "serialno": "string",
    "virtual": boolean,
    "type_of_server": "string",
    "hierarchy_field_id": "string",
    "status": "string",
    "keepalive_timestamp": integer,
    "last_online": "string",
    "created_at": timestamp,
    "updated_at": timestamp,
    "virtual_nodes": [
    ],
    "puppet_masterless": boolean,
    "puppet_environment": "string",
    "properties": {
        "property1": "value1",
        "property2": {
            "nested_property1": "nested_value1"
        }
    },
    "service_checks": {
        "docker_versions": [
        ]
    },
    "available_docker_images": {
        "images": [
            {
            "ID": "string",
            "Tag": "string",
            "Size": "string",
            "Digest": "string",
            "CreatedAt": "string",
            "Containers": "string",
            "Repository": "string",
            "SharedSize": "string",
            "UniqueSize": "string",
            "VirtualSize": "string",
            "CreatedSince": "string"
            }
        ],
        "last_checked": timestamp
    }
}

Response parameters

If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format.

Field	Type	Description
`id`	Integer	The ID of the node.
`installation_token`	Object	The details about the installation token.
`node_name`	String	The hostname of the node.
`node_group_id`	Integer	The ID of the node group the node belongs to.
`store_number`	Integer	The store number associated with the node. This corresponds to the `Node Number` value in SC//Reliant™ Platform Manager.
`instance_number`	Integer	The instance number associated with the node.
`hostname`	String	The hostname of the node.
`serialno`	String	The serial number of the physical host of the node.
`virtual`	Boolean	Whether or not the node is a virtual node.
`type_of_server`	String	The server type of the node. If no type is associated, this returns a `null` value.
`hierarchy_field_id`	Integer	The ID associated with the level of hierarchy field.
`status`	String	The current status of the node.
`keepalive_timestamp`	Integer	The UNIX epoch timestamp of the last keepalive transmission.
`last_online`	Timestamp	The timestamp indicating the last time the node was confirmed online.
`created_at`	Timestamp	The timestamp indicating when the node was created in SC//Reliant Platform Manager.
`updated_at`	Timestamp	The timestamp indicating when the node was last updated in SC//Reliant Platform Manager.
`virtual_nodes`	String array	The details of the virtual nodes associated with the node.
`puppet_environment`	String	The branch that is used for Puppet agent runs. If no value is specified, the default value of `Production` is used.
`puppet_masterless`	Boolean	Whether or not Puppet is run in `masterless` mode.
`properties`	String array	The system and dynamic properties associated with the node.
`service_checks`	String array	The details of the last service checks run on the node.
`available_docker_images`	String array	The Docker images available on the node. This is similar to running a `docker images` command on the node.

Errors

The following are common errors returned by this API.

Code	Message	Cause
-	-	-

Examples

Example: Return the details of a single node

This example returns the details about the sit0000red0 node.

ruby api.rb <customer_code> get api/nodes/sit0000red0

Response

{
    "id": 112874,
    "installation_token": {
        "uuid": "f6d4fcEXAMPLE",
        "state": "active",
        "expires_at": null
    },
    "node_name": "sit0000red0",
    "node_group_id": 1953,
    "store_number": 102,
    "instance_number": 0,
    "hostname": "sit0000red0",
    "serialno": null,
    "virtual": false,
    "type_of_server": null,
    "hierarchy_field_id": null,
    "status": "online",
    "keepalive_timestamp": 1724797676,
    "last_online": "2024-08-27T22:27:56.000Z",
    "created_at": "2023-12-18T19:58:28.931Z",
    "updated_at": "2024-07-12T14:38:02.332Z",
    "virtual_nodes": [],
    "puppet_environment": null,
    "puppet_masterless": false,
    "properties": {
        "my_property1": "API_KEY=123EXAMPLEkey"
    },
    "service_checks": {
        "docker_versions": []
    },
    "available_docker_images": null
}

Example: Return the value of a specific property for a node

This example returns the value of the property1 property for the sit0000red0 node. You must prefix all dynamic property names with my_ and specify the name in all lowercase. For example, if you have a dynamic property named Lan1 Ip, you would specify that as my_lan1_ip in the request.

ruby api.rb <customer_code> get api/nodes/sit0000red0/property/my_property1

Response

{
    "value": "API_KEY=123EXAMPLEkey"
}