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

# Clone a simulation

POST https://api.dsx-air.nvidia.com/api/v3/simulations/clone/
Content-Type: application/json

Cloning a simulation will create a new replica of the simulation which is completely independent of the original simulation. 

An optional `checkpoint` value may be specified in the payload in order to copy a checkpoint from the original simulation onto the new simulation. If `checkpoint` is excluded from the payload, the most recent checkpoint of the simulation will be used; if the `null` value is provided, no checkpoint will be used and the simulation will perform an initial boot the first time it is started. 

If you would like to attempt to start the new sim immediately after cloning, provide true for the `attempt_start` value in your payload; even if `attempt_start` is set to true, the sim may not start if Air or your organization does not have sufficient credit/resources. The `attempt_start` option does not apply for simulations being cloned to a demo. 

An optional `name` value may be provided in the payload to set the name of the new simulation. If omitted, the new simulation will inherit the name of the original simulation.

**Required scope:** `air:simulation_create` (roles: `air_org_admin`, `air_user`)

Reference: https://docs.nvidia.com/dsx-air/api-reference/simulations/api-v-3-simulations-clone-create

## Authentication

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

## Request

### Body (application/json)

This endpoint expects an object.

- `simulation` (string, required) — A simulation to clone from; must be in the `INACTIVE` or `CLONING` state.
- `checkpoint` (string, optional, nullable) — A `COMPLETE` checkpoint to clone from. If `null`, Air will not transfer a checkpoint.If not specified, Air will find the most recent COMPLETE if it exists. If no checkpoint exists, no checkpoint will be transferred.
- `attempt_start` (boolean, optional, default: false) — If the simulation should request to start immediately after cloning. The request to start will always be honored, but the start request may be rejected depending on Air/organization credits/resources. Attempts to start do not apply for simulations being cloned to a demo.
- `name` (string, optional) — An optional name for the new simulation. If omitted, the new simulation will inherit the name of the original simulation.

## Response

### 201

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

### 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
{
  "simulation": "string"
}
```

**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/clone/"

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

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

print(response.json())
```

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

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/clone/"

	payload := strings.NewReader("{\n  \"simulation\": \"string\"\n}")

	req, _ := http.NewRequest("POST", 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/clone/")

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

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

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.post("https://api.dsx-air.nvidia.com/api/v3/simulations/clone/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"simulation\": \"string\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.dsx-air.nvidia.com/api/v3/simulations/clone/', [
  'body' => '{
  "simulation": "string"
}',
  '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/clone/");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"simulation\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["simulation": "string"] 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/clone/")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()
```