air_sdk.endpoints.simulations

Update the simulation’s properties.

Note: For OOB and DHCP configuration, use dedicated methods like enable_auto_oob(), disable_auto_oob(), etc.

Parameters:

• name – New name for the simulation
• sleep_at – When the simulation should be automatically put to sleep
• expires_at – When the simulation should be automatically deleted
• documentation – Documentation markdown or URL to documentation markdown
• metadata – Custom metadata as a JSON string

Example:

>>> simulation.update(name='New Name', documentation='https://docs.example.com')
>>> simulation.update(metadata='{"env": "production", "version": "1.0"}')

Enable automatic Out-of-band management for this simulation.

Parameters:

• enable_dhcp – If True, enable DHCP on the OOB management network (default behavior). If False, disable DHCP on the OOB network.

Example:

# Enable OOB with DHCP (default):
>>> simulation.enable_auto_oob()
# Enable OOB without DHCP:
>>> simulation.enable_auto_oob(enable_dhcp=False)

Disable automatic Out-of-band management for this simulation.

Example:

>>> simulation.disable_auto_oob()

Start the simulation.

Parameters:

• checkpoint – Optional checkpoint ID to start from. If not specified, the API will use its default behavior (typically uses the most recent checkpoint if available). If explicitly set to None, starts from clean state (rebuild). If a string, starts from the specified checkpoint.

Example:

# Normal start (API determines behavior):
>>> simulation.start()
# Start from specific checkpoint:
>>> simulation.start(checkpoint='checkpoint-id')
# Rebuild (start from clean state, no checkpoint):
>>> simulation.start(checkpoint=None)

Shut down the simulation.

Parameters:

• create_checkpoint – Whether to create a checkpoint before shutting down. If not specified, the API will use its default behavior.

Example:

# Normal shutdown (API determines behavior):
>>> simulation.shutdown()
# Explicitly create checkpoint before shutdown:
>>> simulation.shutdown(create_checkpoint=True)
# Explicitly don't create checkpoint:
>>> simulation.shutdown(create_checkpoint=False)

Rebuild the simulation from a given checkpoint.

Tears down the simulation and starts it from the given checkpoint. If no checkpoint is provided, the simulation will be rebuilt from the clean state.

Parameters:

• checkpoint – Optional checkpoint ID to rebuild from. If not specified, the API will use its default behavior (the current checkpoint the simulation is running off of). If explicitly set to None, starts from clean state (rebuild). If a string, starts from the specified checkpoint.

Example:

# Rebuild simulation from specific checkpoint:
>>> simulation.rebuild(checkpoint='checkpoint-id')

Wait for simulation to reach one of the target states.

Parameters:

• target_states – Single state or list of states to wait for
• timeout – Maximum time to wait (default: 120 seconds)
• poll_interval – Time between status checks (default: 2 seconds)
• error_states – Single state or list of states that should raise an error

Raises:

• ValueError – If the simulation enters one of the error states
• TimeoutError – If timeout is reached before target state

Example:

>>> simulation.wait_for_state('ACTIVE', error_states=['INVALID'])
>>> # Wait for multiple possible states
>>> simulation.wait_for_state(['INACTIVE', 'ACTIVE'])
>>> # Custom timeout
>>> simulation.wait_for_state(
...     'ACTIVE',
...     timeout=timedelta(minutes=5),
...     error_states=['INVALID', 'DELETING']
... )

Set when the simulation should be automatically put to sleep (stored).

Accepts any timezone-aware datetime, which will be automatically converted to UTC. Naive datetimes (without timezone) will trigger a warning and assume local timezone.

Parameters:

• sleep_at – Timezone-aware datetime when simulation should sleep, or None to clear. Naive datetimes will assume local timezone and emit a warning.

Example:

>>> from datetime import datetime, timedelta, timezone
# Timezone-aware datetime (recommended):
>>> sleep_time = datetime.now(timezone.utc) + timedelta(hours=1)
>>> simulation.set_sleep_time(sleep_time)
# Naive datetime (triggers warning):
>>> now = datetime.now()
>>> simulation.set_sleep_time(now + timedelta(hours=1))
# Clear sleep time:
>>> simulation.set_sleep_time(None)

