NVIDIA Run:ai Workspaces API
A Workspace is a simplified tool for researchers to conduct experiments, build AI models, access standard MLOps tools, and collaborate with their peers.Workspaces abstract complex concepts related to running containerized workloads in a Kubernetes environment and are built from predefined setups that includenetworking, storage, secrets and other resources. All the setup and configurations for research, including container images, data sets, resource requests, as well as all tools are included. for the research, in a single place. It answers the research needs while ensuring infrastructure owners keep control and allocation efficiency.A workspace is associated with a specific NVIDIA Run:ai project and you can have multiple workspaces under a specific project. For more information, see [Workspaces](https://run-ai-docs.nvidia.com/saas/workloads-in-nvidia-run-ai/using-workspaces/running-workspace).
NVIDIA Run:ai Workspaces 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 Workspaces. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and authentication docs.
This API exposes 5 operations across 4 paths, and defines 141 schemas. It is described by OpenAPI 3.0.3, at version latest.
Requests are made against a single base URL, https://app.run.ai.
5 operations
4 paths
141 schemas
1 DELETE1 GET3 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 1
NVIDIA Run:ai Workspaces 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 5
Across 4 paths, the API surfaces 5 operations — 1 DELETE, 1 GET, 3 POST. Each is listed below with its method, path, parameters, and response codes.
Workspaces 5
A Workspace is a simplified tool for researchers to conduct experiments, build AI models, access standard MLOps tools, and collaborate with their peers. Workspaces abstract comple…
POST
/api/v1/workloads/workspaces
Create a workspace.
DELETE
/api/v1/workloads/workspaces/{workloadId}
Delete a workspace.
GET
/api/v1/workloads/workspaces/{workloadId}
Get workspace data.
POST
/api/v1/workloads/workspaces/{workloadId}/suspend
Suspend a workspace.
POST
/api/v1/workloads/workspaces/{workloadId}/resume
Resume a workspace.
Schemas 141
The contract defines 141 schemas that model the data the API accepts and returns. The most detailed are WorkloadMeta1 (11 properties), ExposedUrl (9 properties), EnvironmentVariable (8 properties), Toleration (7 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
Probe
object
6 properties
ExposedUrl
object
A URL for accessing the workload.
9 properties
WorkloadId2
string
A unique ID of the workload.
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.
Error
object
3 properties
2 required
ExcludeField
object
1 property
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.
Toleration
object
Toleration details.
7 properties
ClusterId
string
The id of the cluster.
S3AccessKey
object
3 properties
SecretFieldsNonUpdatable
object
1 property
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…
Workspace1
HostPath
object
4 properties
SecretFieldsUpdatable
object
2 properties
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.
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
Annotations
array
Set of annotations to populate into the container running the workload.
WorkloadDesiredPhase
string
The desired phase of the workload.
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
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…
HostPathItems
array
Set of host paths to use in the workload.
WorkloadName
string
The name of 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
DepartmentId2
string
The id of the department.
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…
StorageInstanceName
object
1 property
EnvironmentVariables
array
Set of environment variables to populate into the container running the workload.
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.
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
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…
ImagePullSecrets
array
A list of references to Kubernetes secrets in the same namespace used for pulling container images.
GitSecretRef
object
4 properties
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
CreateHomeDir
boolean
When set to true, creates a home directory for the container.
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
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…
Capability
string
WorkloadCreationMeta
object
4 properties
3 required
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
NfsInstance
object
SecretItems1
array
Set of secret volumes to use in the workload
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
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…
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.
PodAffinityType
string
The affinity type, required or preferred. (mandatory)
ReadOnlyRootFileSystem
boolean
If true, mounts the container's root filesystem as read-only.
ConfigMapInstance
object
Command
string
A command to the server as the entry point of the container running the workload.
ExposedUrls
array
Set of container ports that the workload exposes via URLs.
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.
WorkspaceSpec
object
The specifications of the workspace to be created.
1 property
SubmitWithTemplateId
object
1 property
Args
string
Arguments to the command that the container running the workload executes.
DataVolumeInstance
object
ComplianceIssuesV2
object
1 property
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…
Phase
string
NodeSelectorTerm
object
A null or empty node selector term matches no objects. The requirements of them are ANDed.
1 property
WorkingDir
string
Container's working directory. If not specified, the container runtime default will be used. This may be configured in the container image.
SubmissionErrorV2
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
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…
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.
Nfs
object
4 properties
PvcInstance
object
WorkloadMeta1
object
11 properties
8 required
GitAuthenticationMethod
string
Specifies the authentication method to use when accessing the Git repository. This is required for private repositories - password - Authenticate using a usern…
ProjectId
string
The id of the project.
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
HttpResponse
object
2 properties
2 required
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.
PortServiceType
string
The service type of the port (mandatory).
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
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
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
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…
ExtendedResources
array
Extended resources and their quantity.
WorkspaceSpecSpec
ConfigMap
object
4 properties
GitCommon
object
4 properties
Secret5
Port
object
A port for accessing the workload.
7 properties
BackoffLimit
integer
Specifies the number of retries before marking a workload as failed (not applicable to Inference workloads). The default value is 6.
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…
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…
WorkspaceCreationRequest
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…
PvcFieldsUpdatable
object
1 property
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
#Workspaces