> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo-platform/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo-platform/_mcp/server.

# Create ModelDeploymentConfig

POST /apis/models/v2/workspaces/{workspace}/deployment-configs
Content-Type: application/json

Create a new ModelDeploymentConfig (version 1).

Reference: https://docs.nvidia.com/nemo-platform/nemo-platform/v0.3.0/documentation/reference/api-reference/model-deployment-configs/create-deployment-config-apis-models-v-2-workspaces-workspace-deployment-configs-post

## Request

### Path parameters

- `workspace` (string, required)

### Body (application/json)

- `name` (string, required) — Name of the deployment configuration. Name must start with a lowercase letter, be 2-63 characters, and use lowercase letters, digits, hyphens, and dots (no consecutive hyphens, cannot end with a hyphen).
- `engine` (enum, required) — Inference engine selecting the compiler path (nim/vllm/generic)
  - Allowed values: `nim`, `vllm`, `generic`
- `model_spec` (object, required) — What model to serve and how -- independent of the executor it runs on
  - `model_type` (enum, optional) — Type of model being deployed
    - Allowed values: `llm`, `embed`, `other`
  - `model_namespace` (string, optional) — Model repository namespace - organization/user namespace as it exists in repo_id.
  - `model_name` (string, optional) — Model name - model repository name for model weights.
  - `model_revision` (string, optional) — Model revision (branch, tag, or commit). If not specified, parsed from model_name @revision suffix or defaults to 'main'
  - `chat_template` (string, optional) — Jinja2 chat template string for the model. Overrides the chat_template from ModelEntity.spec if both are set. Used by the engine to format chat completions.
  - `tool_call_config` (object, optional) — Tool calling configuration for the deployment. Overrides tool_call_config from ModelEntity.spec if both are set. Controls how the model handles function/tool calling.
    - `tool_call_parser` (string, optional) — Name of the tool call parser to use (e.g., 'openai', 'hermes', 'pythonic', 'llama3_json', 'mistral').
    - `tool_call_plugin` (string, optional) — Reference to a fileset containing the custom tool call plugin Python file. Expected format: '\{workspace}/\{fileset\_name}'. The fileset is mounted separately from the model checkpoint at deployment time.
    - `auto_tool_choice` (boolean, optional) — Whether to enable automatic tool choice. When enabled, the model can decide to call tools without explicit user instruction.
  - `lora_enabled` (boolean, optional, default: false) — Whether to enable LoRA support
- `executor_config` (object, required) — Compute + container settings for the executor the deployment runs on
  - `gpu` (integer, required) — Number of GPUs required for the deployment. 0 = CPU-only.
  - `disk_size` (string, optional, default: 50Gi) — Disk size for the deployment
  - `image_name` (string, optional) — Container image name. If not specified, defaults to the engine's configured image (e.g. default_vllm_image / default_nimservice_image). Required for engine='generic'.
  - `image_tag` (string, optional) — Container image tag. If not specified, defaults to the engine's configured image tag.
  - `health_check_path` (string, optional) — HTTP path used for the container readiness probe. If not specified, defaults to the engine's standard health endpoint (e.g. '/v1/health/ready' for NIM, '/health' for vLLM). Set this for engine='generic' containers that expose a non-standard health endpoint.
  - `run_as_user` (integer, optional) — Pod securityContext runAsUser (uid) for the serving container (k8s backend only). If unset, the engine default applies (vLLM pins its image's user; generic uses the image's own user). Ignored by the docker backend.
  - `run_as_group` (integer, optional) — Pod securityContext runAsGroup (gid) for the serving container (k8s backend only). If unset, the engine default applies. Ignored by the docker backend.
  - `additional_envs` (map from string to string, optional) — Additional environment variables for the deployment
  - `additional_args` (list of string, optional) — Raw container/`serve` args appended verbatim to the container's arg vector.
  - `k8s_nim_operator_config` (object, optional) — Typed Kubernetes configuration for common NIMService Spec fields (NIM engine on k8s). Applied after defaults but before override_config. Ignored by non-NIM engines.
    - `resources` (map from string to any, optional) — Kubernetes resource requirements including requests and limits. Example: \{'requests': \{'cpu': '2', 'memory': '8Gi'}, 'limits': \{'memory': '16Gi'}}
    - `tolerations` (list of map from string to any, optional) — Kubernetes tolerations for pod scheduling. Example: \[\{'key': 'nvidia.com/gpu', 'operator': 'Exists', 'effect': 'NoSchedule'}]
    - `node_selector` (map from string to string, optional) — Kubernetes node selector for pod placement. Example: \{'node-type': 'gpu-node', 'zone': 'us-west1-a'}
    - `startup_probe_grace_seconds` (integer, optional) — Grace period in seconds for NIM startup. Determines how long Kubernetes will wait for the NIM to become ready before restarting it. Example: 600 (10 minutes). Must be a positive integer.
  - `override_config` (map from string to any, optional) — Partial NIMService Spec fragments deep-merged after generated defaults and k8s_nim_operator_config (NIM engine on k8s only). Supported keys: image, command, args, resources, env, readinessProbe, livenessProbe, startupProbe, nodeSelector, tolerations, userID, groupID, labels, initContainers, sidecarContainers. Unsupported keys are rejected at compile time. Ignored by non-NIM engines and docker runtime.
