# Workloads V2

The Workloads V2 API allows you to create, retrieve, and delete workloads that originate from third-party ML frameworks, tools, or the broader Kubernetes ecosystem. These workloads are registered in the platform through the Workload Types API, some are already registered in NVIDIA Run:ai, while others can be added by administrators. Each submission combines the user’s Kubernetes manifest with NVIDIA Run:ai scheduling metadata, enabling consistent orchestration, monitoring, and governance. See [Extending workload support](https://run-ai-docs.nvidia.com/self-hosted/workloads-in-nvidia-run-ai/workload-types/extending-workload-support) for more details.

## Create a workload. \[Experimental]

> Submit a workload with metadata and a Kubernetes manifest.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.23"},"tags":[{"name":"Workloads V2","description":"The Workloads V2 API allows you to create, retrieve, and delete workloads that originate from third-party ML frameworks, tools, or the broader Kubernetes ecosystem. These workloads are registered in the platform through the Workload Types API, some are already registered in NVIDIA Run:ai, while others can be added by administrators.\nEach submission combines the user’s Kubernetes manifest with NVIDIA Run:ai scheduling metadata, enabling consistent orchestration, monitoring, and governance. See [Extending workload support](https://run-ai-docs.nvidia.com/self-hosted/workloads-in-nvidia-run-ai/workload-types/extending-workload-support) for more details.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"schemas":{"WorkloadV2CreateRequest":{"type":"object","required":["metadata"],"properties":{"metadata":{"$ref":"#/components/schemas/WorkloadV2MetadataCreateParams"},"manifest":{"$ref":"#/components/schemas/Manifest"},"manifestBase64Encoded":{"$ref":"#/components/schemas/ManifestEncoded"}}},"WorkloadV2MetadataCreateParams":{"type":"object","required":["name","projectId"],"properties":{"name":{"$ref":"#/components/schemas/WorkloadName"},"projectId":{"$ref":"#/components/schemas/ProjectId"},"priority":{"$ref":"#/components/schemas/PriorityClass"},"category":{"$ref":"#/components/schemas/Category"}}},"WorkloadName":{"description":"The name of the workload.","type":"string","minLength":1,"pattern":".*"},"ProjectId":{"description":"The id of the project.","type":"string","pattern":".*"},"PriorityClass":{"description":"Specifies the priority class for the workload. Valid values are: very-low, low, medium-low, medium, medium-high, high, very-high. You can use this parameter to adjust the workload's scheduling behavior. Each workload type has a default priority. To view the default priority for each workload type, use the GET /workload-types endpoint.","type":"string","nullable":true,"pattern":".*"},"Category":{"description":"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.","type":"string","nullable":true,"pattern":".*"},"Manifest":{"type":"object","description":"The full Kubernetes manifest for the workload in JSON form. Mutually exclusive with manifestEncodedBase64.","additionalProperties":true},"ManifestEncoded":{"type":"string","format":"byte","description":"Kubernetes YAML manifest encoded in base 64. Mutually exclusive with manifest."},"WorkloadV2":{"type":"object","required":["metadata","desiredPhase","workloadManifest","rawManifest"],"properties":{"metadata":{"$ref":"#/components/schemas/WorkloadV2Metadata"},"desiredPhase":{"$ref":"#/components/schemas/DesiredPhase"},"workloadManifest":{"$ref":"#/components/schemas/Manifest"},"rawManifest":{"$ref":"#/components/schemas/Manifest"}}},"WorkloadV2Metadata":{"allOf":[{"$ref":"#/components/schemas/WorkloadV2MetadataCreateParams"},{"$ref":"#/components/schemas/WorkloadV2MetadataAutoFill"}]},"WorkloadV2MetadataAutoFill":{"type":"object","required":["id","gvk","projectName","clusterId","tenantId","departmentId","departmentName","createdAt","createdBy","updatedAt","updatedBy"],"properties":{"id":{"$ref":"#/components/schemas/WorkloadId3"},"gvk":{"$ref":"#/components/schemas/GVK"},"projectName":{"$ref":"#/components/schemas/ProjectName2"},"clusterId":{"$ref":"#/components/schemas/ClusterId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"departmentId":{"$ref":"#/components/schemas/DepartmentId3"},"departmentName":{"$ref":"#/components/schemas/DepartmentName1"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the workload was created."},"createdBy":{"type":"string","description":"Identifier of the user who created the workload.","format":".*"},"updatedAt":{"type":"string","format":"date-time","description":"The timestamp for the last time the workload was updated."},"updatedBy":{"type":"string","description":"Identifier of the user who last updated the workload.","format":".*"},"deletedAt":{"type":"string","format":"date-time","description":"The timestamp indicating when the workload was deleted.","nullable":true},"deletedBy":{"type":"string","format":".*","description":"Identifier of the user who deleted the workload.","nullable":true}}},"WorkloadId3":{"description":"A unique ID of the workload.","type":"string","format":"uuid"},"GVK":{"type":"object","description":"Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload.","required":["group","version","kind"],"properties":{"group":{"description":"The API group of the Kubernetes resource.","type":"string"},"version":{"description":"The API version of the resource within the specified group.","type":"string"},"kind":{"description":"The type of Kubernetes resource being referenced.","type":"string"}}},"ProjectName2":{"type":"string","description":"The name of the project","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"DepartmentId3":{"description":"The id of the department.","type":"string","minLength":1,"pattern":".*"},"DepartmentName1":{"type":"string","description":"The name of the department","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"DesiredPhase":{"description":"The desired phase of the workload.","type":"string","enum":["Running","Stopped","Deleted"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409Conflict":{"description":"The specified resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/workloads":{"post":{"summary":"Create a workload. [Experimental]","description":"Submit a workload with metadata and a Kubernetes manifest.","operationId":"create_workload_v2","tags":["Workloads V2"],"requestBody":{"description":"Workload metadata and manifest","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkloadV2CreateRequest"}}}},"responses":{"202":{"description":"Workload creation request accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkloadV2"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"409":{"$ref":"#/components/responses/409Conflict"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Get a specific workload. \[Experimental]

> Retrieve details of a specific workload by ID

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.23"},"tags":[{"name":"Workloads V2","description":"The Workloads V2 API allows you to create, retrieve, and delete workloads that originate from third-party ML frameworks, tools, or the broader Kubernetes ecosystem. These workloads are registered in the platform through the Workload Types API, some are already registered in NVIDIA Run:ai, while others can be added by administrators.\nEach submission combines the user’s Kubernetes manifest with NVIDIA Run:ai scheduling metadata, enabling consistent orchestration, monitoring, and governance. See [Extending workload support](https://run-ai-docs.nvidia.com/self-hosted/workloads-in-nvidia-run-ai/workload-types/extending-workload-support) for more details.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"WorkloadV2Id":{"name":"WorkloadV2Id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The ID of the workload."}}},"schemas":{"WorkloadV2GetResponse":{"type":"object","required":["workload"],"properties":{"workload":{"$ref":"#/components/schemas/WorkloadV2"},"syncInfo":{"$ref":"#/components/schemas/WorkloadV2SyncInfo"}}},"WorkloadV2":{"type":"object","required":["metadata","desiredPhase","workloadManifest","rawManifest"],"properties":{"metadata":{"$ref":"#/components/schemas/WorkloadV2Metadata"},"desiredPhase":{"$ref":"#/components/schemas/DesiredPhase"},"workloadManifest":{"$ref":"#/components/schemas/Manifest"},"rawManifest":{"$ref":"#/components/schemas/Manifest"}}},"WorkloadV2Metadata":{"allOf":[{"$ref":"#/components/schemas/WorkloadV2MetadataCreateParams"},{"$ref":"#/components/schemas/WorkloadV2MetadataAutoFill"}]},"WorkloadV2MetadataCreateParams":{"type":"object","required":["name","projectId"],"properties":{"name":{"$ref":"#/components/schemas/WorkloadName"},"projectId":{"$ref":"#/components/schemas/ProjectId"},"priority":{"$ref":"#/components/schemas/PriorityClass"},"category":{"$ref":"#/components/schemas/Category"}}},"WorkloadName":{"description":"The name of the workload.","type":"string","minLength":1,"pattern":".*"},"ProjectId":{"description":"The id of the project.","type":"string","pattern":".*"},"PriorityClass":{"description":"Specifies the priority class for the workload. Valid values are: very-low, low, medium-low, medium, medium-high, high, very-high. You can use this parameter to adjust the workload's scheduling behavior. Each workload type has a default priority. To view the default priority for each workload type, use the GET /workload-types endpoint.","type":"string","nullable":true,"pattern":".*"},"Category":{"description":"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.","type":"string","nullable":true,"pattern":".*"},"WorkloadV2MetadataAutoFill":{"type":"object","required":["id","gvk","projectName","clusterId","tenantId","departmentId","departmentName","createdAt","createdBy","updatedAt","updatedBy"],"properties":{"id":{"$ref":"#/components/schemas/WorkloadId3"},"gvk":{"$ref":"#/components/schemas/GVK"},"projectName":{"$ref":"#/components/schemas/ProjectName2"},"clusterId":{"$ref":"#/components/schemas/ClusterId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"departmentId":{"$ref":"#/components/schemas/DepartmentId3"},"departmentName":{"$ref":"#/components/schemas/DepartmentName1"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the workload was created."},"createdBy":{"type":"string","description":"Identifier of the user who created the workload.","format":".*"},"updatedAt":{"type":"string","format":"date-time","description":"The timestamp for the last time the workload was updated."},"updatedBy":{"type":"string","description":"Identifier of the user who last updated the workload.","format":".*"},"deletedAt":{"type":"string","format":"date-time","description":"The timestamp indicating when the workload was deleted.","nullable":true},"deletedBy":{"type":"string","format":".*","description":"Identifier of the user who deleted the workload.","nullable":true}}},"WorkloadId3":{"description":"A unique ID of the workload.","type":"string","format":"uuid"},"GVK":{"type":"object","description":"Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload.","required":["group","version","kind"],"properties":{"group":{"description":"The API group of the Kubernetes resource.","type":"string"},"version":{"description":"The API version of the resource within the specified group.","type":"string"},"kind":{"description":"The type of Kubernetes resource being referenced.","type":"string"}}},"ProjectName2":{"type":"string","description":"The name of the project","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"DepartmentId3":{"description":"The id of the department.","type":"string","minLength":1,"pattern":".*"},"DepartmentName1":{"type":"string","description":"The name of the department","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"DesiredPhase":{"description":"The desired phase of the workload.","type":"string","enum":["Running","Stopped","Deleted"]},"Manifest":{"type":"object","description":"The full Kubernetes manifest for the workload in JSON form. Mutually exclusive with manifestEncodedBase64.","additionalProperties":true},"WorkloadV2SyncInfo":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/WorkloadV2SyncStatus"},"message":{"type":"string","pattern":".*"}}},"WorkloadV2SyncStatus":{"type":"string","enum":["Queued","Applying","Deleting","Synced","Deleted","Failed"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/workloads/{WorkloadV2Id}":{"get":{"summary":"Get a specific workload. [Experimental]","description":"Retrieve details of a specific workload by ID","operationId":"get_workload_v2_by_id","tags":["Workloads V2"],"parameters":[{"$ref":"#/components/parameters/WorkloadV2Id"}],"responses":{"200":{"description":"Successfully retrieved the workload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkloadV2GetResponse"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Delete a workload. \[Experimental]

> Delete a specific workload by ID

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.23"},"tags":[{"name":"Workloads V2","description":"The Workloads V2 API allows you to create, retrieve, and delete workloads that originate from third-party ML frameworks, tools, or the broader Kubernetes ecosystem. These workloads are registered in the platform through the Workload Types API, some are already registered in NVIDIA Run:ai, while others can be added by administrators.\nEach submission combines the user’s Kubernetes manifest with NVIDIA Run:ai scheduling metadata, enabling consistent orchestration, monitoring, and governance. See [Extending workload support](https://run-ai-docs.nvidia.com/self-hosted/workloads-in-nvidia-run-ai/workload-types/extending-workload-support) for more details.\n"}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"WorkloadV2Id":{"name":"WorkloadV2Id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The ID of the workload."}}},"schemas":{"WorkloadV2":{"type":"object","required":["metadata","desiredPhase","workloadManifest","rawManifest"],"properties":{"metadata":{"$ref":"#/components/schemas/WorkloadV2Metadata"},"desiredPhase":{"$ref":"#/components/schemas/DesiredPhase"},"workloadManifest":{"$ref":"#/components/schemas/Manifest"},"rawManifest":{"$ref":"#/components/schemas/Manifest"}}},"WorkloadV2Metadata":{"allOf":[{"$ref":"#/components/schemas/WorkloadV2MetadataCreateParams"},{"$ref":"#/components/schemas/WorkloadV2MetadataAutoFill"}]},"WorkloadV2MetadataCreateParams":{"type":"object","required":["name","projectId"],"properties":{"name":{"$ref":"#/components/schemas/WorkloadName"},"projectId":{"$ref":"#/components/schemas/ProjectId"},"priority":{"$ref":"#/components/schemas/PriorityClass"},"category":{"$ref":"#/components/schemas/Category"}}},"WorkloadName":{"description":"The name of the workload.","type":"string","minLength":1,"pattern":".*"},"ProjectId":{"description":"The id of the project.","type":"string","pattern":".*"},"PriorityClass":{"description":"Specifies the priority class for the workload. Valid values are: very-low, low, medium-low, medium, medium-high, high, very-high. You can use this parameter to adjust the workload's scheduling behavior. Each workload type has a default priority. To view the default priority for each workload type, use the GET /workload-types endpoint.","type":"string","nullable":true,"pattern":".*"},"Category":{"description":"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.","type":"string","nullable":true,"pattern":".*"},"WorkloadV2MetadataAutoFill":{"type":"object","required":["id","gvk","projectName","clusterId","tenantId","departmentId","departmentName","createdAt","createdBy","updatedAt","updatedBy"],"properties":{"id":{"$ref":"#/components/schemas/WorkloadId3"},"gvk":{"$ref":"#/components/schemas/GVK"},"projectName":{"$ref":"#/components/schemas/ProjectName2"},"clusterId":{"$ref":"#/components/schemas/ClusterId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"departmentId":{"$ref":"#/components/schemas/DepartmentId3"},"departmentName":{"$ref":"#/components/schemas/DepartmentName1"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the workload was created."},"createdBy":{"type":"string","description":"Identifier of the user who created the workload.","format":".*"},"updatedAt":{"type":"string","format":"date-time","description":"The timestamp for the last time the workload was updated."},"updatedBy":{"type":"string","description":"Identifier of the user who last updated the workload.","format":".*"},"deletedAt":{"type":"string","format":"date-time","description":"The timestamp indicating when the workload was deleted.","nullable":true},"deletedBy":{"type":"string","format":".*","description":"Identifier of the user who deleted the workload.","nullable":true}}},"WorkloadId3":{"description":"A unique ID of the workload.","type":"string","format":"uuid"},"GVK":{"type":"object","description":"Specifies the Group, Version, and Kind (GVK) of the Kubernetes resource that defines the workload.","required":["group","version","kind"],"properties":{"group":{"description":"The API group of the Kubernetes resource.","type":"string"},"version":{"description":"The API version of the resource within the specified group.","type":"string"},"kind":{"description":"The type of Kubernetes resource being referenced.","type":"string"}}},"ProjectName2":{"type":"string","description":"The name of the project","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"DepartmentId3":{"description":"The id of the department.","type":"string","minLength":1,"pattern":".*"},"DepartmentName1":{"type":"string","description":"The name of the department","minLength":1,"pattern":"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"},"DesiredPhase":{"description":"The desired phase of the workload.","type":"string","enum":["Running","Stopped","Deleted"]},"Manifest":{"type":"object","description":"The full Kubernetes manifest for the workload in JSON form. Mutually exclusive with manifestEncodedBase64.","additionalProperties":true},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/workloads/{WorkloadV2Id}":{"delete":{"summary":"Delete a workload. [Experimental]","description":"Delete a specific workload by ID","operationId":"delete_workload_v2","tags":["Workloads V2"],"parameters":[{"$ref":"#/components/parameters/WorkloadV2Id"}],"responses":{"202":{"description":"Deletion request accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkloadV2"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```