Set when the simulation should be automatically deleted.

Accepts any timezone-aware datetime, which will be automatically converted to UTC. Naive datetimes (without timezone) will trigger a warning and assume local timezone.

Parameters:

• expires_at – Timezone-aware datetime when simulation should expire, or None to clear. Naive datetimes will assume local timezone and emit a warning.

Example:

>>> from datetime import datetime, timedelta, timezone
# Timezone-aware datetime (recommended):
>>> expire_time = datetime.now(timezone.utc) + timedelta(hours=2)
>>> simulation.set_expire_time(expire_time)
# Naive datetime (triggers warning):
>>> now = datetime.now()
>>> simulation.set_expire_time(now + timedelta(hours=2))
# Clear expiration time:
>>> simulation.set_expire_time(None)

Create a ZTP (Zero Touch Provisioning) script for the simulation.

Parameters:

• content – The content of the ZTP script

Returns:

The created ZTPScript instance

Example:

>>> script = simulation.create_ztp_script(
...     content='#!/bin/bash\n#CUMULUS-AUTOPROVISIONING\necho "Hello World"'
... )

Update the ZTP script for this simulation.

Parameters:

• content – The new script content

Returns:

The updated ZTPScript instance

Example:

>>> updated_script = simulation.update_ztp_script(
...     content='#!/bin/bash\n#CUMULUS-AUTOPROVISIONING\necho "Updated"'
... )

Delete the ZTP script for this simulation.

After deletion, simulation.ztp_script will return None.

Example:

>>> simulation.delete_ztp_script()
>>> print(simulation.ztp_script)
None

Export the simulation.

Parameters:

• image_ids – Whether to include image IDs in the export. If not specified, the API will use its default behavior.
• topology_format – Format for the topology in the export. If not specified, the API will use its default behavior.

Returns:

Dictionary containing the exported simulation data

Example:

# Export with API defaults:
>>> export_data = simulation.export()
# Export with specific options:
>>> export_data = simulation.export(image_ids=True, topology_format='JSON')

Clone/duplicate the simulation.

Parameters:

• checkpoint – Optional checkpoint ID to clone from. If not specified, Air will find the most recent COMPLETE checkpoint if it exists.
• attempt_start – If the simulation should start immediately after cloning

Returns:

The cloned Simulation instance

Example:

# Simple clone:
>>> cloned_sim = simulation.clone()
# Clone with specific checkpoint:
>>> cloned_sim = simulation.clone(checkpoint='checkpoint-id')
# Clone and start immediately:
>>> cloned_sim = simulation.clone(attempt_start=True)

Get the simulation’s ZTP script if it exists.

Returns:

The ZTPScript instance or None if no script exists

Example:

>>> if script := simulation.ztp_script:
...     print(script.content)

Get the historical entries for the simulation.

Parameters:

• category – Filter by category of the history entries
• actor – Filter by actor who performed the actions
• search – Search term to filter the history entries
• ordering – Order the response by the specified field

Returns:

Iterator of History objects for the simulation

Example:

# Basic usage with ordering:
>>> for history in simulation.get_history(ordering='created'):
...     print(history.description)
# Search and filter:
>>> for history in simulation.get_history(search='OOB', ordering='category'):
...     print(history.description)

Query for the related nodes of the simulation.

Returns:

NodeEndpointAPI instance filtered for this simulation’s nodes

Example:

>>> for node in simulation.nodes.list():
...     print(node.name)

Query for the related interfaces of the simulation.

Returns:

InterfaceEndpointAPI instance filtered for this simulation’s interfaces

Example:

>>> for interface in simulation.interfaces.list():
...     print(interface.name)

Query for the related links of the simulation.

Returns:

LinkEndpointAPI instance filtered for this simulation’s links

Example:

>>> for link in simulation.links.list():
...     print(link.interfaces[0].name, link.interfaces[1].name)

Query for the related node instructions of the simulation.

Returns:

NodeInstructionEndpointAPI filtered for this simulation’s instructions

Example:

>>> for instruction in simulation.node_instructions.list():
...     print(instruction.name, instruction.state)

Query for the related services of the simulation.

Returns:

ServiceEndpointAPI instance filtered for this simulation’s services

Example:

