> 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.

# Nodes

```python
# Imports (run once)
from air_sdk import AirApi
from air_sdk.endpoints.images import Image
from air_sdk.endpoints.nodes import Node
from air_sdk.endpoints.simulations import Simulation
```

```python
# Authentication (run once)
api = AirApi.with_ngc_config()
# OR api = AirApi.with_api_key(api_key="...")
# OR api = AirApi.with_device_login(email="...", org_num="...")
#    ^ use in terminal only — not supported in Jupyter notebooks
```

## CREATE

We can create new nodes for a simulation by using the `api.nodes.create` method:

```python
sim: Simulation = api.simulations.create(name='Blank Simulation')
ubuntu_2204 = next(api.images.list(search='generic/ubuntu2204'))

node: Node = api.nodes.create(
    simulation=sim,
    image=ubuntu_2204,
    name='ubuntu-server',
    console_username='ubuntu',
    console_password='nvidia',
)
node.dict()
```

```
{'id': 'ab51b7fa-a0a7-4969-ba48-e49c7302c3d5',
 'created': datetime.datetime(2025, 5, 5, 19, 27, 12, 522911, tzinfo=datetime.timezone.utc),
 'modified': datetime.datetime(2025, 5, 5, 19, 27, 14, 522928, tzinfo=datetime.timezone.utc),
 'name': 'ubuntu-server',
 'simulation': '75dd1ce1-7927-46e1-a84c-07ec00661884',
 'image': 'f42d97f1-e217-470a-b63b-59368ef18ec9',
 'category': '',
 'state': 'READY',
 'status_from_worker': '',
 'split_options': None,
 'cpu': 1,
 'memory': 1024,
 'storage': 10,
 'pos_x': 0,
 'pos_y': 0,
 'cdrom': None,
 'storage_pci': None,
 'attributes': None,
 'metadata': None,
 'advanced': {'nic_model': 'virtio',
  'cpu_mode': 'custom',
  'cpu_options': [],
  'secureboot': False,
  'uefi': False,
  'boot': 'hd'},
 'management_ip': None,
 'management_mac': '00:00:00:00:00:00'}
```

Nodes can also be created off of an existing `Simulation` instance:

```python
sim: Simulation = api.simulations.create(name='Blank Simulation')
ubuntu_2204 = next(api.images.list(search='generic/ubuntu2204'))

# You do not have to specify `simulation=sim` in the payload when using this method.
node: Node = sim.nodes.create(name='new-node', image=ubuntu_2204)
node.dict()
```

```
{'id': 'fe4ba46d-1142-4a1c-a9f1-86b453272c1c',
 'created': datetime.datetime(2025, 5, 5, 19, 27, 14, 536811, tzinfo=datetime.timezone.utc),
 'modified': datetime.datetime(2025, 5, 5, 19, 27, 16, 536828, tzinfo=datetime.timezone.utc),
 'name': 'new-node',
 'simulation': '75dd1ce1-7927-46e1-a84c-07ec00661884',
 'image': 'f42d97f1-e217-470a-b63b-59368ef18ec9',
 'category': 'SERVER',
 'state': 'READY',
 'status_from_worker': '',
 'split_options': None,
 'cpu': 1,
 'memory': 1024,
 'storage': 10,
 'pos_x': 0,
 'pos_y': 0,
 'cdrom': None,
 'storage_pci': None,
 'attributes': None,
 'metadata': None,
 'advanced': {'nic_model': 'virtio',
  'cpu_mode': 'custom',
  'cpu_options': [],
  'secureboot': False,
  'uefi': False,
  'boot': 'hd'},
 'management_ip': None,
 'management_mac': '00:00:00:00:00:00'}
```

## GET

How to list, filter, order, and search for nodes of a simulation.

```python
ubuntu_2204: Image = next(api.images.list(search='generic/ubuntu2204'))
cumulus_5_6_0: Image = next(api.images.list(search='cumulus-vx-5.6.0'))
sim: Simulation = api.simulations.create(name='Blank Simulation')
```

```python
# Create nodes with various specifications
sim.nodes.create(name='ubuntu-1', image=ubuntu_2204)
sim.nodes.create(name='ubuntu-2', image=ubuntu_2204)
sim.nodes.create(name='ubuntu-12', image=ubuntu_2204)
sim.nodes.create(name='special-node', image=ubuntu_2204)
sim.nodes.create(name='node14', image=cumulus_5_6_0)
sim.nodes.create(name='node15', image=cumulus_5_6_0)
sim.nodes.create(name='node16', image=cumulus_5_6_0)

for node in sim.nodes.list():
    print(node)
```

```
Node(id='42917bde-000a-4209-a20b-59db0c15b1a1', name='ubuntu-1')
Node(id='552b72bd-e4c5-4226-b50e-0e763c7890b8', name='ubuntu-2')
Node(id='c2903bfe-fa0b-43ec-ae75-7faf80f1f049', name='ubuntu-12')
Node(id='7f6772aa-76ef-4012-a2e0-e6d30ceb78a4', name='special-node')
Node(id='f61db084-99da-4928-bdb3-7bbd5950416e', name='node14')
Node(id='1a77d4bd-f533-48a7-a169-1415d52d8d91', name='node15')
Node(id='4abe2036-b4d1-438e-ad3b-9c236fd32e47', name='node16')
```

#### Order nodes by specific fields

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

```
node14
node15
node16
special-node
ubuntu-1
ubuntu-12
ubuntu-2
```

#### Search for nodes by name

```python
for node in sim.nodes.list(search='node'):
    print(node.name)
```

```
node14
node15
node16
```

#### Filter node by specific properties

```python
for node in sim.nodes.list(image=cumulus_5_6_0):
    print(node.name, node.image.name)
```

```
node14 cumulus-vx-5.6.0
node15 cumulus-vx-5.6.0
node16 cumulus-vx-5.6.0
```

This can be used to obtain a specific node by `name`

```python
list(sim.nodes.list(name='special-node'))
```

```
[Node(id='7f6772aa-76ef-4012-a2e0-e6d30ceb78a4', name='special-node')]
```