Air APIAPI ReferenceSimulations

Begins shutting down the simulation

View as Markdown
This endpoint is used to shut down a simulation. By default, the simulation will save its progress as a new checkpoint and perform the following state transitions: `ACTIVE` -> `PREPARE_SHUTDOWN` -> `SHUTTING_DOWN` -> `SAVING` -> `INACTIVE`. If necessary, Air may delete an existing checkpoint of your simulation to make room for the newly created checkpoint; if this happens, Air will prefer to keep favorited checkpoints over non-favorited checkpoints and more recently created checkpoints over older checkpoints. If `create_checkpoint` is set to false in the payload, the simulation will not create a checkpoint and will instead perform the following state transitions: `ACTIVE` -> `PREPARE_PURGE` -> `PURGING` -> `INACTIVE`. **Required scope:** `air:simulation_start_stop` (roles: `air_org_admin`, `air_user`) **Alternative:** role `air_trainee` also grants access.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idstringRequiredformat: "uuid"
A UUID string identifying this simulation.

Request

This endpoint expects an object.
create_checkpointbooleanOptionalDefaults to true

If a new checkpoint should be created when shutting down the simulation. When true, the simulation will shut down and enter a temporary SAVING state while the checkpoint is getting saved; if necessary, Air may delete an existing checkpoint of your simulation to make room in storage for the newly created checkpoint. If false, the simulation will be purged from the workers and updates applied to the simulation from its current run will be lost; previously saved checkpoints will not be affected.

Response

idstringRead-onlyformat: "uuid"
createddatetimeRead-only
modifieddatetimeRead-only
namestring<=128 characters
stateenum
  • CLONING - Cloning
  • CREATING - Creating
  • IMPORTING - Importing
  • INVALID - Invalid
  • INACTIVE - Inactive
  • REQUESTING - Requesting
  • PENDING - Pending
  • PROVISIONING - Provisioning
  • PREPARE_BOOT - Prepare to boot
  • BOOTING - Booting
  • ACTIVE - Active
  • PREPARE_SHUTDOWN - Prepare to shutdown
  • SHUTTING_DOWN - Shutting down
  • SAVING - Saving
  • DELETING - Deleting
  • PREPARE_PURGE - Prepare to purge
  • PURGING - Purging
  • DEMO - Demo
  • TRAINING - Training
  • PREPARE_REBUILD - Prepare to rebuild
  • REBUILDING - Rebuilding
  • ADMIN_SUSPENDED - Admin suspended
auto_oob_enabledboolean or nullRead-only
If OOB should be automatically configured.
enable_dhcpboolean or nullRead-only

If DHCP should be enabled on the oob-mgmt-server for simulations with automatic OOB enabled.

creatorstringRead-only
The email of the user who created the simulation
assigned_tostring or nullRead-only
The email of the user who is assigned to the simulation during a Training event.
documentationstring or nullRead-only

The raw markdown documentation associated with the simulation, if any. This is populated for simulations provisioned from a marketplace demo, sharing the same content as the demo. It cannot be edited directly on the simulation — edit the marketplace demo’s documentation instead.

complete_checkpoint_countintegerRead-only

The number of complete checkpoints in the simulation. When a sim has complete checkpoints, nodes/interfaces cannot be modified, created, or deleted.

sleep_atdatetime or nullOptional

When the simulation should be automatically put to sleep. For organizations on a free trial of DSX Air, this defaults to 24 hours after the simulation was started; if the simulation has not yet started this value will default to null and will be updated when the simulation starts. For all other organizations, this defaults to null. NVIDIA users using the internal deployment of DSX Air may set this value to null even when on a free trial. Users on a free trial of the public deployment of DSX Air may not set this value to null and may not set this value to exceed 72 hours in the future.

expires_atdatetime or nullOptional
When the simulation should be automatically deleted.
metadatastring or nullOptional<=1048576 characters
Custom metadata as a JSON string. This field does not affect the runtime of the simulation. It is provided for clients to store metadata about the simulation for their own purposes.
user_notesstringOptional<=4096 characters

Free-text notes about the simulation recorded by the user.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error