>>> for service in simulation.services.list():
...     print(f'{service.name}: {service.worker_fqdn}:{service.worker_port}')
>>>
>>> # Create service using 'node:interface' string (BC)
>>> service = simulation.services.create(
...     name='SSH', interface='server-1:eth0', dest_port=22
... )

Query for the related checkpoints of the simulation.

Returns:

CheckpointEndpointAPI instance filtered for this simulation’s checkpoints

Example:

>>> for cp in simulation.checkpoints.list():
...     print(cp.name, cp.state)

Create service using node and interface names.

Parameters:

• node_name – Node name in this simulation
• interface_name – Interface name on the node (e.g., ‘eth0’, ‘swp1’)
• node_port – Port number on the node
• name – Service name (optional)
• service_type – Service type - ‘SSH’, ‘HTTPS’, ‘HTTP’, or ‘OTHER’

Returns:

Service object

Raises:

• ValueError – If node or interface not found in simulation

Example:

>>> service = sim.create_service(
...     node_name='server-1',
...     interface_name='eth0',
...     name='SSH Access',
...     node_port=22,
...     service_type='SSH'
... )

Bulk assign configurations to nodes in this simulation.

Parameters:

• nodes – List of node assignment data containing node, user_data, and meta_data

Example:

>>> # Bulk assign cloud-init configs to multiple nodes
>>> simulation.node_bulk_assign(
...     nodes=[
...         {'node': 'node1', 'user_data': 'config1'},
...         {'node': 'node2', 'meta_data': 'config2'},
...     ],
... )

Reset specific nodes within this simulation.

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:

• nodes – List of node reset payloads, each containing a node object or ID

Example:

>>> # Reset a single node
>>> simulation.node_bulk_reset(nodes=[{'id': node.id}])
>>> # Reset multiple nodes using node IDs
>>> simulation.node_bulk_reset(
...     nodes=[
...         {'id': 'node-uuid-1'},
...         {'id': 'node-uuid-2'},
...     ],
... )
>>> # Reset all nodes in simulation
>>> nodes_to_reset = [{'id': n} for n in simulation.nodes.list()]
>>> simulation.node_bulk_reset(nodes=nodes_to_reset)

Rebuild specific nodes within this simulation.

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

Parameters:

• nodes – List of node rebuild payloads, each containing a node object or ID
• checkpoint – Optional checkpoint ID to rebuild from

Example:

>>> # Rebuild a single node
>>> simulation.node_bulk_rebuild(nodes=[{'id': node.id}])
>>> # Rebuild multiple nodes using node IDs
>>> simulation.node_bulk_rebuild(
...     nodes=[
...         {'id': 'node-uuid-1'},
...         {'id': 'node-uuid-2'},
...     ],
... )
>>> # Rebuild all nodes in simulation
>>> nodes_to_rebuild = [{'id': n} for n in simulation.nodes.list()]
>>> simulation.node_bulk_rebuild(nodes=nodes_to_rebuild)

Create a blank simulation.

Parameters:

• name – Name for the new simulation
• sleep_at – When the simulation should be automatically put to sleep
• expires_at – When the simulation should be automatically deleted
• documentation – Documentation/description for the simulation
• metadata – Custom metadata as a JSON string

Returns:

The created Simulation instance

Example:

# Simple creation:
>>> simulation = api.simulations.create(name='My Simulation')
# With expiration and documentation:
>>> from datetime import datetime, timedelta, timezone
>>> expires = datetime.now(timezone.utc) + timedelta(days=7)
>>> simulation = api.simulations.create(
...     name='My Simulation',
...     expires_at=expires,
...     documentation='Test simulation'
... )
# With metadata:
>>> simulation = api.simulations.create(
...     name='My Simulation',
...     metadata='{"env": "staging", "owner": "team-a"}'
... )

Import a simulation from raw data.

Parameters:

• format – Format of the content (‘JSON’ or ‘DOT’)
• content – The topology content (dict for JSON, str for DOT)
• name – Name for the new simulation
• ztp – Optional ZTP script content
• attempt_start – When enabled, waits for the simulation creation to complete and then starts it automatically
• start_timeout – Maximum time to wait for simulation creation (default: 120 seconds)

