NVIDIA Run:ai Template API
Templates are a pre-set configuration used to quickly configure and submit workloads using existing assets.
Templates are a pre-set configuration used to quickly configure and submit workloads using existing assets.
openapi: 3.2.0
info:
version: latest
description: '# Introduction
The NVIDIA Run:ai Control-Plane API reference is a guide that provides an easy-to-use programming interface for adding various tasks to your application, including workload submission, resource management, and administrative operations.
NVIDIA Run:ai APIs are accessed using *bearer tokens*. To obtain a token, you need to create a **Service account** through the NVIDIA Run:ai user interface.
To create a service account, in your UI, go to Access → Service Accounts (for organization-level service accounts) or User settings → Access Keys (for user access keys), and create a new one.
After you have created a new service account, you will need to assign it access rules.
To assign access rules to the service account, see [Create access rules](https://run-ai-docs.nvidia.com/saas/infrastructure-setup/authentication/accessrules#create-or-delete-rules).
Make sure you assign the correct rules to your service account. Use the [Roles](https://run-ai-docs.nvidia.com/saas/infrastructure-setup/authentication/roles) to assign the correct access rules.
To get your access token, follow the instructions in [Request a token](https://run-ai-docs.nvidia.com/saas/reference/api/rest-auth/#request-an-api-token).
'
title: NVIDIA Run:ai Access Keys Template API
x-logo:
url: https://api.redocly.com/registry/raw/runai-xq8/saas/latest/public/runai-logo-api.png
altText: NVIDIA Run:ai
href: https://run.ai
license:
name: NVIDIA Run:ai
url: https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-software-license-agreement/
servers:
- url: https://app.run.ai
security:
- bearerAuth: []
tags:
- name: Template
description: Templates are a pre-set configuration used to quickly configure and submit workloads using existing assets.
paths:
/api/v1/asset/workload-template:
get:
summary: List templates.
description: Retrieve a list of templates.
operationId: list_templates
deprecated: true
tags:
- Template
parameters:
- $ref: '#/components/parameters/AssetNameFilter'
- $ref: '#/components/parameters/AssetScopeFilter'
- $ref: '#/components/parameters/AssetProjectFilter'
- $ref: '#/components/parameters/AssetDepartmentFilter'
- $ref: '#/components/parameters/AssetClusterFilter'
- $ref: '#/components/parameters/DistributedFrameworkQuery'
- $ref: '#/components/parameters/IsDistributedQuery'
- $ref: '#/components/parameters/IsTrainingQuery'
- $ref: '#/components/parameters/IsWorkspaceQuery'
responses:
'200':
description: Request completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkloadTemplateListResponse'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
post:
summary: Create a template.
description: Use to create a template.
operationId: create_template
deprecated: true
tags:
- Template
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WorkloadTemplateCreationRequest'
responses:
'202':
description: Request accepted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkloadTemplate'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'409':
$ref: '#/components/responses/409Conflict'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
/api/v1/asset/workload-template/{AssetId}:
parameters:
- $ref: '#/components/parameters/AssetId'
get:
summary: Get a template.
description: Retrieve the details of a template by id.
operationId: get_template_by_id
deprecated: true
tags:
- Template
responses:
'200':
description: Request completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkloadTemplate'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
put:
summary: Update a template.
description: Use to update the details of a template by id.
operationId: update_template
deprecated: true
tags:
- Template
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WorkloadTemplateUpdateRequest'
responses:
'202':
description: Request accepted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkloadTemplate'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'409':
$ref: '#/components/responses/409Conflict'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
delete:
summary: Delete a template.
description: Use to delete a template by id.
operationId: delete_template_by_id
deprecated: true
tags:
- Template
responses:
'202':
$ref: '#/components/responses/202Accepted'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
components:
schemas:
PodAffinity:
description: Pod affinity scheduling rules (e.g. co-locate this workload in the same node, zone, etc. as some other workloads).
type:
- object
- 'null'
properties:
type:
$ref: '#/components/schemas/PodAffinityType'
key:
description: The label key to use. (mandatory)
type:
- string
- 'null'
pattern: .*
InitialReplicasField:
properties:
initialReplicas:
description: The number of replicas to run when initializing the workload for the first time. Defaults to minReplicas, or to 1 if minReplicas is set to 0
type:
- integer
- 'null'
format: int32
minimum: 0
NodeAffinityRequired:
type:
- object
- 'null'
description: 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 specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node.
properties:
nodeSelectorTerms:
description: A list of node selector terms. The terms are ORed.
type: array
items:
$ref: '#/components/schemas/NodeSelectorTerm'
DataSourceOverrides:
description: specific fields to override in the data source.
type:
- object
- 'null'
properties:
containerPath:
type:
- string
- 'null'
minLength: 1
example: /container/directory
SupplementalGroups:
description: 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 of the environment asset is not `fromTheImage`, and `overrideUidGidInWorkspace` is enabled. Using an empty string implies reverting the supplementary groups of the image.
type:
- string
- 'null'
example: 2,3,5,8
pattern: .*
Tolerations:
description: Set of tolerations to apply to the workload.
type:
- array
- 'null'
items:
$ref: '#/components/schemas/Toleration'
InitializationTimeoutField:
properties:
initializationTimeoutSeconds:
description: Use `servingConfiguration.initializationTimeoutSeconds` instead. If this field is set, it will be ignored and the value under `servingConfiguration` will be used. The maximum amount of time (in seconds) to wait for the container to become ready.
type:
- integer
- 'null'
format: int32
minimum: 1
deprecated: true
TerminationGracePeriod:
description: 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 pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. Value must be non-negative integer. The value zero indicates stop immediately via the kill signal (no opportunity to shut down).
format: int64
type:
- integer
- 'null'
minimum: 0
example: 20
Label:
description: Label details to be populated into the container.
properties:
name:
description: The name of the label (mandatory)
type:
- string
- 'null'
minLength: 1
maxLength: 63
example: stage
pattern: .*
value:
description: The value of the label.
type:
- string
- 'null'
example: initial-research
pattern: .*
exclude:
description: Use 'true' in case the label is defined in defaults of the policy, and you wish to exclude it from the workload.
type:
- boolean
- 'null'
example: false
type:
- object
- 'null'
EnvironmentVariablePodFieldReference:
description: Details of the field-reference and key use to populate the environment variable
properties:
path:
description: The field path resource. (mandatory)
type:
- string
- 'null'
minLength: 1
example: metadata.name
pattern: .*
type:
- object
- 'null'
Labels:
description: Set of labels to populate into the container running the workload.
type:
- array
- 'null'
items:
$ref: '#/components/schemas/Label'
ImagePullSecrets:
description: A list of references to Kubernetes secrets in the same namespace used for pulling container images.
type:
- array
- 'null'
items:
$ref: '#/components/schemas/ImagePullSecret'
AssetCreationRequest:
allOf:
- $ref: '#/components/schemas/AssetUpdatableFields'
- $ref: '#/components/schemas/AssetCreationFields'
example:
name: my-asset
scope: tenant
workloadSupportedTypes:
workspace: false
training: false
inference: false
distributed: true
distFramework: TF
ServingPortAccessAuthorizationTypeEnum:
type:
- string
- 'null'
enum:
- public
- authenticatedUsers
- authorizedUsers
- authorizedGroups
- authorizedUsersOrGroups
description: 'Specifies who can send inference requests to the serving endpoint:
Possible values:
- `public`: No authorization is required. (Default)
- `authenticatedUsers`: Any NVIDIA Run:ai authenticated user and service account can send requests.
- `authorizedUsers`: Only users listed in the authorizedUsers field can send requests.
- `authorizedGroups`: Only members of user groups listed in the authorizedGroups field can send requests.
- `authorizedUsersOrGroups`: Requires either authorizedUsers or authorizedGroups to be provided; if neither is set, or if both are set, a mutual exclusion error is reported. Supported from cluster version 2.19.
'
SpecificRunConnectionInfo:
required:
- connectionName
properties:
name:
type: string
minLength: 1
description: Unique identifier of the connection. Will be used to correlate between the information given here and the information provided for the connection in the environment asset.
nodePort:
description: Port number of the host that will be connected with the container port. Required if and only if isCustomPort is set to true in the environment asset.
type:
- integer
- 'null'
format: int32
minimum: 0
maximum: 65535
externalUrl:
description: URL to associated with the container port. Required if and only if isCustomExternalUrl is set to true in the environment asset.
type:
- string
- 'null'
minLength: 1
authorizedUsers:
description: List of users or applications that are allowed to access the URL. Note that authorizedUsers and authorizedGroups are mutually exclusive.
type:
- array
- 'null'
items:
type: string
authorizedGroups:
description: Specifies the names of those groups that are allowed to access the connection. Note that authorizedUsers and authorizedGroups are mutually exclusive.
type:
- array
- 'null'
items:
type: string
DistributedFramework:
description: The distributed training framework used in the workload.
type:
- string
- 'null'
enum:
- MPI
- PyTorch
- TF
- XGBoost
- JAX
Args:
description: Arguments to the command that the container running the workload executes.
type:
- string
- 'null'
minLength: 1
example: -x my-script.py
pattern: .*
ToolType:
description: Super set of Internal and External tool types.
type: string
minLength: 1
enum:
- jupyter-notebook
- pycharm
- visual-studio-code
- tensorboard
- rstudio
- mlflow
- custom
- wandb
- matlab
- comet
- chatbot-ui
AutoDeletionTimeAfterPreemption:
description: Specifies the duration after which a finished workload (completed or failed) will be automatically deleted. The default is 30 days. Log retention is managed separately.
format: int64
type:
- integer
- 'null'
example: 15
AutoScalingCommonFields:
allOf:
- $ref: '#/components/schemas/MetricThresholdPercentageField'
- $ref: '#/components/schemas/InferencesMinReplicasField'
- $ref: '#/components/schemas/InferencesMaxReplicasField'
- $ref: '#/components/schemas/InitialReplicasField'
- $ref: '#/components/schemas/ActivationReplicasField'
- $ref: '#/components/schemas/ConcurrencyHardLimitField'
- $ref: '#/components/schemas/ScaleToZeroRetentionField'
- $ref: '#/components/schemas/ScaleDownDelayField'
- $ref: '#/components/schemas/InitializationTimeoutField'
type:
- object
- 'null'
EnvironmentVariableCredential:
description: Details of the secret and key use to populate the environment variable. (mutually exclusive with value)
properties:
assetId:
description: Unique identifier of the asset. (mandatory)
type:
- string
- 'null'
minLength: 1
format: uuid
key:
description: The key in the secret resource. (mandatory)
type:
- string
- 'null'
minLength: 1
example: POSTGRES_PASSWORD
type:
- object
- 'null'
PodAffinityType:
description: The affinity type, required or preferred. (mandatory)
type:
- string
- 'null'
enum:
- Required
- Preferred
Annotations:
description: Set of annotations to populate into the container running the workload.
type:
- array
- 'null'
items:
$ref: '#/components/schemas/Annotation'
Annotation:
description: Annotation details to be populated into the container.
properties:
name:
description: The name of the annotation (mandatory)
type:
- string
- 'null'
minLength: 1
maxLength: 63
example: billing
pattern: .*
value:
description: The value of the annotation.
type:
- string
- 'null'
example: my-billing-unit
pattern: .*
exclude:
description: Use 'true' in case the annotation is defined in defaults of the policy, and you wish to exclude it from the workload.
type:
- boolean
- 'null'
default: false
example: false
type:
- object
- 'null'
RunAsUid:
description: 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 (optional). Use only when the source uid/gid of the environment asset is not `fromTheImage`, and `overrideUidGidInWorkspace` is enabled.
type:
- integer
- 'null'
format: int64
example: 500
BackoffLimit:
description: Specifies the number of retries before marking a workload as failed (not applicable to Inference workloads). The default value is 6.
format: int64
type:
- integer
- 'null'
example: 3
NodePools:
description: 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 one if the first is not available.
type:
- array
- 'null'
items:
type: string
pattern: .*
example:
- my-node-pool-a
- my-node-pool-b
AssetRef:
description: Reference information about an asset.
required:
- id
- name
properties:
id:
$ref: '#/components/schemas/AssetId'
name:
$ref: '#/components/schemas/AssetName'
AssetsRefOptional:
allOf:
- $ref: '#/components/schemas/AssetsRef'
type:
- object
- 'null'
AssetUpdateRequest:
allOf:
- $ref: '#/components/schemas/AssetUpdatableFields'
example:
name: my-asset
SpecificRunServingPortAccess:
properties:
servingPortAccess:
allOf:
- $ref: '#/components/schemas/ServingPortAccess'
type:
- object
- 'null'
type:
- object
- 'null'
DatasourceRef:
description: Reference information about a datasource asset.
required:
- id
- name
- kind
properties:
id:
$ref: '#/components/schemas/AssetId'
name:
$ref: '#/components/schemas/AssetName'
kind:
$ref: '#/components/schemas/AssetKind'
overrides:
$ref: '#/components/schemas/DataSourceOverrides'
EnvironmentVariableOfAsset:
description: Details of an environment variable which is populated into the container.
properties:
name:
description: The name of the environment variable. (mandatory)
type:
- string
- 'null'
minLength: 1
example: HOME
value:
description: The value of the environment variable. (mutually exclusive with credential, configMap and podFieldRef)
type:
- string
- 'null'
example: /home/my-folder
credential:
$ref: '#/components/schemas/EnvironmentVariableCredential'
configMap:
$ref: '#/components/schemas/EnvironmentVariableConfigMap'
podFieldRef:
$ref: '#/components/schemas/EnvironmentVariablePodFieldReference'
exclude:
description: Use 'true' in case the environment variable is defined in defaults of the policy, and you wish to exclude it from the workload.
type:
- boolean
- 'null'
example: false
description:
description: Description of the environment variable.
type:
- string
- 'null'
example: Home directory of the user.
type:
- object
- 'null'
Completions:
description: 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 the specified amount of pods has been reached (applicable to standard training only).
type:
- integer
- 'null'
format: int32
example: 1
EnvironmentVariableConfigMap:
description: Details of the configMap and key use to populate the environment variable
properties:
name:
description: The name of the config-map resource. (mandatory)
type:
- string
- 'null'
minLength: 1
example: my-config-map
pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
key:
description: The key in the config-map resource. (mandatory)
type:
- string
- 'null'
minLength: 1
example: MY_POSTGRES_SCHEMA
pattern: .*
type:
- object
- 'null'
AssetReadOnlyFields:
required:
- id
- kind
- createdBy
- createdAt
- updatedBy
- updatedAt
properties:
id:
$ref: '#/components/schemas/AssetId'
kind:
$ref: '#/components/schemas/AssetKind'
tenantId:
description: The id of the tenant.
type:
- integer
- 'null'
format: int32
createdBy:
description: The user who created the asset.
type: string
minLength: 1
createdAt:
description: The time at which the asset were created
type: string
minLength: 1
format: date-time
updatedBy:
description: The user who updated the asset.
type: string
minLength: 1
updatedAt:
description: The time at which the asset has been updated
type: string
minLength: 1
format: date-time
deletedAt:
description: Deletion time of the asset (relevant for assets that sync to the cluster)
type: string
minLength: 1
format: date-time
deletedBy:
description: The user who deleted the asset
type: string
minLength: 1
projectName:
description: The name of the project that the asset is associated with, for project scoped assets.
type:
- string
- 'null'
minLength: 1
updateCount:
$ref: '#/components/schemas/UpdateCount'
type: object
InferencesMinReplicasField:
properties:
minReplicas:
description: The minimum number of replicas for autoscaling. Defaults to 1. Use 0 to allow scale-to-zero
type:
- integer
- 'null'
format: int32
minimum: 0
Command:
description: A command to the server as the entry point of the container running the workload.
type:
- string
- 'null'
minLength: 1
example: python
pattern: .*
Scope:
description: The scope in which an asset can be used. The highest scope, system, is intended for internal purposes only.
type: string
minLength: 1
enum:
- system
- tenant
- cluster
- department
- project
SpecificRunAutoScaling:
properties:
autoScaling:
allOf:
- $ref: '#/components/schemas/AutoScalingCommonFields'
- $ref: '#/components/schemas/SpecificRunMetricFields'
type:
- object
- 'null'
type:
- object
- 'null'
AssetsRef:
description: Reference information about a set of assets. used to describe - assets comprising a workspace - assets comprising a workspace template - assets that use other assets (e.g. s3 asset which uses access key).
required:
- environment
properties:
environment:
description: environment asset.
allOf:
- $ref: '#/components/schemas/EnvironmentAssetRef'
compute:
$ref: '#/components/schemas/AssetsRefCompute'
datasources:
type: array
items:
$ref: '#/components/schemas/DatasourceRef'
workloadVolumes:
type: array
items:
type: string
HttpResponse:
required:
- code
- message
properties:
code:
type: integer
minimum: 100
maximum: 599
message:
type: string
NodeType1:
description: 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, see [Group Nodes](https://docs.run.ai/latest/admin/researcher-setup/limit-to-node-group). When using this flag with with Project-based affinity, it refines the list of allowable node groups set in the Project. For more information, see [Projects](https://docshub.run.ai/guides/platform-management/aiinitiatives/organization/projects).
type:
- string
- 'null'
minLength: 1
example: my-node-type
pattern: .*
AssetsRefCompute:
allOf:
- $ref: '#/components/schemas/AssetRef'
type:
- object
- 'null'
WorkloadTemplateCreationRequest:
required:
- meta
- spec
properties:
meta:
$ref: '#/components/schemas/AssetCreationRequest'
spec:
$ref: '#/components/schemas/SpecificRunCreationFields'
InferencesMaxReplicasField:
properties:
maxReplicas:
description: The maximum number of replicas for autoscaling. Defaults to minReplicas, or to 1 if minReplicas is set to 0
type:
- integer
- 'null'
format: int32
minimum: 1
InfoDistributed:
description: 'Parameters which apply to distributed training.
'
allOf:
- properties:
numWorkers:
type: integer
noMaster:
type:
- boolean
- 'null'
distFramework:
$ref: '#/components/schemas/DistributedFramework'
master:
$ref: '#/components/schemas/InfoDistMaster'
type:
- object
- 'null'
AssetUpdatableFields:
required:
- name
properties:
name:
$ref: '#/components/schemas/AssetName'
description:
$ref: '#/components/schemas/AssetDescription'
NodeSelectorTerm:
type:
- object
- 'null'
description: A null or empty node selector term matches no objects. The requirements of them are ANDed.
properties:
matchExpressions:
description: A list of node selector requirements by node's labels.
type: array
items:
$ref: '#/components/schemas/MatchExpression'
MatchExpression:
type:
- object
- 'null'
description: A selector that contains values, a key, and an operator that relates the key and values.
properties:
key:
description: The label key that the selector applies to (mandatory).
type: string
pattern: .*
operator:
$ref: '#/components/schemas/MatchExpressionOperator'
values:
description: An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer.
type: array
items:
type: string
pattern: .*
required:
- key
- operator
WorkloadTemplate:
required:
- meta
- spec
properties:
meta:
$ref: '#/components/schemas/AssetMeta'
spec:
$ref: '#/components/schemas/SpecificRunInfoFields'
MatchExpressionOperator:
description: Represents a key's relationship to a set of values (mandatory).
type: string
enum:
- In
- NotIn
- Exists
- DoesNotExist
- Gt
- Lt
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
- 'null'
pattern: .*
ActivationReplicasField:
properties:
activationReplicas:
description: The number of replicas to run when scaling-up from zero. Defaults to minReplicas, or to 1 if minReplicas is set to 0
type:
- integer
- 'null'
format: int32
minimum: 1
WorkloadTemplateListResponse:
type: object
required:
- entries
properties:
entries:
type: array
items:
$ref: '#/components/schemas/WorkloadTemplate'
Toleration:
description: Toleration details.
properties:
name:
description: The name of the toleration.
type:
- string
- 'null'
minLength: 1
pattern: .*
operator:
$ref: '#/components/schemas/TolerationOperator'
key:
description: The taint key that the toleration applies to. (mandatory)
type:
- string
- 'null'
pattern: .*
value:
description: The taint value the toleration matches to. Mandatory if operator is Exists, forbidden otherwise.
type:
- string
- 'null'
pattern: .*
effect:
$ref: '#/components/schemas/TolerationEffect'
seconds:
description: The period of time the toleration tolerates the taint. Valid only if effect is NoExecute. taint.
type:
- integer
- 'null'
minimum: 1
exclude:
description: Use 'true' in case the label is defined in defaults of the policy, and you wish to exclude it from the workload.
type:
- boolean
- 'null'
example: false
type:
- object
- 'null'
ImagePullSecret:
description: A reference to a secret in the same namespace used to pull container images.
properties:
name:
type: string
description: The name of the Kubernetes secret containing the image pull credentials.
pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
userCredential:
type:
- boolean
- 'null'
description: Indicates whether the secret is a user credential. Set to true if the secret was created by the user and is only accessible by them.
exclude:
description: Use 'true' in case the secret is defined in defaults of the policy, and you wish to exclude it from the workload.
type:
- boolean
- 'null'
default: false
example: false
type:
- object
- 'null'
InfoDistMaster:
description: 'Parameters which apply to the master in a distributed training.
'
type:
- object
- 'null'
properties:
assets:
$ref: '#/components/schemas/AssetsRefOptional'
specificEnv:
$ref: '#/components/schemas/SpecificRunParams'
EnvironmentVariablesOfAsset:
d
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/runai/refs/heads/main/openapi/runai-template-api-openapi.yml