- `project` (string, optional) — The URN of the project associated with this deployment configuration
- `description` (string, optional) — Optional description of the deployment configuration
- `model_entity_id` (string, optional) — Optional reference to the base model entity ID for this deployment

## Response

### 201

Create a new model deployment configuration

- `name` (string, required) — Name of the entity. Name/workspace combo must be unique across all entities. Name must start with a lowercase letter, be 2-63 characters, and use lowercase letters, digits, hyphens, and dots (no consecutive hyphens, cannot end with a hyphen).
- `workspace` (string, required) — The workspace of the entity. Allowed characters: letters (a-z, A-Z), digits (0-9), underscores, hyphens, and dots.
- `created_at` (datetime, required) — The timestamp of model entity creation
- `updated_at` (datetime, required) — The timestamp of the last model entity update
- `entity_version` (integer, required) — Version of this deployment config. Automatically managed.
- `engine` (enum, required) — Inference engine selecting the compiler path (nim/vllm/generic)
  - Allowed values: `nim`, `vllm`, `generic`
- `model_spec` (object, required) — What model to serve and how -- independent of the executor it runs on
  - `model_type` (enum, optional) — Type of model being deployed
    - Allowed values: `llm`, `embed`, `other`
  - `model_namespace` (string, optional) — Model repository namespace - organization/user namespace as it exists in repo_id.
  - `model_name` (string, optional) — Model name - model repository name for model weights.
  - `model_revision` (string, optional) — Model revision (branch, tag, or commit). If not specified, parsed from model_name @revision suffix or defaults to 'main'
  - `chat_template` (string, optional) — Jinja2 chat template string for the model. Overrides the chat_template from ModelEntity.spec if both are set. Used by the engine to format chat completions.
  - `tool_call_config` (object, optional) — Tool calling configuration for the deployment. Overrides tool_call_config from ModelEntity.spec if both are set. Controls how the model handles function/tool calling.
    - `tool_call_parser` (string, optional) — Name of the tool call parser to use (e.g., 'openai', 'hermes', 'pythonic', 'llama3_json', 'mistral').
    - `tool_call_plugin` (string, optional) — Reference to a fileset containing the custom tool call plugin Python file. Expected format: '\{workspace}/\{fileset\_name}'. The fileset is mounted separately from the model checkpoint at deployment time.
    - `auto_tool_choice` (boolean, optional) — Whether to enable automatic tool choice. When enabled, the model can decide to call tools without explicit user instruction.
  - `lora_enabled` (boolean, optional, default: false) — Whether to enable LoRA support
- `executor_config` (object, required) — Compute + container settings for the executor the deployment runs on
  - `gpu` (integer, required) — Number of GPUs required for the deployment. 0 = CPU-only.
  - `disk_size` (string, optional, default: 50Gi) — Disk size for the deployment
  - `image_name` (string, optional) — Container image name. If not specified, defaults to the engine's configured image (e.g. default_vllm_image / default_nimservice_image). Required for engine='generic'.
  - `image_tag` (string, optional) — Container image tag. If not specified, defaults to the engine's configured image tag.
  - `health_check_path` (string, optional) — HTTP path used for the container readiness probe. If not specified, defaults to the engine's standard health endpoint (e.g. '/v1/health/ready' for NIM, '/health' for vLLM). Set this for engine='generic' containers that expose a non-standard health endpoint.
  - `run_as_user` (integer, optional) — Pod securityContext runAsUser (uid) for the serving container (k8s backend only). If unset, the engine default applies (vLLM pins its image's user; generic uses the image's own user). Ignored by the docker backend.
  - `run_as_group` (integer, optional) — Pod securityContext runAsGroup (gid) for the serving container (k8s backend only). If unset, the engine default applies. Ignored by the docker backend.
  - `additional_envs` (map from string to string, optional) — Additional environment variables for the deployment
  - `additional_args` (list of string, optional) — Raw container/`serve` args appended verbatim to the container's arg vector.
  - `k8s_nim_operator_config` (object, optional) — Typed Kubernetes configuration for common NIMService Spec fields (NIM engine on k8s). Applied after defaults but before override_config. Ignored by non-NIM engines.
    - `resources` (map from string to any, optional) — Kubernetes resource requirements including requests and limits. Example: \{'requests': \{'cpu': '2', 'memory': '8Gi'}, 'limits': \{'memory': '16Gi'}}
    - `tolerations` (list of map from string to any, optional) — Kubernetes tolerations for pod scheduling. Example: \[\{'key': 'nvidia.com/gpu', 'operator': 'Exists', 'effect': 'NoSchedule'}]
    - `node_selector` (map from string to string, optional) — Kubernetes node selector for pod placement. Example: \{'node-type': 'gpu-node', 'zone': 'us-west1-a'}
    - `startup_probe_grace_seconds` (integer, optional) — Grace period in seconds for NIM startup. Determines how long Kubernetes will wait for the NIM to become ready before restarting it. Example: 600 (10 minutes). Must be a positive integer.
  - `override_config` (map from string to any, optional) — Partial NIMService Spec fragments deep-merged after generated defaults and k8s_nim_operator_config (NIM engine on k8s only). Supported keys: image, command, args, resources, env, readinessProbe, livenessProbe, startupProbe, nodeSelector, tolerations, userID, groupID, labels, initContainers, sidecarContainers. Unsupported keys are rejected at compile time. Ignored by non-NIM engines and docker runtime.