Returns:

The imported Simulation instance

Example:

# Import from JSON:
>>> simulation = api.simulations.import_from_data(
...     format='JSON', content={'nodes': [...]}, name='My Sim'
... )
# Import and start:
>>> simulation = api.simulations.import_from_data(
...     format='JSON',
...     content={'nodes': [...]},
...     name='My Sim',
...     attempt_start=True
... )
# Import and start with custom timeout:
>>> simulation = api.simulations.import_from_data(
...     format='JSON',
...     content={'nodes': [...]},
...     name='My Sim',
...     attempt_start=True,
...     start_timeout=300
... )

Import simulation from a full JSON manifest file.

The manifest should contain all import parameters including:

• format: ‘JSON’
• name: Simulation name
• content: Topology data (for JSON format: dict with ‘nodes’, ‘links’, ‘oob’)
• ztp: Optional ZTP script content

Parameters:

• simulation_manifest – Full simulation manifest (dict, JSON string, file path, or file handle)
• attempt_start – When enabled, waits for the simulation creation to complete and then starts it automatically
• start_timeout – Maximum time to wait for simulation creation (default: 120 seconds)

Returns:

The created Simulation instance

Raises:

• ValueError – If manifest is missing required fields
• FileNotFoundError – If file path doesn’t exist
• JSONDecodeError – If JSON content is malformed

Example:

# From dict of simulation manifest:
>>> simulation_manifest = {
...     'format': 'JSON',
...     'name': 'My Simulation',
...     'ztp': '#!/bin/bash\necho "ZTP"',
...     'content': {
...         'nodes': {...},
...         'links': [],
...         'oob': True
...     }
... }
>>> simulation = api.simulations.import_from_simulation_manifest(
...     simulation_manifest=simulation_manifest
... )
# With attempt_start:
>>> simulation_manifest = {
...     'format': 'JSON',
...     'name': 'My Simulation',
...     'content': {...}
... }
>>> simulation = api.simulations.import_from_simulation_manifest(
...     simulation_manifest=simulation_manifest,
...     attempt_start=True,
...     start_timeout=300
... )
# From JSON file:
>>> simulation = api.simulations.import_from_simulation_manifest(
...     '/path/to/manifest.json'
... )
# From Path object:
>>> from pathlib import Path
>>> simulation = api.simulations.import_from_simulation_manifest(
...     Path('/path/to/manifest.json')
... )

Import simulation from DOT topology file/content.

Parameters:

• topology_data – DOT topology content (string, file path, Path object, or file handle)
• name – Simulation name. If not provided, defaults to the graph name declared in the DOT content
• ztp – Optional ZTP script content
• attempt_start – When enabled, waits for the simulation creation to complete and then starts it automatically
• start_timeout – Maximum time to wait for simulation creation (default: 120 seconds)

Returns:

The created Simulation instance

Raises:

• ValueError – If content is invalid
• FileNotFoundError – If file path doesn’t exist

Example:

# From DOT string:
>>> dot_content = '''
... graph MyNetwork {
...     "server1" [ os="generic/ubuntu2204" ]
...     "switch1" [ os="cumulus/vx:5.11.0" ]
...     "server1":"eth1" -- "switch1":"swp1"
... }
... '''
>>> simulation = api.simulations.import_from_dot(
...     topology_data=dot_content, name='My Simulation'
... )
# Import and start:
>>> simulation = api.simulations.import_from_dot(
...     topology_data=dot_content,
...     name='My Simulation',
...     attempt_start=True
... )
# Import and start with custom timeout:
>>> simulation = api.simulations.import_from_dot(
...     topology_data=dot_content,
...     name='My Simulation',
...     attempt_start=True,
...     start_timeout=300
... )
# From DOT file path:
>>> simulation = api.simulations.import_from_dot(
...     topology_data='/path/to/topology.dot', name='My Simulation'
... )
# With ZTP script:
>>> simulation = api.simulations.import_from_dot(
...     topology_data=dot_content,
...     name='My Simulation',
...     ztp='#!/bin/bash\necho "ZTP"'
... )

List all simulations with optional filtering.

Args:

