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

# Begins shutting down the simulation

PATCH https://api.dsx-air.nvidia.com/api/v3/simulations/{id}/shutdown/
Content-Type: application/json

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.

Reference: https://docs.nvidia.com/dsx-air/api-reference/simulations/api-v-3-simulations-shutdown-partial-update

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `id` (string, required) — A UUID string identifying this simulation.

### Body (application/json)

This endpoint expects an object.

- `create_checkpoint` (boolean, optional, default: 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

### 200

- `id` (string, required)
- `created` (datetime, required)
- `modified` (datetime, required)
- `name` (string, required)
- `state` (enum, required) — * `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
  - Allowed values: `CLONING`, `CREATING`, `IMPORTING`, `INVALID`, `INACTIVE`, `REQUESTING`, `PENDING`, `PROVISIONING`, `PREPARE_BOOT`, `BOOTING`, `ACTIVE`, `PREPARE_SHUTDOWN`, `SHUTTING_DOWN`, `SAVING`, `DELETING`, `PREPARE_PURGE`, `PURGING`, `DEMO`, `TRAINING`, `PREPARE_REBUILD`, `REBUILDING`, `ADMIN_SUSPENDED`
- `auto_oob_enabled` (boolean, required, nullable) — If OOB should be automatically configured.
- `enable_dhcp` (boolean, required, nullable) — If DHCP should be enabled on the oob-mgmt-server for simulations with automatic OOB enabled.
- `creator` (string, required) — The email of the user who created the simulation
- `assigned_to` (string, required, nullable) — The email of the user who is assigned to the simulation during a Training event.
- `documentation` (string, required, nullable) — 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_count` (integer, required) — The number of complete checkpoints in the simulation. When a sim has complete checkpoints, nodes/interfaces cannot be modified, created, or deleted.
- `sleep_at` (datetime, optional, nullable) — 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_at` (datetime, optional, nullable) — When the simulation should be automatically deleted.
- `metadata` (string, optional, nullable) — 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_notes` (string, optional) — Free-text notes about the simulation recorded by the user.

## Errors

### 400 Bad Request Error

- `detail` (string, required) — Description of an error.
- `request_id` (string, required, nullable) — ID assigned to the request which encountered the error. Should be provided when opening a support case.
- `type` (enum, required) — Specific type of a 400 error. * `PROTECTED` - Instance may not be deleted as it is being referenced by other instances. * `VALIDATION` - Validation errors encountered during payload processing.
  - Allowed values: `PROTECTED`, `VALIDATION`
- `protected_instances` (list of object, optional) — Instances which bar the current instance from being deleted. Only defined when `type` is set to `PROTECTED`.
  - `id` (string, required) — ID of the instance.
  - `type` (string, required) — Type of the instance.
- `validation_errors` (map from string to list of object or object or map from string to any or list of object, optional) — Validation errors encountered during payload processing. Only defined when `type` is set to `VALIDATION`.

### 403 Forbidden Error

- `detail` (string, required) — Description of an error.
- `request_id` (string, required, nullable) — ID assigned to the request which encountered the error. Should be provided when opening a support case.

### 404 Not Found Error

- `request_id` (string, required, nullable) — ID assigned to the request which encountered the error. Should be provided when opening a support case.
- `detail` (string, optional, default: No object matches the given query.) — Description of an error.

### 500 Internal Server Error

- `request_id` (string, required, nullable) — ID assigned to the request which encountered the error. Should be provided when opening a support case.
- `code` (string, required) — Error code which identifies the error. Should be provided when opening a support case.
- `detail` (string, optional, default: An unexpected error has occurred. Please contact NVIDIA Air support for further assistance.) — Description of an error.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "id": "string",
  "created": "2024-01-15T09:30:00Z",
  "modified": "2024-01-15T09:30:00Z",
  "name": "string",
  "state": "CLONING",
  "auto_oob_enabled": true,
  "enable_dhcp": true,
  "creator": "string",
  "assigned_to": "string",
  "documentation": "string",
  "complete_checkpoint_count": 1,
  "sleep_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "metadata": "string",
  "user_notes": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.dsx-air.nvidia.com/api/v3/simulations/id/shutdown/"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.dsx-air.nvidia.com/api/v3/simulations/id/shutdown/';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dsx-air.nvidia.com/api/v3/simulations/id/shutdown/"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.dsx-air.nvidia.com/api/v3/simulations/id/shutdown/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.dsx-air.nvidia.com/api/v3/simulations/id/shutdown/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.dsx-air.nvidia.com/api/v3/simulations/id/shutdown/', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.dsx-air.nvidia.com/api/v3/simulations/id/shutdown/");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.dsx-air.nvidia.com/api/v3/simulations/id/shutdown/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```