- `id` (string, optional) — Unique identifier for the deployment config
- `project` (string, optional) — The URN of the project associated with this entity.
- `description` (string, optional) — Optional description of the deployment configuration
- `model_entity_id` (string, optional) — Optional reference to the base model entity ID for this deployment

## Examples

**Request**

```json
{
  "name": "nim-config-v1",
  "engine": "nim",
  "executor_config": {
    "gpu": 1
  }
}
```

**Response**

```json
{
  "name": "llama-3.1-8b",
  "workspace": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "entity_version": 1,
  "engine": "nim",
  "model_spec": {
    "model_type": "llm",
    "model_namespace": "string",
    "model_name": "string",
    "model_revision": "string",
    "chat_template": "string",
    "tool_call_config": {
      "tool_call_parser": "string",
      "tool_call_plugin": "string",
      "auto_tool_choice": true
    },
    "lora_enabled": false
  },
  "executor_config": {
    "gpu": 1,
    "disk_size": "50Gi",
    "image_name": "string",
    "image_tag": "string",
    "health_check_path": "string",
    "run_as_user": 1,
    "run_as_group": 1,
    "additional_envs": {},
    "additional_args": [
      "string"
    ],
    "k8s_nim_operator_config": {
      "resources": {},
      "tolerations": [
        {}
      ],
      "node_selector": {},
      "startup_probe_grace_seconds": 1
    },
    "override_config": {}
  },
  "id": "string",
  "project": "string",
  "description": "string",
  "model_entity_id": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.example.com/apis/models/v2/workspaces/workspace/deployment-configs"

payload = {
    "name": "nim-config-v1",
    "engine": "nim",
    "executor_config": { "gpu": 1 }
}
headers = {"Content-Type": "application/json"}

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

print(response.json())
```

```javascript
const url = 'https://api.example.com/apis/models/v2/workspaces/workspace/deployment-configs';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"name":"nim-config-v1","engine":"nim","executor_config":{"gpu":1}}'
};

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.example.com/apis/models/v2/workspaces/workspace/deployment-configs"

	payload := strings.NewReader("{\n  \"name\": \"nim-config-v1\",\n  \"engine\": \"nim\",\n  \"executor_config\": {\n    \"gpu\": 1\n  }\n}")

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

	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.example.com/apis/models/v2/workspaces/workspace/deployment-configs")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"nim-config-v1\",\n  \"engine\": \"nim\",\n  \"executor_config\": {\n    \"gpu\": 1\n  }\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.example.com/apis/models/v2/workspaces/workspace/deployment-configs")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"nim-config-v1\",\n  \"engine\": \"nim\",\n  \"executor_config\": {\n    \"gpu\": 1\n  }\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.example.com/apis/models/v2/workspaces/workspace/deployment-configs', [
  'body' => '{
  "name": "nim-config-v1",
  "engine": "nim",
  "executor_config": {
    "gpu": 1
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.example.com/apis/models/v2/workspaces/workspace/deployment-configs");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"nim-config-v1\",\n  \"engine\": \"nim\",\n  \"executor_config\": {\n    \"gpu\": 1\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = [
  "name": "nim-config-v1",
  "engine": "nim",
  "executor_config": ["gpu": 1]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/apis/models/v2/workspaces/workspace/deployment-configs")! 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()
```