> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/dsx-air/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/dsx-air/_mcp/server.

# air_sdk.endpoints.nodes

Stub file for simulations endpoint type hints.

## Classes

| Name                                                               | Description                                          |
| ------------------------------------------------------------------ | ---------------------------------------------------- |
| [`NodeAttributes`](#air_sdkendpointsnodesnodeattributes)           | Node attributes for topology organization.           |
| [`NodeAdvanced`](#air_sdkendpointsnodesnodeadvanced)               | Advanced node configuration options.                 |
| [`NodeCDROM`](#air_sdkendpointsnodesnodecdrom)                     | CD-ROM configuration for a node.                     |
| [`StoragePCIField`](#air_sdkendpointsnodesstoragepcifield)         | Represents a single storage PCI drive configuration. |
| [`CloudInitAssignment`](#air_sdkendpointsnodescloudinitassignment) | Response payload for cloud-init assignment.          |
| [`Node`](#air_sdkendpointsnodesnode)                               | Node model representing a network node.              |
| [`NodeEndpointAPI`](#air_sdkendpointsnodesnodeendpointapi)         | API client for simulation endpoints.                 |

## Module Contents

```python
class air_sdk.endpoints.nodes.NodeAttributes
```

**Bases**: `typing.TypedDict`

Node attributes for topology organization.

```python
group: str | None
```

```python
model: str | None
```

```python
sku: str | None
```

```python
rack_name: str | None
```

```python
rack_unit: int | None
```

```python
scalable_unit: int | None
```

```python
rail_index: int | None
```

```python
data_hall: str | None
```

```python
tray_index: int | None
```

```python
role: str | None
```

```python
pod: int | None
```

```python
superspine_group: int | None
```

```python
plane_id: int | None
```

```python
class air_sdk.endpoints.nodes.NodeAdvanced
```

**Bases**: `typing.TypedDict`

Advanced node configuration options.

```python
secureboot: bool | None
```

```python
uefi: bool | None
```

```python
tpm: bool | None
```

```python
cpu_options: Literal[ssse3, sse4.1, sse4.2, popcnt] | None
```

```python
cpu_mode: Literal[custom, host-model, host-passthrough]
```

```python
boot: Literal[hd, network]
```

```python
nic_model: Literal[virtio, e1000]
```

```python
class air_sdk.endpoints.nodes.NodeCDROM
```

**Bases**: `typing.TypedDict`

CD-ROM configuration for a node.

```python
image: Image | None
```

```python
class air_sdk.endpoints.nodes.StoragePCIField
```

**Bases**: `typing.TypedDict`

Represents a single storage PCI drive configuration.

Used in storage\_pci as: dict\[str, StoragePCIField]
where keys are dynamic drive names like "drive1", "drive2", etc.

```python
name: str | None
```

```python
size: int | None
```

```python
type: Literal[NVME] | None
```

```python
class air_sdk.endpoints.nodes.CloudInitAssignment
```

**Bases**: `typing.TypedDict`

Response payload for cloud-init assignment.

```python
user_data: UserConfig | None
```

```python
meta_data: UserConfig | None
```

```python
class air_sdk.endpoints.nodes.Node
```

**Bases**: `air_sdk.air_model.AirModel`

Node model representing a network node.

```python
id: str
```

Unique identifier for the node

```python
created: datetime.datetime
```

Timestamp when the node was created

```python
modified: datetime.datetime
```

Timestamp when the node was last modified

```python
name: str
```

Human-readable name of the node

```python
simulation: Simulation
```

```python
image: Image
```

```python
state: str
```

Current state of the node

```python
category: str
```

Category of the node

```python
status_from_worker: str
```

Status of the node from the worker

```python
split_options: list[int] | None
```

Split options for the node

```python
cpu: int
```

CPU of the node

```python
memory: int
```

Memory of the node

```python
storage: int
```

Storage of the node

```python
pos_x: int
```

X position of the node

```python
pos_y: int
```

Y position of the node

```python
attributes: NodeAttributes | None
```

Attributes of the node

```python
advanced: NodeAdvanced
```

Advanced attributes of the node

```python
cdrom: NodeCDROM | None
```

CDROM attributes of the node

```python
storage_pci: dict[str, StoragePCIField] | None
```

Storage PCI attributes of the node

```python
get_model_api() -> type[NodeEndpointAPI]
```

```python
model_api: NodeEndpointAPI
```

```python
update(
    *,
    name: str | dataclasses._MISSING_TYPE = ...,
    image: Image | dataclasses._MISSING_TYPE = ...,
    cpu: int | dataclasses._MISSING_TYPE = ...,
    memory: int | dataclasses._MISSING_TYPE = ...,
    storage: int | dataclasses._MISSING_TYPE = ...,
    pos_x: int | dataclasses._MISSING_TYPE = ...,
    pos_y: int | dataclasses._MISSING_TYPE = ...,
    attributes: dict[str, Any] | dataclasses._MISSING_TYPE = ...,
    advanced: dict[str, Any] | dataclasses._MISSING_TYPE = ...,
    storage_pci: dict[str, Any] | dataclasses._MISSING_TYPE = ...
) -> None
```

Update the node's properties.

**Parameters:**

* `name` – Name of the node
* `image` – Image of the node
* `cpu` – CPU of the node
* `memory` – Memory of the node
* `storage` – Storage of the node
* `pos_x` – X position of the node
* `pos_y` – Y position of the node
* `attributes` – Attributes of the node
* `advanced` – Advanced attributes of the node
* `storage_pci` – Storage PCI of the node

**Example:**

```python
>>> node = api.nodes.update(
...     name='my-node',
...     image=image,
...     cpu=1,
...     memory=1024,
...     storage=10,
...     pos_x=0,
...     pos_y=0,
...     attributes={'key': 'value'},
...     advanced={'key': 'value'},
...     storage_pci={'key': 'value'},
... )
```

```python
clear_cloud_init_assignment(**kwargs: Any) -> None
```

Clear cloud-init assignment for this node (V3).

Removes any user\_data and meta\_data cloud-init configurations from this node.

**Example:**

```python
>>> node.clear_cloud_init_assignment()
```

```python
instructions: Any
```

Access the instructions endpoint for this node.

**Returns:**

Any instance scoped to this node

**Example:**

```python
>>> node = api.nodes.instructions.list()
```

```python
interfaces: InterfaceEndpointAPI
```

Access the interfaces endpoint for this node.

**Returns:**

Any instance scoped to this node

**Example:**

```python
>>> for interface in node.interfaces.list():
...     print(interface.name)
```

```python
services: ServiceEndpointAPI
```

Query for the related services of the node.

**Returns:**

ServiceEndpointAPI instance filtered for this node's services

**Example:**

```python
>>> for service in node.services.list():
...     print(f'{service.name}: {service.worker_fqdn}:{service.worker_port}')
>>>
>>> # Create service by interface ID
>>> service = node.services.create(
...     name='ssh-service',
...     interface='interface-id',
...     node_port=22,
...     service_type='SSH'
... )
```

```python
create_service(
    *,
    interface_name: str,
    node_port: int,
    name: str = ...,
    service_type: Literal[SSH, HTTPS, HTTP, OTHER] = ...
) -> Service
```

Create service by resolving interface name (v3 convenience).

**Parameters:**

* `interface_name` – Interface name on this node (e.g., 'eth0', 'swp1')
* `node_port` – Port number on the node/interface
* `name` – Service name
* `service_type` – Service type - 'SSH', 'HTTPS', 'HTTP', or 'OTHER'

**Returns:**

Service object

**Raises:**

* `ValueError` – If interface not found on this node

**Example:**

```python
>>> service = node.create_service(
...     interface_name='eth0',
...     name='ssh-service',
...     node_port=22,
...     service_type='SSH',
... )
```

```python
delete_all_node_instructions() -> None
```

Delete all node instructions for this node.

**Example:**

```python
>>> node = api.nodes.delete_all_node_instructions()
```

```python
cloud_init: CloudInit
```

Cloud-Init assignments of the node

Get the cloud-init assignment for this node.

**Returns:**

CloudInit object containing user\_data and meta\_data assignments

**Example:**

```python
>>> cloud_init = node.cloud_init
>>> print(cloud_init.user_data)
>>> print(cloud_init.meta_data)
```

```python
reset() -> None
```

Reset this node.

Resetting the node emulates the hardware reset button on physical machines
where the machine is immediately restarted without a clean shutdown of the
operating system. For nodes that are not currently running, this means simply
booting them back up.

**Example:**

```python
>>> node.reset()
```

```python
rebuild() -> None
```

Rebuild this node.

Rebuilding a node means returning the node to the state of its simulation's
current checkpoint.
When rebuilding from the initial state, all repeatable instructions
for this node will be applied. All existing instructions created for this node
which have not yet been completed will be failed. All existing instructions
created for this node which have not yet been delivered will be cancelled.

**Example:**

```python
>>> node.rebuild()
```

```python
class air_sdk.endpoints.nodes.NodeEndpointAPI
```

**Bases**: `air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.nodes.Node]`

API client for simulation endpoints.

```python
API_PATH: str
```

```python
model: type[Node]
```

```python
create(
    *,
    name: str,
    simulation: Simulation,
    image: Image,
    cpu: int | None = ...,
    memory: int | None = ...,
    storage: int | None = ...,
    pos_x: int | None = ...,
    pos_y: int | None = ...,
    attributes: NodeAttributes | None = ...,
    advanced: NodeAdvanced | None = ...,
    storage_pci: dict[str, StoragePCIField] | None = ...
) -> Node
```

Create a new node.

**Parameters:**

* `name` – Name of the node
* `simulation` – Simulation of the node
* `image` – Image of the node
* `cpu` – (optional) CPU of the node
* `memory` – (optional) Memory of the node
* `storage` – (optional) Storage of the node
* `pos_x` – (optional) X position of the node
* `pos_y` – (optional) Y position of the node
* `attributes` – (optional) Attributes of the node
* `advanced` – (optional) Advanced attributes of the node
* `storage_pci` – (optional) Storage PCI of the node

**Example:**

```python
>>> node = api.nodes.create(simulation=sim, image=image, name='my-node')
```

**Returns:**

The created node instance

```python
list(
    *,
    limit: int | None = ...,
    offset: int | None = ...,
    ordering: str | None = ...,
    search: str | None = ...,
    **kwargs: Any
) -> Iterator[Node]
```

List all nodes.

**Parameters:**

* `limit` – (optional) Limit the number of nodes returned
* `offset` – (optional) Offset the number of nodes returned
* `ordering` – (optional) Order the nodes by a field
* `search` – (optional) Search for nodes by a keyword

**Returns:**

Iterator of Node instances

**Example:**

```python
>>> for node in api.nodes.list(ordering='name'):
...     print(node.name)

>>> for node in api.nodes.list(search='my-node'):
...     print(node.name)

>>> for node in api.nodes.list(ordering='-name'):
...     print(node.name)
```

```python
get(pk: PrimaryKey) -> Node
```

Get a specific node by ID.

**Parameters:**

* `pk` – The node ID (string or UUID)

**Returns:**

The Node instance

**Example:**

```python
>>> node = api.nodes.get('node-id')
```

```python
delete(pk: PrimaryKey) -> None
```

Delete a specific node by ID.

**Parameters:**

* `pk` – The node ID (string or UUID)

**Example:**

```python
>>> api.nodes.delete('node-id')
```

```python
update(
    *,
    node: Node | PrimaryKey,
    name: str | dataclasses._MISSING_TYPE = ...,
    image: Image | dataclasses._MISSING_TYPE = ...,
    cpu: int | dataclasses._MISSING_TYPE = ...,
    memory: int | dataclasses._MISSING_TYPE = ...,
    storage: int | dataclasses._MISSING_TYPE = ...,
    pos_x: int | dataclasses._MISSING_TYPE = ...,
    pos_y: int | dataclasses._MISSING_TYPE = ...,
    attributes: NodeAttributes | dataclasses._MISSING_TYPE = ...,
    advanced: NodeAdvanced | dataclasses._MISSING_TYPE = ...,
    storage_pci: dict[str, StoragePCIField] | None = ...
) -> Node
```

Update a specific node by ID.

**Parameters:**

* `node` – The node to update (Node object or ID)
* `name` – Name of the node
* `image` – Image of the node (image object or ID)
* `cpu` – CPU of the node
* `memory` – Memory of the node
* `storage` – Storage of the node
* `pos_x` – X position of the node
* `pos_y` – Y position of the node
* `attributes` – Attributes of the node
* `advanced` – Advanced attributes of the node
* `storage_pci` – Storage PCI of the node

**Example:**

```python
>>> node = api.nodes.update(node=node, name='my-node')
```

```python
create_from_system_node(
    system_node: System | PrimaryKey,
    name: str,
    simulation: Simulation | PrimaryKey,
    image: Image | PrimaryKey | dataclasses._MISSING_TYPE = ...,
    cpu: int | dataclasses._MISSING_TYPE = ...,
    memory: int | dataclasses._MISSING_TYPE = ...,
    storage: int | dataclasses._MISSING_TYPE = ...,
    pos_x: int | dataclasses._MISSING_TYPE = ...,
    pos_y: int | dataclasses._MISSING_TYPE = ...,
    attributes: dict[str, Any] | dataclasses._MISSING_TYPE = ...,
    advanced: dict[str, Any] | dataclasses._MISSING_TYPE = ...,
    storage_pci: dict[str, StoragePCIField] | dataclasses._MISSING_TYPE = ...,
    **kwargs: Any
) -> Node
```

Create a node from a system node template.

**Parameters:**

* `system_node` – System node template ID to create from
* `name` – Name of the new node
* `simulation` – Simulation object or ID where the node will be created
* `image` – Optional image to use (overrides template)
* `cpu` – Optional CPU count (overrides template)
* `memory` – Optional memory in MB (overrides template)
* `storage` – Optional storage in GB (overrides template)
* `pos_x` – Optional X position on canvas
* `pos_y` – Optional Y position on canvas
* `attributes` – Optional node attributes
* `advanced` – Optional advanced configuration
* `storage_pci` – Optional storage PCI configuration
* `**kwargs` – Additional parameters

**Returns:**

The created Node object

**Example:**

```python
>>> node = api.nodes.from_system_node(
...     system_node='system-node-template-id',
...     name='my-node',
...     simulation='simulation-id'
... )
```

```python
list_system_nodes(**kwargs: Any) -> list[System]
```

List all available system nodes.

**Parameters:**

* `limit` – (optional) Limit the number of system nodes returned
* `offset` – (optional) Offset the number of system nodes returned
* `ordering` – (optional) Order the system nodes by a field
* `search` – (optional) Search for system nodes by a keyword
* `simulation` – (optional) Filter system nodes by simulation

**Returns:**

List of System objects that can be used to create nodes.

```python
reset(
    *,
    node: Node | PrimaryKey
) -> None
```

Reset a node.

Resetting the node emulates the hardware reset button on physical machines
where the machine is immediately restarted without a clean shutdown of the
operating system. For nodes that are not currently running, this means simply
booting them back up.

**Parameters:**

* `node` – The node object or node ID to reset

**Example:**

```python
>>> # Reset using node object
>>> api.nodes.reset(node=node)

>>> # Reset using node ID
>>> api.nodes.reset(node='node-uuid-123')
```

```python
rebuild(
    *,
    node: Node | PrimaryKey
) -> None
```

Rebuild a node.

Rebuilding a node means returning the node to the state of its simulation's
current checkpoint.
When rebuilding from the initial state, all repeatable instructions
for the node will be applied. All existing instructions created for the node
which have not yet been completed will be failed. All existing instructions
created for the node which have not yet been delivered will be cancelled.

**Parameters:**

* `node` – The node object or node ID to rebuild

**Example:**

```python
>>> # Rebuild using node object
>>> api.nodes.rebuild(node=node)

>>> # Rebuild using node ID
>>> api.nodes.rebuild(node='node-uuid-123')
```