> This page is for Self-Hosted, version v3.0 (default).
> For other versions, use one of these documentation indexes:
> - v3.0 (default): https://docs.nvidia.com/run-ai/self-hosted/v3.0/llms.txt
> - v2.26: https://docs.nvidia.com/run-ai/self-hosted/v2.26/llms.txt
> - v2.25: https://docs.nvidia.com/run-ai/self-hosted/v2.25/llms.txt
> - v2.24: https://docs.nvidia.com/run-ai/self-hosted/v2.24/llms.txt

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

# Update workload spec.

PUT http://localhost:8080/api/v2/workloads/{WorkloadV2Id}
Content-Type: application/json

Update the specification of an existing workload.

Reference: https://docs.nvidia.com/run-ai/self-hosted/reference/rest-api/endpoints/workloads/workloads-v-2/update-workload-v-2

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication

## Request

### Path parameters

- `WorkloadV2Id` (string, required)

### Body (application/json)

This endpoint expects a WorkloadV2UpdateRequest.

- `metadata` (WorkloadV2MetadataUpdateParams, optional)
- `manifest` (map from string to any, optional) — The full Kubernetes manifest for the workload in JSON form. Mutually exclusive with manifestEncodedBase64.
- `manifestBase64Encoded` (string, optional) — Kubernetes YAML manifest encoded in base 64. Mutually exclusive with manifest.

## Response

### 202

Workload update request accepted

- `metadata` (WorkloadV2Metadata, required)
- `desiredPhase` (enum, required) — The desired phase of the workload.
  - Allowed values: `Running`, `Stopped`, `Deleted`
- `workloadManifest` (map from string to any, required) — The full Kubernetes manifest for the workload in JSON form. Mutually exclusive with manifestEncodedBase64.
- `rawManifest` (map from string to any, required) — The full Kubernetes manifest for the workload in JSON form. Mutually exclusive with manifestEncodedBase64.

## Errors

### 401 Unauthorized Error

Unauthorized

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 403 Forbidden Error

Forbidden

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 404 Not Found Error

The specified resource was not found

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 500 Internal Server Error

unexpected error

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 503 Service Unavailable Error

unexpected error

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

## Types

### WorkloadV2MetadataUpdateParams

- `priority` (string, optional) — Specifies the priority class for the workload, which determines its scheduling behavior. Valid values are: very-low, low, medium-low, medium, medium-high, high, and very-high. Each workload type has a default priority. To view the default priority for each workload type, use the GET /workload-types endpoint. Once you change the priority from the default value defined for that workload type, the preemptibility field is not automatically updated. Make sure to set the desired preemptibility value.
- `category` (string, optional) — Specify the workload category assigned to the workload. Categories are used to classify and monitor different types of workloads within the NVIDIA Run:ai platform.
- `configuration` (WorkloadV2Configuration, optional, nullable) — Specifies the features configuration to apply to a workload.

### WorkloadV2Metadata

- `name` (string, required) — The name of the workload.
- `projectId` (string, required) — The id of the project.
- `id` (string, required) — A unique ID of the workload.
- `gvk` (GVK, required) — Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload.
- `projectName` (string, required) — The name of the project
- `clusterId` (string, required) — The id of the cluster.
- `tenantId` (integer, required) — The id of the tenant.
- `departmentId` (string, required) — The id of the department.
- `departmentName` (string, required) — The name of the department
- `createdAt` (datetime, required) — The timestamp for when the workload was created.
- `createdBy` (string, required) — Identifier of the user who created the workload.
- `updatedAt` (datetime, required) — The timestamp for the last time the workload was updated.
- `updatedBy` (string, required) — Identifier of the user who last updated the workload.
- `priority` (string, optional) — Specifies the priority class for the workload, which determines its scheduling behavior. Valid values are: very-low, low, medium-low, medium, medium-high, high, and very-high. Each workload type has a default priority. To view the default priority for each workload type, use the GET /workload-types endpoint. Once you change the priority from the default value defined for that workload type, the preemptibility field is not automatically updated. Make sure to set the desired preemptibility value.
- `category` (string, optional) — Specify the workload category assigned to the workload. Categories are used to classify and monitor different types of workloads within the NVIDIA Run:ai platform.
- `preemptibility` (enum, optional) — Specifies whether the workload can be preempted by higher-priority workloads. Valid values are preemptible, semi-preemptible and non-preemptible. If explicitly set, this value takes precedence. If not set, the system derives the preemptibility from the priorityClassName field, ensuring backward compatibility. Each workload type has a default preemptibility. To view the default preemptibility for each workload type, use the GET /workload-types endpoint.
  - Allowed values: `preemptible`, `semi-preemptible`, `non-preemptible`
