NVIDIA Run:ai Workload templates API
This set of endpoints manages workload templates used to define reusable workload configurations across various workload types in the NVIDIA Run:ai platform. Templates help standardize workload definitions for consistent submission and resource usage across projects and users.
NVIDIA Run:ai Workload templates API is one of 62 APIs that NVIDIA Run:ai publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Workload templates. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and authentication docs.
This API exposes 26 operations across 12 paths, and defines 239 schemas. It is described by OpenAPI 3.0.3, at version latest.
Requests are made against a single base URL, https://app.run.ai.
26 operations
12 paths
239 schemas
4 DELETE12 GET3 PATCH4 POST3 PUT
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 1
NVIDIA Run:ai Workload templates API declares
1 security scheme
for authenticating requests.
It accepts HTTP bearer tokens (JWT) (bearerAuth).
By default, every request must be authenticated.
bearerAuth— Bearer authentication
Paths & Operations 26
Across 12 paths, the API surfaces 26 operations — 4 DELETE, 12 GET, 3 PATCH, 4 POST, 3 PUT. Each is listed below with its method, path, parameters, and response codes.
Workload templates 26
This set of endpoints manages workload templates used to define reusable workload configurations across various workload types in the NVIDIA Run:ai platform. Templates help standa…
GET
/api/v1/workload-templates
List templates. [Experimental]
GET
/api/v1/workload-templates/name-availability
Template name availability
GET
/api/v1/workload-templates/{templateId}
Get a template, any type. [Experimental]
GET
/api/v1/workload-templates/count
Count templates. [Experimental]
POST
/api/v1/workload-templates/workspaces
Create a new workspace template. [Experimental]
GET
/api/v1/workload-templates/workspaces
List all workspace templates. [Experimental]
GET
/api/v1/workload-templates/workspaces/{templateId}
Retrieve a specific workspace template by ID. [Experimental]
DELETE
/api/v1/workload-templates/workspaces/{templateId}
Delete a workspace template by ID. [Experimental]
PATCH
/api/v1/workload-templates/workspaces/{templateId}
Patch a workspace template by ID. [Experimental]
PUT
/api/v1/workload-templates/workspaces/{templateId}
Update a workspace template by ID. [Experimental]
POST
/api/v1/workload-templates/trainings
Create a new training template. [Experimental]
GET
/api/v1/workload-templates/trainings
List all training templates. [Experimental]
GET
/api/v1/workload-templates/trainings/{templateId}
Retrieve a specific training template by ID. [Experimental]
DELETE
/api/v1/workload-templates/trainings/{templateId}
Delete a training template by ID. [Experimental]
PATCH
/api/v1/workload-templates/trainings/{templateId}
Patch a training template by ID. [Experimental]
PUT
/api/v1/workload-templates/trainings/{templateId}
Update a training template by ID. [Experimental]
POST
/api/v1/workload-templates/distributed
Create a new distributed training template. [Experimental]
GET
/api/v1/workload-templates/distributed
List all distributed training templates. [Experimental]
GET
/api/v1/workload-templates/distributed/{templateId}
Get a specific distributed training template by ID. [Experimental]
DELETE
/api/v1/workload-templates/distributed/{templateId}
Delete a distributed training template by ID. [Experimental]
PATCH
/api/v1/workload-templates/distributed/{templateId}
Patch a distributed training template by ID. [Experimental]
PUT
/api/v1/workload-templates/distributed/{templateId}
Update a distributed training template by ID. [Experimental]
POST
/api/v1/workload-templates/inferences
Create a new inference template. [Experimental]
GET
/api/v1/workload-templates/inferences
List all inference templates. [Experimental]
GET
/api/v1/workload-templates/inferences/{templateId}
Get a specific inference template by ID. [Experimental]
DELETE
/api/v1/workload-templates/inferences/{templateId}
Delete an inference template by ID. [Experimental]
Schemas 239
The contract defines 239 schemas that model the data the API accepts and returns. The most detailed are MasterTemplateSpec (31 properties), DistributedInferenceLeaderWorkerSpec1 (18 properties), TemplateMetaFields (13 properties), SupersetServingPort (9 properties). Each schema is shown below with its type and property counts.
S3Common
object
3 properties
Category
string
Specify the workload category assigned to the workload. Categories are used to classify and monitor different types of workloads within the NVIDIA Run:ai platf…
PvcFieldsNonUpdatable
object
6 properties
AutoScalingMetricField
object
1 property
Probe
object
6 properties
ExposedUrl
object
A URL for accessing the workload.
9 properties
TemplateUpdateMetaFields
object
2 properties
1 required
BackoffLimitMaster
integer
Specifies the number of retries before marking a workload as failed (not applicable to Inference workloads). The default value is 6.
NodeAffinityRequired
object
If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements…
1 property
UidGidSource
string
Indicate the way to determine the user and group ids of the container. The options are a. fromTheImage - user and group ids are determined by the docker image…
SecretInstance2
object
Labels
array
Set of labels to populate into the container running the workload.
InitializationTimeoutField
object
1 property
TemplateMeta
object
1 property
1 required
MetricThresholdField
object
1 property
Error
object
3 properties
2 required
ExcludeField
object
1 property
WorkloadType
string
the type of workload
TemplateId
string
A unique ID of the template.
TerminationGracePeriod
integer
Duration in seconds the pod needs to terminate gracefully upon probe failure. The grace period is the duration in seconds after the processes running in the po…
CpuMemoryLimit
string
Limitations on the CPU memory to allocate for this workload (1G, 20M, .etc). The system guarantees that this workload will not be able to consume more than thi…
GitInstance
object
PvcAddedAttrValues
array
an optional array of key-values pairs that are written as annotations on the created PVC. the allowed attributes are determined according to the storage class…
PvcClaimSize
string
Requested size for the PVC. Mandatory when existingPvc is false. Recommended sizes: TB/GB/MB/TIB/GIB/MIB
Ports
array
Set of container ports that the workload exposes.
InferenceFields
object
Toleration
object
Toleration details.
7 properties
ScopeIdOptional
string
The id of the cluster, department or project, depending on the scope type.
S3AccessKey
object
3 properties
SecretFieldsNonUpdatable
object
1 property
SupersetServingPort
object
9 properties
Pvc
Stdin
boolean
Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in…
Capabilities
array
Add POSIX capabilities to running containers. Defaults to the default set of capabilities granted by the container runtime.
GpuMemoryRequest
string
Required if and only if gpuRequestType is memory. States the GPU memory to allocate for the created workload, per GPU device. Note that the workload will not b…
ComplianceInfoReason
object
An issue preventing the use of a template or asset for creating workloads in a given project.
3 properties
1 required
DistributedInferenceCommonSpec
object
PriorityClassMaster
string
Specifies the priority class for the workload, which determines its scheduling behavior. Valid values are: very-low, low, medium-low, medium, medium-high, high…
PvcFieldsUpdatable
object
1 property
HostPath
object
4 properties
SecretFieldsUpdatable
object
2 properties
InferencesMaxReplicasField
object
1 property
HostNetwork
boolean
Whether to enable host networking. Default to false.
EnvironmentVariable
object
Details of an environment variable which is populated into the container.
8 properties
LargeShmRequest
boolean
A large /dev/shm device to mount into a container running the created workload. An shm is a shared file system mounted on RAM.
TemplateComplianceIssues
array
A list of issues preventing the use of a template or asset for creating workloads in a given project.
DistributedInferenceWorkersField
object
1 property
RunAsGid
integer
The group id to run the entrypoint of the container which executes the workspace. Default to the value specified in the environment asset runAsGid field (optio…
EnvironmentVariableSecret
object
Details of the secret and key use to populate the environment variable
2 properties
MinReplicas
integer
the lower limit for the number of worker pods to which the training job can scale down. (applicable only for PyTorch)
TemplatePatchMeta
object
1 property
ProjectIdOptional
integer
The id of the project.
Annotations
array
Set of annotations to populate into the container running the workload.
AutoScalingMetric
string
The metric to use for autoscaling. Mandatory if minReplicas < maxReplicas, except for the special case where minReplicas is set to 0 and maxReplicas is set to…
ProbeHandler
object
The action taken to determine the health of the container. (mandatory)
1 property
MatchExpressionOperator
string
Represents a key's relationship to a set of values (mandatory).
TolerationEffect
string
The taint effect to match. (mandatory)
GitPassword
object
3 properties
TemplateUpdateMeta
object
1 property
1 required
DistributedInferenceLeaderWorkerSpec1
object
18 properties
ImagePullPolicy
string
Image pull policy. Defaults to Always if :latest tag is specified, otherwise it is IfNotPresent.
AllowPrivilegeEscalation
boolean
Allow the container running the workload and all launched processes to gain additional privileges after the workload starts. For more information consult the U…
TemplateMetaFields
object
13 properties
7 required
HostPathItems
array
Set of host paths to use in the workload.
ClaimInfo
object
Claim information for the newly created PVC. The information should not be provided when attempting to use existing PVC.
5 properties
TemplateCreationMetaFields
object
4 properties
2 required
DistributedInferenceServingPort
object
Defines the configuration for the inference serving endpoint. This determines how applications or services can send inference requests to the workload.
SlotsPerWorker
integer
Specifies the number of slots per worker used in hostfile. Defaults to 1. (applicable only for MPI)
ServingPort
object
A port for accessing the inference service
HostPathMountPropagation
string
Share this volumes mount with other containers. If set to HostToContainer, this volume mount will receive all subsequent mounts that are mounted to this volume…
WorkspaceTemplatePatchRequest
NumWorkers
integer
the number of workers that will be allocated for running the workload.
DistributedInferenceRestartPolicy
string
Determines the behavior when a pod fails. - RecreateGroupOnPodRestart: Restarts all pods in the group if any pod fails. - None: No automatic restart behavior i…
CountResponse
object
1 property
1 required
StorageInstanceName
object
1 property
EnvironmentVariables
array
Set of environment variables to populate into the container running the workload.
ServingPortContainerAndProtocol
object
2 properties
TemplateCreationMeta
object
1 property
1 required
CpuCoreRequest
number
CPU units to allocate for the created workload (0.5, 1, .etc). The workload will receive at least this amount of CPU. Note that the workload will not be schedu…
Preemptibility
string
Specifies whether the workload can be preempted by higher-priority workloads. Valid values are preemptible and non-preemptible. If explicitly set, this value t…
RelatedUrls
array
Set of URLs that are related to the workload.
DistributedInferenceWorkerSpecFields
object
1 property
SupplementalGroups
string
Comma separated list of groups that the user running the container belongs to, in addition to the group indicated by runAsGid. Use only when the source uid/gid…
DataVolume
object
2 properties
ConfigMapItems
array
Set of config map volumes to use in the workload
CleanPodPolicy
string
The policy describes how to deal with pods when the job is finished.
PolicyRuleEnum
string
Indicates which validation rule (e.g., min, max, step, options, required, canEdit, canAdd) conflicted with policy restrictions, causing the asset or template t…
DistributedTemplateCreationRequest
DistributedTemplatePatchRequest
Completions
integer
Used with Hyperparameter Optimization. Specifies the number of successful pods the job should reach to be completed. The Job will be marked as successful once…
AutoScalingField
object
1 property
InitialReplicasField
object
1 property
DistributedInferenceServingPortAccess
object
5 properties
ServingPortProtocol
string
The protocol used by the port, defaults to http
AutoScalingMetricFields
object
ImagePullSecrets
array
A list of references to Kubernetes secrets in the same namespace used for pulling container images.
GitSecretRef
object
4 properties
Parallelism
integer
Used with Hyperparameter Optimization. Specifies the maximum number of pods the workload should run at any given time (applicable to standard training only).
Image
string
Docker image name. For more information, see [Images](https://kubernetes.io/docs/concepts/containers/images). The image name is mandatory for creating a worklo…
EnvironmentVariableUserCredential
object
Defines a reference to a user-created credential and a specific key within that credential whose value will populate the environment variable. User credentials…
2 properties
Annotation
object
Annotation details to be populated into the container.
3 properties
TerminationGracePeriodMaster
integer
Duration in seconds the pod needs to terminate gracefully upon probe failure. The grace period is the duration in seconds after the processes running in the po…
SupersetSpec
CreateHomeDir
boolean
When set to true, creates a home directory for the container.
DistributedInferenceStartupPolicy
string
Determines when the worker pods should start during workload initialization. - LeaderCreated: Workers start after the leader pod is created. - LeaderReady: Wor…
GpuMemoryLimit
string
Limitation on the memory consumed by the workload, per GPU device. The system guarantees The gpuMemoryLimit must be no less than gpuMemoryRequest.
EnvironmentVariableConfigMap
object
Details of the configMap and key use to populate the environment variable
2 properties
DistributedSpecSpec
CpuCoreLimit
number
Limitations on the number of CPUs consumed by the workload (0.5, 1, .etc). The system guarantees that this workload will not be able to consume more than this…
InferenceTemplatesListResponseItem
WorkspaceTemplateCreationRequest
DistributedInferenceServingPortAccessAuthorizationTypeEnum
string
Specifies who can send inference requests to the serving endpoint: Possible values: - public: No authorization is required. (Default) - authenticatedUsers: Any…
WorkspaceTemplatesListResponseItem
MasterTemplateSpec
object
31 properties
Capability
string
InferenceTemplate
DistributedInferenceReplicasField
object
1 property
AutoScalingCommonFields
object
GpuDevicesRequest
integer
Requested number of GPU devices. Currently if more than one device is requested, it is not possible to provide values for gpuMemory or gpuPortion.
NodePools
array
A prioritized list of node pools for the scheduler to run the workload on. The scheduler will always try to use the first node pool before moving to the next o…
PvcAddedAttrValue
object
2 properties
1 required
InferenceTemplateCreationRequest
DistributedInferenceLeaderSpecFields
object
1 property
NfsInstance
object
InferencesMinReplicasField
object
1 property
SecretItems1
array
Set of secret volumes to use in the workload
MetricThresholdPercentageField
object
1 property
PodAffinity
object
Pod affinity scheduling rules (e.g. co-locate this workload in the same node, zone, etc. as some other workloads).
2 properties
NfsItems
array
Set of nfs volumes to use in the workload.
EnvironmentVariablePodFieldReference
object
Details of the field-reference and key use to populate the environment variable
1 property
ServingPortAccessAuthorizationTypeEnum
string
Specifies who can send inference requests to the serving endpoint: Possible values: - public: No authorization is required. (Default) - authenticatedUsers: Any…
MatchExpression
object
A selector that contains values, a key, and an operator that relates the key and values.
3 properties
2 required
GpuRequestType
string
Sets the unit type for GPU resources requests. Stated in terms of portion or memory. Sets the unit type for other GPU request fields. If gpuDevicesRequest 1, o…
DistributedTemplate
EmptyDir
object
3 properties
PvcItems
array
Set of pvc persistent volume claims to use in the workload.
DataVolumeItems
array
Set of data volumes to use in the workload.
DistributedInferenceServingPortProtocol
string
The protocol used to access the port.
PodAffinityType
string
The affinity type, required or preferred. (mandatory)
ReadOnlyRootFileSystem
boolean
If true, mounts the container's root filesystem as read-only.
ConfigMapInstance
object
WorkspaceTemplateUpdateRequest
Command
string
A command to the server as the entry point of the container running the workload.
TemplateMasterSection
object
2 properties
DistributedFramework
string
The distributed training framework used in the workload.
ExposedUrls
array
Set of container ports that the workload exposes via URLs.
ActivationReplicasField
object
1 property
ProbeHandlerScheme
string
Scheme to use for connecting to the host, defaults to HTTP.
RunAsNonRoot
boolean
Force the container to run as a non-root user.
Args
string
Arguments to the command that the container running the workload executes.
DataVolumeInstance
object
ServingConfiguration
object
The inference workload serving configuration.
2 properties
TemplateNameOptional
string
The name of the template.
TemplateDescription
string
A description of the template.
PriorityClass
string
Specifies the priority class for the workload, which determines its scheduling behavior. Valid values are: very-low, low, medium-low, medium, medium-high, high…
NodeSelectorTerm
object
A null or empty node selector term matches no objects. The requirements of them are ANDed.
1 property
WorkspaceTemplatesListResponse
object
2 properties
SshAuthMountPath
string
Specifies the directory where SSH keys are mounted. (applicable only for MPI)
PaginationInfo
object
3 properties
WorkingDir
string
Container's working directory. If not specified, the container runtime default will be used. This may be configured in the container image.
SupersetRestartPolicy
string
DistributedTemplateSpec
FieldsToClear
object
array of xpath expression with fields that their values should be cleared
1 property
PvcVolumeMode
string
Default volume mode for the PVC. Choose between Filesystem (default) or Block.
Label
object
Label details to be populated into the container.
3 properties
TemplateAssets
DistributedInferenceStartupPolicyField
object
1 property
GitItems
array
Set of git repositories to use in the workload.
SeccompProfileType
string
Indicates which kind of seccomp profile will be applied to the container. The options are a. RuntimeDefault - the container runtime default profile should be u…
ServingConfigurationField
object
1 property
RestartPolicy
string
Specify the restart policy of the workload pods. Default is empty, which is determine by the framework default
DefaultMode
string
File permission mode in octal string format. This value must be a 4-digit octal number, representing the default file mode when mounting a Secret or ConfigMap…
Tolerations
array
Set of tolerations to apply to the workload.
TemplatesListResponse
object
2 properties
Nfs
object
4 properties
PvcInstance
object
TrainingTemplatesListResponse
object
2 properties
GitAuthenticationMethod
string
Specifies the authentication method to use when accessing the Git repository. This is required for private repositories - password - Authenticate using a usern…
AutoScaling
object
AutoDeletionTimeAfterPreemption
integer
Specifies the duration after which a finished workload (completed or failed) will be automatically deleted. The default is 30 days. Log retention is managed se…
CpuMemoryRequest
string
The amount of CPU memory to allocate for this workload (1G, 20M, .etc). The workload will receive at least this amount of memory. Note that the workload will n…
ExtendedResource
object
Quantity of an extended resource.
3 properties
TrainingTemplatePatchRequest
TerminateAfterPreemption
boolean
Indicates if the job should be terminated by the system after it has been preempted.
EmptyDirItems
array
A list of emptyDir volumes to mount in the workload.
AutoDeletionTimeAfterPreemptionMaster
integer
Specifies the duration after which a finished workload (completed or failed) will be automatically deleted. The default is 30 days. Log retention is managed se…
PortServiceType
string
The service type of the port (mandatory).
ConcurrencyHardLimitField
object
1 property
GpuPortionRequest
number
Required if and only if gpuRequestType is portion. States the portion of the GPU to allocate for the created workload, per GPU device, between 0 and 1. The def…
RelatedUrl
object
A URL that is related to the workload. For example, a URL to an external server providing statistics or logging about the workload.
4 properties
TemplateAssetsIdsOptional
object
WorkspaceTemplate
RunnableInfo
object
whether the template can be submitted, as is
2 properties
GpuPortionLimit
number
Limitations on the portion consumed by the workload, per GPU device. The system guarantees The gpuPotionLimit must be no less than the gpuPortionRequest.
HostPathInstance
object
TemplateName
string
The name of the template.
WorkspaceTemplateSpec
TemplateComplianceInfo
object
1 property
TrainingTemplateCreationRequest
MasterSpecSameAsWorker
boolean
used for distributed workloads to indicate that the master spec should be the same as the worker spec. in this case, masterSpec should not be specified.
MpiLauncherCreationPolicy
string
Define whether the MPI Launcher is created in parallel with the workers, or if its creation is postponed until all workers are in Ready state. This prevents fa…
ScopeType
string
SupersetTemplate
Probes
object
Probes are used to determine if the container is healthy and ready to accept traffic.
1 property
S3Instance
object
S3Items
array
Set of s3 buckets to use in the workload.
EmptyDirInstance
object
MaxReplicas
integer
the upper limit for the number of worker pods that can be set by the autoscaler. Cannot be smaller than MinReplicas. (applicable only for PyTorch)
NodeType3
string
Nodes (machines), or a group of nodes on which the workload will run. To use this feature, your Administrator will need to label nodes. For more information, s…
ScaleDownDelayField
object
1 property
ExtendedResources
array
Extended resources and their quantity.
DistributedInferenceServingPortContainerAndProtocol
object
2 properties
TemplatePatchMetaFields
object
2 properties
1 required
TrainingTemplateUpdateRequest
ConfigMap
object
4 properties
TrainingTemplatesListResponseItem
InferenceTemplatesListResponse
object
2 properties
GitCommon
object
4 properties
ScopeId
string
The id of the cluster, department or project, depending on the scope type.
ScaleToZeroRetentionField
object
1 property
Secret5
Port
object
A port for accessing the workload.
7 properties
DistributedTemplatesListResponseItem
TrainingTemplateSpec
ServingPortAccess
object
4 properties
BackoffLimit
integer
Specifies the number of retries before marking a workload as failed (not applicable to Inference workloads). The default value is 6.
TrainingTemplate
DistributedTemplatesListResponse
object
2 properties
ImagePullSecret
object
A reference to a secret in the same namespace used to pull container images.
3 properties
AuthorizationType
string
Specifies who can access the connection URL: - authenticatedUsers: Any authenticated user or service account can access the URL; the authorizedUsers and author…
ClusterIdOptional
string
The id of the cluster.
HostIpc
boolean
Whether to enable host IPC. Defaults to false.
TolerationOperator
string
A key's relationship to the value. Equal uses key and value. Exists is equivalent to wildcard for value, so that a workload can tolerate all taints of a partic…
DepartmentIdOptional
string
The id of the department.
Tty
boolean
Whether this container should allocate a TTY for itself, also requires 'stdin' to be true.
RunAsUid
integer
The user id to run the entrypoint of the container which executes the workspace. Default to the value specified in the environment asset runAsUid field (option…
InferenceTemplateSpec
DistributedTemplateUpdateRequest
PvcAccessModes
object
Default access mode(s) applied to newly created PVCs unless explicitly overridden.
3 properties
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from NVIDIA Run:ai 12
Other APIs NVIDIA Run:ai publishes across the network.
NVIDIA Run:ai Access Keys API
NVIDIA Run:ai Access rules API
NVIDIA Run:ai Administrator Command Line Interface API
NVIDIA Run:ai AI Applications API
NVIDIA Run:ai Applications API
NVIDIA Run:ai AuditLogs API
NVIDIA Run:ai Clusters API
NVIDIA Run:ai Compute API
NVIDIA Run:ai ConfigMap API
NVIDIA Run:ai Credentials API
NVIDIA Run:ai Datasources API
NVIDIA Run:ai Datavolumes API
#Workload templates