# Clusters
Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters.
## Get a list of clusters.
> Retrieve a list of clusters with details.
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"QueryVerbosity":{"name":"verbosity","in":"query","required":false,"description":"response verbosity level.\n","schema":{"type":"string","enum":["metadata","full"],"default":"full"}},"QueryIncludeRequestedForDelete":{"name":"includeRequestedForDelete","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, includes clusters that are marked for deletion"}},"schemas":{"DisplayedCluster":{"type":"object","required":["uuid","tenantId","name","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"domain":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/ClusterDisplayedStatus"},"updatedAt":{"type":"string","format":"date-time","nullable":true},"deletedAt":{"type":"string","nullable":true,"format":"date-time"},"lastLiveness":{"type":"string","nullable":true,"format":"date-time"},"deleteRequestedAt":{"description":"the timestamp value of when the cluster deletion request was received","type":"string","format":"date-time","nullable":true}}},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"ClusterDisplayedStatus":{"type":"object","description":"The cluster's displayed status.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ClusterReportedStatus"},{"type":"object","properties":{"state":{"$ref":"#/components/schemas/ClusterState"}}}]},"ClusterReportedStatus":{"type":"object","description":"the cluster status reported by the cluster","properties":{"conditions":{"items":{"description":"Condition contains details for one aspect of the current state of this API Resource","properties":{"lastTransitionTime":{"description":"lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.","format":"date-time","type":"string"},"message":{"description":"message is a human readable message indicating details about the transition. This may be an empty string.","maxLength":32768,"type":"string"},"observedGeneration":{"description":"observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.","format":"int64","minimum":0,"type":"integer"},"reason":{"description":"reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.","maxLength":1024,"minLength":1,"pattern":"^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$","type":"string"},"status":{"description":"status of the condition, one of True, False, Unknown.","enum":["True","False","Unknown"],"type":"string"},"type":{"description":"type of condition in CamelCase or in foo.example.com/CamelCase. --- Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)","maxLength":316,"type":"string"}},"required":["lastTransitionTime","message","reason","status","type"],"type":"object"},"type":"array"},"operands":{"additionalProperties":{"description":"Status specifies the status of an operand. And operand manages resources, some of which are not immediately available and need their status monitored, such as Deployments, Daemonsets, Ingressess etc. Some resources are immediately available and should not be monitored once accepted by the cluster, such as Services, ConfigMaps, Secrets etc. If all resources of an operand are ready, a Status with Ready set to 'true' and a nil 'Reasons' slice should be returned, otherwise, a Status with 'Reasons' slice containig the reason why the Operand is not ready (Deployment pods are not ready for example.)","properties":{"lastTransitionTime":{"description":"LastTransitionTime specifies the last time the operand readiness changed","format":"date-time","type":"string"},"ready":{"description":"Ready specifies if the operand is ready or not","type":"boolean"},"reasons":{"description":"Reasons specifies the reasons why the operand is not ready","items":{"type":"string"},"type":"array"},"unreadyThresholdCrossed":{"description":"UnreadyThresholdCrossed specifies if the operand has been unready for longer than the threshold","type":"boolean"}},"required":["ready"],"type":"object"},"description":"OperandStatuses specifies the status of the managed operands","type":"object"},"platform":{"$ref":"#/components/schemas/ClusterReportedStatusPlatform"},"config":{"$ref":"#/components/schemas/ClusterReportedConfig"},"dependencies":{"$ref":"#/components/schemas/ClusterDependenciesStatus"}}},"ClusterReportedStatusPlatform":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["vanilla","openshift","rke","gke","aks","eks"],"description":"the cluster platform type"},"kubeVersion":{"nullable":true,"type":"string","description":"the cluster kubernetes version"}}},"ClusterReportedConfig":{"description":"Holds cluster configuration values.","type":"object","properties":{"workloadOwnershipProtection":{"type":"boolean","nullable":true,"description":"indicates if the cluster workload ownership protection is enabled"},"subdomainEnabled":{"type":"boolean","nullable":true,"description":"indicates if the cluster subdomain is enabled"},"ingressClass":{"type":"string","nullable":true,"description":"the ingress class that is configured for the cluster"}},"nullable":true},"ClusterDependenciesStatus":{"type":"object","required":["required","optional"],"properties":{"required":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}},"optional":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterDependencyStatus":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"whether the dependency is available"},"reason":{"type":"string","description":"the reason for the dependency status"},"components":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterState":{"type":"string","description":"The cluster's state.","enum":["WaitingToConnect","Connected","Disconnected","MissingPrerequisites","ServiceIssues","Unknown"]},"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/v1/clusters":{"get":{"summary":"Get a list of clusters.","description":"Retrieve a list of clusters with details.","operationId":"get_clusters","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/QueryVerbosity"},{"$ref":"#/components/parameters/QueryIncludeRequestedForDelete"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DisplayedCluster"}}}}},"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"}}}}}}
```
## Create a cluster.
> Use to create a Kubernetes cluster.
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"schemas":{"ClusterCreationRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"domain":{"type":"string"},"version":{"type":"string"}}},"DisplayedCluster":{"type":"object","required":["uuid","tenantId","name","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"domain":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/ClusterDisplayedStatus"},"updatedAt":{"type":"string","format":"date-time","nullable":true},"deletedAt":{"type":"string","nullable":true,"format":"date-time"},"lastLiveness":{"type":"string","nullable":true,"format":"date-time"},"deleteRequestedAt":{"description":"the timestamp value of when the cluster deletion request was received","type":"string","format":"date-time","nullable":true}}},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"ClusterDisplayedStatus":{"type":"object","description":"The cluster's displayed status.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ClusterReportedStatus"},{"type":"object","properties":{"state":{"$ref":"#/components/schemas/ClusterState"}}}]},"ClusterReportedStatus":{"type":"object","description":"the cluster status reported by the cluster","properties":{"conditions":{"items":{"description":"Condition contains details for one aspect of the current state of this API Resource","properties":{"lastTransitionTime":{"description":"lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.","format":"date-time","type":"string"},"message":{"description":"message is a human readable message indicating details about the transition. This may be an empty string.","maxLength":32768,"type":"string"},"observedGeneration":{"description":"observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.","format":"int64","minimum":0,"type":"integer"},"reason":{"description":"reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.","maxLength":1024,"minLength":1,"pattern":"^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$","type":"string"},"status":{"description":"status of the condition, one of True, False, Unknown.","enum":["True","False","Unknown"],"type":"string"},"type":{"description":"type of condition in CamelCase or in foo.example.com/CamelCase. --- Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)","maxLength":316,"type":"string"}},"required":["lastTransitionTime","message","reason","status","type"],"type":"object"},"type":"array"},"operands":{"additionalProperties":{"description":"Status specifies the status of an operand. And operand manages resources, some of which are not immediately available and need their status monitored, such as Deployments, Daemonsets, Ingressess etc. Some resources are immediately available and should not be monitored once accepted by the cluster, such as Services, ConfigMaps, Secrets etc. If all resources of an operand are ready, a Status with Ready set to 'true' and a nil 'Reasons' slice should be returned, otherwise, a Status with 'Reasons' slice containig the reason why the Operand is not ready (Deployment pods are not ready for example.)","properties":{"lastTransitionTime":{"description":"LastTransitionTime specifies the last time the operand readiness changed","format":"date-time","type":"string"},"ready":{"description":"Ready specifies if the operand is ready or not","type":"boolean"},"reasons":{"description":"Reasons specifies the reasons why the operand is not ready","items":{"type":"string"},"type":"array"},"unreadyThresholdCrossed":{"description":"UnreadyThresholdCrossed specifies if the operand has been unready for longer than the threshold","type":"boolean"}},"required":["ready"],"type":"object"},"description":"OperandStatuses specifies the status of the managed operands","type":"object"},"platform":{"$ref":"#/components/schemas/ClusterReportedStatusPlatform"},"config":{"$ref":"#/components/schemas/ClusterReportedConfig"},"dependencies":{"$ref":"#/components/schemas/ClusterDependenciesStatus"}}},"ClusterReportedStatusPlatform":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["vanilla","openshift","rke","gke","aks","eks"],"description":"the cluster platform type"},"kubeVersion":{"nullable":true,"type":"string","description":"the cluster kubernetes version"}}},"ClusterReportedConfig":{"description":"Holds cluster configuration values.","type":"object","properties":{"workloadOwnershipProtection":{"type":"boolean","nullable":true,"description":"indicates if the cluster workload ownership protection is enabled"},"subdomainEnabled":{"type":"boolean","nullable":true,"description":"indicates if the cluster subdomain is enabled"},"ingressClass":{"type":"string","nullable":true,"description":"the ingress class that is configured for the cluster"}},"nullable":true},"ClusterDependenciesStatus":{"type":"object","required":["required","optional"],"properties":{"required":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}},"optional":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterDependencyStatus":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"whether the dependency is available"},"reason":{"type":"string","description":"the reason for the dependency status"},"components":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterState":{"type":"string","description":"The cluster's state.","enum":["WaitingToConnect","Connected","Disconnected","MissingPrerequisites","ServiceIssues","Unknown"]},"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/v1/clusters":{"post":{"summary":"Create a cluster.","description":"Use to create a Kubernetes cluster.","operationId":"create_cluster","tags":["Clusters"],"requestBody":{"description":"The cluster to create.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterCreationRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisplayedCluster"}}}},"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"}}}}}}
```
## Get cluster by id.
> Retrieve cluster details by Universally Unique Identifier (UUID).
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClusterUuid":{"name":"clusterUuid","in":"path","required":true,"description":"The Universally Unique Identifier (UUID) of the cluster.","schema":{"type":"string","format":"uuid","minLength":1}},"QueryVerbosity":{"name":"verbosity","in":"query","required":false,"description":"response verbosity level.\n","schema":{"type":"string","enum":["metadata","full"],"default":"full"}}},"schemas":{"DisplayedCluster":{"type":"object","required":["uuid","tenantId","name","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"domain":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/ClusterDisplayedStatus"},"updatedAt":{"type":"string","format":"date-time","nullable":true},"deletedAt":{"type":"string","nullable":true,"format":"date-time"},"lastLiveness":{"type":"string","nullable":true,"format":"date-time"},"deleteRequestedAt":{"description":"the timestamp value of when the cluster deletion request was received","type":"string","format":"date-time","nullable":true}}},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"ClusterDisplayedStatus":{"type":"object","description":"The cluster's displayed status.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ClusterReportedStatus"},{"type":"object","properties":{"state":{"$ref":"#/components/schemas/ClusterState"}}}]},"ClusterReportedStatus":{"type":"object","description":"the cluster status reported by the cluster","properties":{"conditions":{"items":{"description":"Condition contains details for one aspect of the current state of this API Resource","properties":{"lastTransitionTime":{"description":"lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.","format":"date-time","type":"string"},"message":{"description":"message is a human readable message indicating details about the transition. This may be an empty string.","maxLength":32768,"type":"string"},"observedGeneration":{"description":"observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.","format":"int64","minimum":0,"type":"integer"},"reason":{"description":"reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.","maxLength":1024,"minLength":1,"pattern":"^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$","type":"string"},"status":{"description":"status of the condition, one of True, False, Unknown.","enum":["True","False","Unknown"],"type":"string"},"type":{"description":"type of condition in CamelCase or in foo.example.com/CamelCase. --- Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)","maxLength":316,"type":"string"}},"required":["lastTransitionTime","message","reason","status","type"],"type":"object"},"type":"array"},"operands":{"additionalProperties":{"description":"Status specifies the status of an operand. And operand manages resources, some of which are not immediately available and need their status monitored, such as Deployments, Daemonsets, Ingressess etc. Some resources are immediately available and should not be monitored once accepted by the cluster, such as Services, ConfigMaps, Secrets etc. If all resources of an operand are ready, a Status with Ready set to 'true' and a nil 'Reasons' slice should be returned, otherwise, a Status with 'Reasons' slice containig the reason why the Operand is not ready (Deployment pods are not ready for example.)","properties":{"lastTransitionTime":{"description":"LastTransitionTime specifies the last time the operand readiness changed","format":"date-time","type":"string"},"ready":{"description":"Ready specifies if the operand is ready or not","type":"boolean"},"reasons":{"description":"Reasons specifies the reasons why the operand is not ready","items":{"type":"string"},"type":"array"},"unreadyThresholdCrossed":{"description":"UnreadyThresholdCrossed specifies if the operand has been unready for longer than the threshold","type":"boolean"}},"required":["ready"],"type":"object"},"description":"OperandStatuses specifies the status of the managed operands","type":"object"},"platform":{"$ref":"#/components/schemas/ClusterReportedStatusPlatform"},"config":{"$ref":"#/components/schemas/ClusterReportedConfig"},"dependencies":{"$ref":"#/components/schemas/ClusterDependenciesStatus"}}},"ClusterReportedStatusPlatform":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["vanilla","openshift","rke","gke","aks","eks"],"description":"the cluster platform type"},"kubeVersion":{"nullable":true,"type":"string","description":"the cluster kubernetes version"}}},"ClusterReportedConfig":{"description":"Holds cluster configuration values.","type":"object","properties":{"workloadOwnershipProtection":{"type":"boolean","nullable":true,"description":"indicates if the cluster workload ownership protection is enabled"},"subdomainEnabled":{"type":"boolean","nullable":true,"description":"indicates if the cluster subdomain is enabled"},"ingressClass":{"type":"string","nullable":true,"description":"the ingress class that is configured for the cluster"}},"nullable":true},"ClusterDependenciesStatus":{"type":"object","required":["required","optional"],"properties":{"required":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}},"optional":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterDependencyStatus":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"whether the dependency is available"},"reason":{"type":"string","description":"the reason for the dependency status"},"components":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterState":{"type":"string","description":"The cluster's state.","enum":["WaitingToConnect","Connected","Disconnected","MissingPrerequisites","ServiceIssues","Unknown"]},"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/v1/clusters/{clusterUuid}":{"get":{"summary":"Get cluster by id.","description":"Retrieve cluster details by Universally Unique Identifier (UUID).","operationId":"get_cluster_by_uuid","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClusterUuid"},{"$ref":"#/components/parameters/QueryVerbosity"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisplayedCluster"}}}},"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"}}}}}}
```
## Update a cluster by id.
> Use to update the details of a Kubernetes cluster by Universally Unique Identifier (UUID).
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClusterUuid":{"name":"clusterUuid","in":"path","required":true,"description":"The Universally Unique Identifier (UUID) of the cluster.","schema":{"type":"string","format":"uuid","minLength":1}}},"schemas":{"ClusterUpdateRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"204NoContent":{"description":"No Content."},"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"}}}},"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/v1/clusters/{clusterUuid}":{"put":{"summary":"Update a cluster by id.","description":"Use to update the details of a Kubernetes cluster by Universally Unique Identifier (UUID).","operationId":"updateCluster","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClusterUuid"}],"requestBody":{"description":"The cluster details to update","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterUpdateRequest"}}}},"responses":{"204":{"$ref":"#/components/responses/204NoContent"},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
## Delete a cluster by id.
> Use to delete a cluster by Universally Unique Identifier (UUID). \
> Will return 202 for success if this api was called on a cluster that its version is >=2.20, \
> and force query param is false or not provided.\
> Will return 204 for success if force query param is true, or if cluster is in a version < 2.20
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClusterUuid":{"name":"clusterUuid","in":"path","required":true,"description":"The Universally Unique Identifier (UUID) of the cluster.","schema":{"type":"string","format":"uuid","minLength":1}},"QueryForceDelete":{"name":"force","in":"query","required":false,"description":"if true will force cluster instant deletion otherwise will start cluster graceful deletion process.\n","schema":{"type":"boolean","default":false}}},"responses":{"202Accepted":{"description":"Accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpResponse"}}}},"204NoContent":{"description":"No Content."},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","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"}}}}},"schemas":{"HttpResponse":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v1/clusters/{clusterUuid}":{"delete":{"summary":"Delete a cluster by id.","description":"Use to delete a cluster by Universally Unique Identifier (UUID). \nWill return 202 for success if this api was called on a cluster that its version is >=2.20, \nand force query param is false or not provided.\nWill return 204 for success if force query param is true, or if cluster is in a version < 2.20\n","operationId":"delete_cluster","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClusterUuid"},{"$ref":"#/components/parameters/QueryForceDelete"}],"responses":{"202":{"$ref":"#/components/responses/202Accepted"},"204":{"$ref":"#/components/responses/204NoContent"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
## Retrieve the installation instructions of a cluster by ID.
> Use to retrieve installation instruction for a cluster by Universally Unique Identifier (UUID). \
> Supports clusters version 2.15 or above.
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClusterUuid":{"name":"clusterUuid","in":"path","required":true,"description":"The Universally Unique Identifier (UUID) of the cluster.","schema":{"type":"string","format":"uuid","minLength":1}},"ClusterVersion":{"name":"version","in":"query","required":true,"description":"The cluster version to install","schema":{"type":"string"}},"ClusterRemoteURL":{"name":"remoteClusterUrl","in":"query","required":false,"description":"The remote URL of the runai cluster","schema":{"type":"string"}}},"schemas":{"ClusterInstallationInfoResponse":{"type":"object","required":["installationStr","repositoryName","chartRepoURL","clientSecret"],"properties":{"installationStr":{"type":"string"},"repositoryName":{"type":"string"},"chartRepoURL":{"type":"string"},"clientSecret":{"type":"string"}}},"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/v1/clusters/{clusterUuid}/cluster-install-info":{"get":{"summary":"Retrieve the installation instructions of a cluster by ID.","description":"Use to retrieve installation instruction for a cluster by Universally Unique Identifier (UUID). \nSupports clusters version 2.15 or above.\n","operationId":"get_cluster_install_info_by_uuid","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClusterUuid"},{"$ref":"#/components/parameters/ClusterVersion"},{"$ref":"#/components/parameters/ClusterRemoteURL"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterInstallationInfoResponse"}}}},"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"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://run-ai-docs.nvidia.com/multi-tenant-api/2.24/organizations/clusters.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.