- `configuration` (WorkloadV2Configuration, optional) — Specifies the features configuration to apply to a workload.
- `deletedAt` (datetime, optional, nullable) — The timestamp indicating when the workload was deleted.
- `deletedBy` (string, optional, nullable) — Identifier of the user who deleted the workload.

### WorkloadV2Configuration

Specifies the features configuration to apply to a workload.

- `mnnvl` (string, optional, nullable)
- `userCredentials` (WorkloadV2UpdateConfigurationUserCredentials, optional) — User credentials to make available to the workload. Each entry references a user-created credential by name. User credentials can only be accessed by the user who created them.

### GVK

Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload.

- `version` (string, required) — The API version of the resource within the specified group.
- `kind` (string, required) — The type of Kubernetes resource being referenced.
- `group` (string, optional, nullable) — The API group of the Kubernetes resource. Empty string for core resources like Pod.

### WorkloadV2UpdateConfigurationUserCredentials

User credentials to make available to the workload. Each entry references a user-created credential by name. User credentials can only be accessed by the user who created them.

- `sources` (list of WorkloadV2UpdateConfigurationUserCredentialSource, optional) — List of user credentials to make available to the workload.

### WorkloadV2UpdateConfigurationUserCredentialSource

- `ref` (string, required) — The name of the user credential.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "metadata": {
    "name": "my-workload-name",
    "projectId": "1",
    "id": "string",
    "gvk": {
      "version": "v1",
      "kind": "Deployment",
      "group": "apps"
    },
    "projectName": "project-a",
    "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
    "tenantId": 1001,
    "departmentId": "2",
    "departmentName": "default",
    "createdAt": "2024-01-15T10:30:00Z",
    "createdBy": "user@run.ai",
    "updatedAt": "2024-01-15T10:35:00Z",
    "updatedBy": "user@run.ai",
    "priority": "string",
    "category": "string",
    "preemptibility": "preemptible",
    "configuration": {
      "mnnvl": "string",
      "userCredentials": {
        "sources": [
          {
            "ref": "my-hf-token-abc1234567"
          }
        ]
      }
    },
    "deletedAt": "2024-01-15T10:35:00Z",
    "deletedBy": "user@run.ai"
  },
  "desiredPhase": "Running",
  "workloadManifest": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "my-app"
    },
    "spec": {
      "replicas": 1,
      "selector": {
        "matchLabels": {
          "app": "my-app"
        }
      },
      "template": {
        "metadata": {
          "labels": {
            "app": "my-app"
          }
        },
        "spec": {
          "containers": [
            {
              "image": "nginx:latest",
              "name": "app"
            }
          ]
        }
      }
    }
  },
  "rawManifest": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "my-app"
    },
    "spec": {
      "replicas": 1,
      "selector": {
        "matchLabels": {
          "app": "my-app"
        }
      },
      "template": {
        "metadata": {
          "labels": {
            "app": "my-app"
          }
        },
        "spec": {
          "containers": [
            {
              "image": "nginx:latest",
              "name": "app"
            }
          ]
        }
      }
    }
  }
}
```

**SDK Code**

```python
import requests

url = "http://localhost:8080/api/v2/workloads/WorkloadV2Id"

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

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

print(response.json())
```

```javascript
const url = 'http://localhost:8080/api/v2/workloads/WorkloadV2Id';
const options = {
  method: 'PUT',
  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 := "http://localhost:8080/api/v2/workloads/WorkloadV2Id"

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

	req, _ := http.NewRequest("PUT", 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("http://localhost:8080/api/v2/workloads/WorkloadV2Id")

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

request = Net::HTTP::Put.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.put("http://localhost:8080/api/v2/workloads/WorkloadV2Id")
  .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('PUT', 'http://localhost:8080/api/v2/workloads/WorkloadV2Id', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("http://localhost:8080/api/v2/workloads/WorkloadV2Id");
var request = new RestRequest(Method.PUT);
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: "http://localhost:8080/api/v2/workloads/WorkloadV2Id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
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()
```