auto_oob_enabled: Filter by auto OOB enabled status enable_dhcp: Filter by DHCP enabled status on OOB network id: Filter by simulation ID limit: Number of results to return per page name: Filter by simulation name offset: The initial index from which to return the results ordering: Order objects by field. Prefix with ”-” for desc order search: Search by name state: Filter by simulation state (e.g., ‘ACTIVE’, ‘INACTIVE’, ‘CREATING’, ‘CLONING’, etc.)

Returns:

Iterator of Simulation instances

Example:

>>> # List all simulations
>>> for sim in api.simulations.list():
...     print(sim.name)
        >>> # Filter by state
        >>> for sim in api.simulations.list(state='ACTIVE'):
        ...     print(sim.name)
        >>> # Search by name
        >>> for sim in api.simulations.list(search='my-sim'):
        ...     print(sim.name)
        >>> # Order by name descending
        >>> for sim in api.simulations.list(ordering='-name'):
        ...     print(sim.name)

Get a specific simulation by ID.

Parameters:

• pk – The simulation ID (string or UUID)

Returns:

The Simulation instance

Example:

>>> simulation = api.simulations.get('sim-id')

Update a simulation’s properties.

Parameters:

• simulation – The simulation to update (Simulation object or ID)
• name – New name for the simulation
• sleep_at – When the simulation should be automatically put to sleep
• expires_at – When the simulation should be automatically deleted
• documentation – Documentation/description for the simulation
• metadata – Custom metadata as a JSON string

Returns:

The updated Simulation instance

Example:

# Using Simulation object:
>>> updated_sim = api.simulations.update(
...     simulation=simulation, name='Updated Name'
... )
# Using simulation ID:
>>> updated_sim = api.simulations.update(
...     simulation='sim-123-abc',
...     name='Updated Name',
...     documentation='New docs'
... )
# With metadata:
>>> updated_sim = api.simulations.update(
...     simulation=simulation,
...     metadata='{"env": "production", "version": "1.0"}'
... )

Export a simulation.

Parameters:

• simulation – The simulation to export (Simulation object or simulation ID)
• image_ids – Whether to include image IDs in the export
• topology_format – Format for the topology in the export

Returns:

Dictionary containing the exported simulation data

Example:

# Using Simulation object:
>>> export_data = api.simulations.export(simulation=simulation)
# Using simulation ID:
>>> export_data = api.simulations.export(simulation='sim-123-abc')
# With optional parameters:
>>> export_data = api.simulations.export(
...     simulation=simulation, image_ids=True, topology_format='JSON'
... )

Clone/duplicate a simulation.

Parameters:

• simulation – The simulation to clone (Simulation object or simulation ID)
• checkpoint – Optional checkpoint ID to clone from. If not specified, Air will find the most recent COMPLETE checkpoint if it exists.
• attempt_start – If the simulation should start immediately after cloning

Returns:

The cloned Simulation instance

Example:

# Using Simulation object:
>>> cloned_sim = api.simulations.clone(simulation=sim)
# Using simulation ID:
>>> cloned_sim = api.simulations.clone(simulation='sim-123-abc')
# Clone with checkpoint:
>>> cloned_sim = api.simulations.clone(
...     simulation=sim, checkpoint='checkpoint-id'
... )
# Clone and start immediately:
>>> cloned_sim = api.simulations.clone(simulation=sim, attempt_start=True)

Enable automatic Out-of-band management for a simulation.

Parameters:

• simulation – The simulation object or simulation ID
• enable_dhcp – If True, enable DHCP on the OOB management network. If False, disable DHCP on the OOB network.

Example:

# Enable OOB with DHCP (using simulation object):
>>> api.simulations.enable_auto_oob(simulation=simulation)
# Enable OOB using simulation ID:
>>> api.simulations.enable_auto_oob(simulation='uuid-123')
# Enable OOB without DHCP:
>>> api.simulations.enable_auto_oob(
...     simulation=simulation, enable_dhcp=False
... )

Disable automatic Out-of-band management for a simulation.

Parameters:

• simulation – The simulation object or simulation ID

Example:

# Using simulation object:
>>> api.simulations.disable_auto_oob(simulation=simulation)
# Using simulation ID:
>>> api.simulations.disable_auto_oob(simulation='uuid-123')

Start a simulation.

