Ctrlk
Contact support
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 for more details.

Create a workload. [Experimental]

post

Submit a workload with metadata and a Kubernetes manifest.

Authorizations
AuthorizationstringRequired

Bearer authentication

Query parameters
dryRunbooleanOptional

True to perform validations only, without side effects.

Default: falseExample: false
Body
manifestBase64Encodedstring · byte · max: 2097152Optional

Kubernetes YAML manifest encoded in base 64. Mutually exclusive with manifest.

Example: YXBpVmVyc2lvbjogdjEKa2luZDogUG9kCm1ldGFkYXRhOgogIG5hbWU6IG15LXBvZApzcGVjOgogIGNvbnRhaW5lcnM6CiAgLSBuYW1lOiBuZ2lueAogICAgaW1hZ2U6IG5naW54OmxhdGVzdAo=
Responses
202

Workload creation request accepted.

application/json
desiredPhasestring · enumRequired

The desired phase of the workload.

Possible values:
post/api/v2/workloads
POST /api/v2/workloads HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 673

{
  "metadata": {
    "name": "my-workload-name",
    "useGivenNameAsPrefix": true,
    "projectId": 1,
    "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
    "priority": "text",
    "category": "text",
    "preemptibility": "preemptible",
    "configuration": {
      "mnnvl": "text"
    }
  },
  "manifest": {
    "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": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  },
  "manifestBase64Encoded": "YXBpVmVyc2lvbjogdjEKa2luZDogUG9kCm1ldGFkYXRhOgogIG5hbWU6IG15LXBvZApzcGVjOgogIGNvbnRhaW5lcnM6CiAgLSBuYW1lOiBuZ2lueAogICAgaW1hZ2U6IG5naW54OmxhdGVzdAo="
}
{
  "metadata": {
    "name": "my-workload-name",
    "projectId": 1,
    "priority": "text",
    "category": "text",
    "preemptibility": "preemptible",
    "configuration": {
      "mnnvl": "text"
    },
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "gvk": {
      "group": "apps",
      "version": "v1",
      "kind": "Deployment"
    },
    "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",
    "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": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  },
  "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": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  }
}

Get a specific workload. [Experimental]

get

Retrieve details of a specific workload by ID

Authorizations
AuthorizationstringRequired

Bearer authentication

Path parameters
WorkloadV2Idstring · uuidRequired

The ID of the workload.

Responses
200

Successfully retrieved the workload

application/json
get/api/v2/workloads/{WorkloadV2Id}
GET /api/v2/workloads/{WorkloadV2Id} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "workload": {
    "metadata": {
      "name": "my-workload-name",
      "projectId": 1,
      "priority": "text",
      "category": "text",
      "preemptibility": "preemptible",
      "configuration": {
        "mnnvl": "text"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "gvk": {
        "group": "apps",
        "version": "v1",
        "kind": "Deployment"
      },
      "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",
      "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": [
              {
                "name": "app",
                "image": "nginx:latest"
              }
            ]
          }
        }
      }
    },
    "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": [
              {
                "name": "app",
                "image": "nginx:latest"
              }
            ]
          }
        }
      }
    }
  },
  "syncInfo": {
    "status": "Queued",
    "message": "text"
  }
}

Update workload spec. [Experimental]

put

Update the specification of an existing workload.

Authorizations
AuthorizationstringRequired

Bearer authentication

Path parameters
WorkloadV2Idstring · uuidRequired

The ID of the workload.

Body
manifestBase64Encodedstring · byte · max: 2097152Optional

Kubernetes YAML manifest encoded in base 64. Mutually exclusive with manifest.

Example: YXBpVmVyc2lvbjogdjEKa2luZDogUG9kCm1ldGFkYXRhOgogIG5hbWU6IG15LXBvZApzcGVjOgogIGNvbnRhaW5lcnM6CiAgLSBuYW1lOiBuZ2lueAogICAgaW1hZ2U6IG5naW54OmxhdGVzdAo=
Responses
202

Workload update request accepted

application/json
desiredPhasestring · enumRequired

The desired phase of the workload.

Possible values:
put/api/v2/workloads/{WorkloadV2Id}
PUT /api/v2/workloads/{WorkloadV2Id} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 490

{
  "metadata": {
    "priority": "text",
    "category": "text"
  },
  "manifest": {
    "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": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  },
  "manifestBase64Encoded": "YXBpVmVyc2lvbjogdjEKa2luZDogUG9kCm1ldGFkYXRhOgogIG5hbWU6IG15LXBvZApzcGVjOgogIGNvbnRhaW5lcnM6CiAgLSBuYW1lOiBuZ2lueAogICAgaW1hZ2U6IG5naW54OmxhdGVzdAo="
}
{
  "metadata": {
    "name": "my-workload-name",
    "projectId": 1,
    "priority": "text",
    "category": "text",
    "preemptibility": "preemptible",
    "configuration": {
      "mnnvl": "text"
    },
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "gvk": {
      "group": "apps",
      "version": "v1",
      "kind": "Deployment"
    },
    "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",
    "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": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  },
  "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": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  }
}

Delete a workload. [Experimental]

delete

Delete a specific workload by ID

Authorizations
AuthorizationstringRequired

Bearer authentication

Path parameters
WorkloadV2Idstring · uuidRequired

The ID of the workload.

Responses
202

Deletion request accepted.

application/json
desiredPhasestring · enumRequired

The desired phase of the workload.

Possible values:
delete/api/v2/workloads/{WorkloadV2Id}
DELETE /api/v2/workloads/{WorkloadV2Id} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "metadata": {
    "name": "my-workload-name",
    "projectId": 1,
    "priority": "text",
    "category": "text",
    "preemptibility": "preemptible",
    "configuration": {
      "mnnvl": "text"
    },
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "gvk": {
      "group": "apps",
      "version": "v1",
      "kind": "Deployment"
    },
    "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",
    "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": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  },
  "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": [
            {
              "name": "app",
              "image": "nginx:latest"
            }
          ]
        }
      }
    }
  }
}
PreviousWorkloads
NextNVIDIA NIM

Last updated