Parameters:

• simulation – The simulation object or simulation ID to start
• checkpoint – Optional checkpoint ID to start from. If not specified, the API will use its default behavior (typically uses the most recent checkpoint if available). If explicitly set to None, starts from clean state (rebuild). If a string, starts from the specified checkpoint.

Example:

# Normal start (API determines behavior):
>>> api.simulations.start(simulation=simulation)
# Start using simulation ID:
>>> api.simulations.start(simulation='uuid-123')
# Start from specific checkpoint:
>>> api.simulations.start(simulation=simulation, checkpoint='checkpoint-id')
# Rebuild (start from clean state, no checkpoint):
>>> api.simulations.start(simulation=simulation, checkpoint=None)

Rebuild a simulation from a given checkpoint.

Tears down the simulation and starts it from the given checkpoint. If no checkpoint is provided, the simulation will be rebuilt from the clean state.

Parameters:

• simulation – The simulation object or simulation ID to rebuild
• checkpoint – Optional checkpoint ID to rebuild from. If not specified, the API will use its default behavior (the current checkpoint the simulation is running off of). If explicitly set to None, starts from clean state (rebuild). If a string, starts from the specified checkpoint.

Example:

# Rebuild simulation from specific checkpoint:
>>> api.simulations.rebuild(simulation=simulation, checkpoint='checkpoint-id')
# Rebuild from clean state (no checkpoint):
>>> api.simulations.rebuild(simulation=simulation, checkpoint=None)
# Rebuild using simulation ID:
>>> api.simulations.rebuild(simulation='uuid-123')

Shut down a simulation.

Parameters:

• simulation – The simulation object or simulation ID to shut down
• create_checkpoint – Whether to create a checkpoint before shutting down. If not specified, the API will use its default behavior.

Example:

# Normal shutdown (API determines behavior):
>>> api.simulations.shutdown(simulation=simulation)
# Shutdown using simulation ID:
>>> api.simulations.shutdown(simulation='uuid-123')
# Explicitly create checkpoint before shutdown:
>>> api.simulations.shutdown(simulation=simulation, create_checkpoint=True)
# Explicitly don't create checkpoint:
>>> api.simulations.shutdown(simulation=simulation, create_checkpoint=False)

Create service for a simulation by resolving node and interface names.

Parameters:

• simulation – Simulation ID or object
• node_name – Node name in the simulation
• interface_name – Interface name on the node (e.g., ‘eth0’, ‘swp1’)
• node_port – Port number on the node
• name – Service name (optional)
• service_type – Service type - ‘SSH’, ‘HTTPS’, ‘HTTP’, or ‘OTHER’

Returns:

Service object

Raises:

• ValueError – If node or interface not found in simulation

Example:

>>> service = api.simulations.create_service(
...     simulation='sim-id',
...     node_name='server-1',
...     interface_name='eth0',
...     node_port=22,
...     service_type='SSH'
... )

Parse topology content between different formats.

Convert topology data between different formats (e.g., DOT to JSON).

Parameters:

• topology_data – The topology content to parse
• source_format – The format to parse the topology from (e.g., ‘DOT’).
• destination_format – The format to parse the topology to (e.g., ‘JSON’).

Returns:

Parsed topology data as a dictionary

Example:

>>> dot_content = '''
... graph MyNetwork {
...     "node-1" [ os="generic/ubuntu2204" cpu=2 ]
...     "node-2" [ os="generic/ubuntu2204" memory=2048 ]
...     "node-1":"eth1" -- "node-2":"eth1"
... }
... '''
>>> # Convert DOT to JSON
>>> parsed = api.simulations.parse(
...     topology_data=dot_content,
...     source_format='DOT',
...     destination_format='JSON',
... )

Bulk assign configurations to nodes in given simulation.

Parameters:

• simulation – The simulation to bulk assign to
• nodes – List of node assignment data containing node, user_data, and meta_data

Example:

>>> # Bulk assign cloud-init configs to multiple nodes
>>> api.simulations.node_bulk_assign(
...     simulation=simulation,
...     nodes=[
...         {'node': 'node1', 'user_data': 'config1'},
...         {'node': 'node2', 'meta_data': 'config2'},
...     ],
... )