OpenAPI Specification
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 Datasources 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: Datasources
description: Data source assets.
paths:
/api/v1/asset/datasource:
get:
summary: List datasource assets.
description: Returns a combined list of data-sources.
operationId: list_datasource_assets
tags:
- Datasources
parameters:
- $ref: '#/components/parameters/AssetNameFilter'
- $ref: '#/components/parameters/AssetScopeFilter'
- $ref: '#/components/parameters/AssetProjectFilter'
- $ref: '#/components/parameters/AssetDepartmentFilter'
- $ref: '#/components/parameters/AssetClusterFilter'
- $ref: '#/components/parameters/IncludeUsageInfo'
- $ref: '#/components/parameters/ComplyToProject'
- $ref: '#/components/parameters/ComplyToWorkloadType'
- $ref: '#/components/parameters/IncludeStatus'
- $ref: '#/components/parameters/AssetIdsFilter'
- $ref: '#/components/parameters/ComplyToReplicaType'
- $ref: '#/components/parameters/includeDescendants'
responses:
'200':
description: Request completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DatasourceListResponse'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
components:
responses:
403Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 403
message: You do not have sufficient permissions.
503ServiceUnavailable:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 503
message: Please try again in few minutes.
401Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
message: Issuer is not familiar.
schemas:
SecretAssetSpec:
allOf:
- $ref: '#/components/schemas/CredentialAsset'
- properties:
mountPath:
description: Local path within the workspace to which the Secret will be mapped to (mandatory)
type:
- string
- 'null'
minLength: 1
defaultMode:
$ref: '#/components/schemas/DefaultMode'
type: object
HostPathSpec:
allOf:
- $ref: '#/components/schemas/HostPath'
AssetsUsageRefCompute:
allOf:
- $ref: '#/components/schemas/AssetRef'
type:
- object
- 'null'
DataSourceOverrides:
description: specific fields to override in the data source.
type:
- object
- 'null'
properties:
containerPath:
type:
- string
- 'null'
minLength: 1
example: /container/directory
DatasourceListResponseEntry:
required:
- meta
- spec
properties:
meta:
$ref: '#/components/schemas/AssetMeta'
spec:
$ref: '#/components/schemas/DatasourceListResponseAssetSpec'
usedBy:
$ref: '#/components/schemas/AssetUsageInfo'
usageTimes:
$ref: '#/components/schemas/UsageTimesInfo'
compliance:
$ref: '#/components/schemas/ComplianceInfo'
status:
$ref: '#/components/schemas/AssetClusterStatusInfo'
clusterInfo:
$ref: '#/components/schemas/ClusterInfo1'
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
AssetDatasourceRef:
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'
deprecated: true
ComplianceInfo:
description: Compliance of an asset with creation of workloads in a given project.
properties:
imposed:
description: Whether the asset is imposed on created workloads by the administrator.
type: boolean
compliance:
description: Whether the asset info complies with creation of workloads in the project.
type: boolean
reason:
description: For asset that does not comply, specify one or more reason why.
type: array
items:
$ref: '#/components/schemas/ComplianceInfoReason'
type:
- object
- 'null'
ScopeId:
type: string
description: The id of the cluster, department or project, depending on the scope type.
ConfigMapAssetSpec:
allOf:
- $ref: '#/components/schemas/ConfigMap'
PvcVolumeMode:
description: Default volume mode for the PVC. Choose between Filesystem (default) or Block.
type:
- string
- 'null'
enum:
- Filesystem
- Block
AssetRef:
description: Reference information about an asset.
required:
- id
- name
properties:
id:
$ref: '#/components/schemas/AssetId'
name:
$ref: '#/components/schemas/AssetName'
PvcClaimSize:
description: 'Requested size for the PVC. Mandatory when existingPvc is false. Recommended sizes: TB/GB/MB/TIB/GIB/MIB'
type:
- string
- 'null'
pattern: ^([+]?[0-9.]+)([eEinumkKMGTP]*[-+]?[0-9]*)$
example: 1G
ScopeType:
type: string
enum:
- system
- tenant
- cluster
- department
- project
WorkloadRefAndStatus:
description: Id, name and status of a workspace or training
required:
- id
- name
properties:
id:
$ref: '#/components/schemas/WorkloadId1'
name:
$ref: '#/components/schemas/WorkloadName'
status:
description: The status of the workspace or training.
type: string
minLength: 1
PolicyRuleEnum:
description: Indicates which validation rule (e.g., min, max, step, options, required, canEdit, canAdd) conflicted with policy restrictions, causing the asset or template to be rejected.
type:
- string
- 'null'
enum:
- min
- max
- step
- options
- required
- canEdit
- canAdd
- locked
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
ComplianceInfoReason:
description: An issue preventing the use of a template or asset for creating workloads in a given project.
required:
- details
properties:
field:
description: For policy related issues, includes a json path to the field in the policy for which the issue applies.
type:
- string
- 'null'
pattern: .*
details:
description: Explanation of the issue.
type: string
pattern: .*
rule:
$ref: '#/components/schemas/PolicyRuleEnum'
ConfigMap:
properties:
configMap:
description: The name of the ConfigMap resource. (mandatory)
type:
- string
- 'null'
minLength: 1
pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
mountPath:
description: Local path within the workload to which the ConfigMap will be mapped to. (mandatory)
type:
- string
- 'null'
minLength: 1
pattern: .*
subPath:
description: Path within the volume from which the container's volume should be mounted.
type:
- string
- 'null'
minLength: 1
pattern: .*
defaultMode:
$ref: '#/components/schemas/DefaultMode'
type:
- object
- 'null'
DatasourceListResponseAssetSpec:
properties:
hostPath:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/HostPathSpec'
nfs:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/NFSAssetSpec'
pvc:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/PVCAssetSpec'
git:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/GitAssetSpec'
s3:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/S3AssetSpec'
config_map:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/ConfigMapAssetSpec'
secret:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/SecretAssetSpec'
GitCredentialId:
properties:
credentialId:
description: UUID of a credential asset of type generic secret or user id / password required for authenticating with private Git repositories. For generic secret, the credential asset must contain a key-value pair where the key is ssh (lowercase) and the value is a valid private SSH key
type:
- string
- 'null'
format: uuid
minLength: 1
S3Common:
properties:
bucket:
description: The name of the bucket. (mandatory)
type:
- string
- 'null'
minLength: 1
example: my-bucket
path:
description: Local path within the workload to which the S3 bucket will be mapped. (mandatory)
type:
- string
- 'null'
minLength: 1
example: /container/my-bucket
url:
description: The url of the S3 service provider. The default is the URL of the Amazon AWS S3 service.
type:
- string
- 'null'
minLength: 1
example: https://s3.amazonaws.com
type:
- object
- 'null'
CredentialAsset:
properties:
credentialAssetId:
description: ID of credentials asset (mandatory)
type:
- string
- 'null'
format: uuid
minLength: 1
PvcAddedAttrValue:
type: object
required:
- key
properties:
key:
type: string
minLength: 1
maxLength: 63
pattern: ^([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]$
example: dnsname
value:
type: string
example: my.dns.com
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
PvcFieldsUpdatable:
properties:
path:
description: Local path within the workload to which the PVC bucket will be mapped. (mandatory)
type:
- string
- 'null'
minLength: 1
example: /container/my-claim
pattern: .*
type:
- object
- 'null'
DefaultMode:
type:
- string
- 'null'
description: '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 as a volume.
'
minLength: 4
maxLength: 4
example: '0644'
pattern: 0[0-7]{3}
S3AccessKeyAsset:
properties:
accessKeyAssetId:
description: ID of credentials asset of type access-key, for private S3 buckets.
type:
- string
- 'null'
format: uuid
minLength: 1
UsageTimesInfo:
description: Details about times the asset has been used by workloads, etc.
properties:
lastUsedByWorkload:
description: The time at which the asset were last used by a workload of given type and project. This field requires complyToProject and complyToWorkload types flags of the API, to specify the workload type and project id.
type:
- string
- 'null'
minLength: 1
format: date-time
type:
- object
- 'null'
AssetSyncStatusEnum:
type: string
enum:
- Creating
- Deleting
- Failed
- Deletion failed
- Issues found
- No issues found
- No status
- Updating
AssetClusterStatusIssue:
type: object
required:
- scopeId
- scopeType
- issue
properties:
scopeId:
$ref: '#/components/schemas/ScopeId'
scopeType:
$ref: '#/components/schemas/ScopeType'
issue:
$ref: '#/components/schemas/AssetClusterStatusIssueEnum'
GitCommon:
properties:
repository:
description: URL to a remote Git repository. The content of this repository will be mapped to the container running the workload. (mandatory)
type:
- string
- 'null'
minLength: 1
example: https://github.com/my-git/my-repo
branch:
description: Specific branch to synchronize the repository from.
type:
- string
- 'null'
minLength: 1
example: main
revision:
description: Specific revision to synchronize the repository from.
type:
- string
- 'null'
minLength: 1
path:
description: Local path within the workload to which the Git repository will be mapped (mandatory).
type:
- string
- 'null'
minLength: 1
example: /container/my-repository
type:
- object
- 'null'
AssetUpdatableFields:
required:
- name
properties:
name:
$ref: '#/components/schemas/AssetName'
description:
$ref: '#/components/schemas/AssetDescription'
ClaimInfo:
description: Claim information for the newly created PVC. The information should not be provided when attempting to use existing PVC.
properties:
size:
$ref: '#/components/schemas/PvcClaimSize'
storageClass:
description: Storage class name to associate with the PVC. This parameter may be omitted if there is a single storage class in the system, or you are using the default storage class. For more information, see [Storage class](https://kubernetes.io/docs/concepts/storage/storage-classes).
type:
- string
- 'null'
minLength: 1
example: my-storage-class
pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
accessModes:
$ref: '#/components/schemas/PvcAccessModes'
volumeMode:
$ref: '#/components/schemas/PvcVolumeMode'
addedAttrValues:
$ref: '#/components/schemas/PvcAddedAttrValues'
type:
- object
- 'null'
AssetsUsageRef:
description: Reference information about usage of assets by other assets, for example datasources that uses credentials.
properties:
environment:
type:
- object
- 'null'
description: environment asset.
allOf:
- $ref: '#/components/schemas/EnvironmentAssetRef'
deprecated: true
environments:
type: array
items:
$ref: '#/components/schemas/AssetRef'
compute:
$ref: '#/components/schemas/AssetsUsageRefCompute'
deprecated: true
computes:
type: array
items:
$ref: '#/components/schemas/AssetRef'
datasources:
type: array
items:
$ref: '#/components/schemas/AssetDatasourceRef'
AssetClusterStatusIssues:
type: array
items:
$ref: '#/components/schemas/AssetClusterStatusIssue'
PvcAccessModes:
description: Default access mode(s) applied to newly created PVCs unless explicitly overridden.
properties:
readWriteOnce:
description: Mount the volume as read/write by a single node.
type:
- boolean
- 'null'
default: true
readOnlyMany:
description: Mount the volume as read-only by many nodes.
type:
- boolean
- 'null'
default: false
readWriteMany:
description: Mount the volume as read/write by many nodes.
type:
- boolean
- 'null'
default: false
type:
- object
- 'null'
PvcAddedAttrValues:
description: 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 configuration (see k8s-objects-tracker for further info).
type: array
items:
$ref: '#/components/schemas/PvcAddedAttrValue'
S3AssetSpec:
allOf:
- $ref: '#/components/schemas/S3Common'
- $ref: '#/components/schemas/S3AccessKeyAsset'
Pvc:
allOf:
- $ref: '#/components/schemas/PvcFieldsUpdatable'
- $ref: '#/components/schemas/PvcFieldsNonUpdatable'
AssetId:
description: Unique identifier of the asset.
type: string
format: uuid
minLength: 1
Error:
required:
- code
- message
properties:
code:
type: integer
minimum: 100
maximum: 599
message:
type: string
details:
type: string
example:
code: 400
message: Bad request - Resource should have a name
AssetKind:
description: The kind of the asset.
type: string
minLength: 1
enum:
- compute
- environment
- accessKey
- dockerRegistry
- password
- genericSecret
- registry
- s3
- git
- nfs
- pvc
- hostPath
- workload-template
- model
- config-map
- secret-volume
- data-volume
- ngcApiKey
GitPasswordAsset:
properties:
passwordAssetId:
description: UUID of a credential asset of type userid / password. This credential is required for authenticating with private Git repositories using SSH. (deprecated - use credentialId instead).
type:
- string
- 'null'
format: uuid
minLength: 1
Nfs:
properties:
path:
description: Path that is exported by the NFS server (mandatory). For more information, see [NFS](https://kubernetes.io/docs/concepts/storage/volumes#nfs).
type:
- string
- 'null'
minLength: 1
example: /container/nfs
pattern: .*
readOnly:
description: Force the NFS export to be mounted with read-only permissions.
type:
- boolean
- 'null'
default: true
server:
description: The hostname or IP address of the NFS server. (mandatory)
type:
- string
- 'null'
minLength: 1
example: my.nfs.com
pattern: .*
mountPath:
description: The path that the NFS volume will be mounted to when in use. (mandatory)
type:
- string
- 'null'
minLength: 1
example: /local/nfs
pattern: .*
type:
- object
- 'null'
AssetClusterStatusInfo:
properties:
status:
$ref: '#/components/schemas/AssetSyncStatusEnum'
issues:
$ref: '#/components/schemas/AssetClusterStatusIssues'
message:
type: string
url:
type: string
type:
- object
- 'null'
DatasourceListResponse:
required:
- entries
properties:
entries:
type: array
items:
$ref: '#/components/schemas/DatasourceListResponseEntry'
GitAssetSpec:
allOf:
- $ref: '#/components/schemas/GitCommon'
- $ref: '#/components/schemas/GitPasswordAsset'
- $ref: '#/components/schemas/GitCredentialId'
ClusterIdOptional:
description: The id of the cluster.
type:
- string
- 'null'
format: uuid
minLength: 1
example: 71f69d83-ba66-4822-adf5-55ce55efd210
ClusterResourceInfo:
properties:
name:
example: password-credential-1
description: The name of the resource created for the asset in the cluster.
type:
- string
- 'null'
type:
- object
- 'null'
AssetUsageInfo:
description: Details about resources that use the asset.
properties:
workspaces:
description: workspaces that rely on this asset.
type: array
items:
$ref: '#/components/schemas/WorkloadRefAndStatus'
trainings:
description: trainings that rely on this asset.
type: array
items:
$ref: '#/components/schemas/WorkloadRefAndStatus'
distributed:
description: distributed trainings that rely on this asset.
type: array
items:
$ref: '#/components/schemas/WorkloadRefAndStatus'
inferences:
description: inferences that rely on this asset.
type: array
items:
$ref: '#/components/schemas/WorkloadRefAndStatus'
templates:
description: templates that rely on this asset.
type: array
items:
$ref: '#/components/schemas/AssetRef'
assets:
description: list of other assets that use this asset. specifically, accessKeys used by s3, and passwords used by git.
$ref: '#/components/schemas/AssetsUsageRef'
type:
- object
- 'null'
NFSAssetSpec:
allOf:
- $ref: '#/components/schemas/Nfs'
AssetClusterStatusIssueEnum:
type: string
enum:
- ReplicationError
- LostPhase
- NotCreated
AssetName:
description: The name of the asset.
type: string
minLength: 1
example: my-asset
EnvironmentAssetRef:
description: Reference information about environment asset.
required:
- id
- name
properties:
id:
$ref: '#/components/schemas/AssetId'
name:
$ref: '#/components/schemas/AssetName'
toolTypes:
description: the type of tools as defined in the connections of the environment asset.
type:
- array
- 'null'
items:
$ref: '#/components/schemas/ToolType'
PvcFieldsNonUpdatable:
properties:
existingPvc:
description: Verify existing PVC. PVC is assumed to exist when set to `true`. If set to `false`, the PVC will be created, if it does not exist.
type:
- boolean
- 'null'
default: false
claimName:
description: Name for the PVC. Allow referencing it across workloads. If not provided, a name based on the workload name and scope will be auto-generated.
type:
- string
- 'null'
minLength: 1
maxLength: 63
example: my-claim
pattern: .*
readOnly:
description: Permit only read access to PVC.
type:
- boolean
- 'null'
default: false
ephemeral:
description: Use `true` to set PVC to ephemeral. If set to `true`, the PVC will be deleted when the workload is stopped. Not supported for inference workloads.
type:
- boolean
- 'null'
default: false
example: false
claimInfo:
$ref: '#/components/schemas/ClaimInfo'
dataSharing:
description: use `true` to share the PVC data to all projects under the selected scope.
type:
- boolean
- 'null'
default: false
example: false
type:
- object
- 'null'
HostPathMountPropagation:
description: 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 or any of its subdirectories. In case of multiple hostPath entries, this field should have the same value for all of them.
type:
- string
- 'null'
enum:
- None
- HostToContainer
WorkloadSupportedTypes:
properties:
inference:
description: Is inference a supported workload type.
type:
- boolean
- 'null'
workspace:
description: Is workspace a supported workload type.
type:
- boolean
- 'null'
training:
description: Is training a supported workload type.
type:
- boolean
- 'null'
distributed:
description: Is distributed a supported workload type.
type:
- boolean
- 'null'
distFramework:
description: The distributed training framework used in the workload.
type:
- string
- 'null'
enum:
- MPI
- PyTorch
- TF
- XGBoost
type:
- object
- 'null'
AssetDescription:
description: The description of the asset.
type:
- string
- 'null'
minLength: 1
maxLength: 250
example: description of my asset.
AssetMeta:
allOf:
- $ref: '#/components/schemas/AssetUpdatableFields'
- $ref: '#/components/schemas/AssetCreationFields'
- $ref: '#/components/schemas/AssetReadOnlyFields'
example:
name: my-asset
scope: tenant
id: a418ed33-9399-48c0-a890-122cadd13bfd
kind: s3
createdBy: test@run.ai
createdAt: '2023-02-23T14:25:36.707685Z'
updatedBy: test@run.ai
updatedAt: '2023-02-23T14:25:36.707685Z'
workloadSupportedTypes:
workspace: false
training: false
distributed: true
distFramework: TF
ClusterInfo1:
description: Cluster related information of the asset.
properties:
resources:
type: array
items:
$ref: '#/components/schemas/ClusterResourceInfo'
type:
- object
- 'null'
PVCAssetSpec:
allOf:
- $ref: '#/components/schemas/Pvc'
HostPath:
properties:
path:
description: Local path within the controller to which the host volume will be mapped. (mandatory)
type:
- string
- 'null'
minLength: 1
example: /container/directory
pattern: .*
readOnly:
description: Force the volume to be mounted with read-only permissions. Defaults to false.
type:
- boolean
- 'null'
default: true
mountPath:
description: The path that the host volume will be mounted to when in use. (mandatory)
type:
- string
- 'null'
minLength: 1
example: /local/directory
pattern: .*
mountPropagation:
$ref: '#/components/schemas/HostPathMountPropagation'
type:
- object
- 'null'
WorkloadName:
description: The name of the workload.
type: string
minLength: 1
example: my-workload-name
pattern: .*
AssetCreationFields:
type: object
required:
- scope
properties:
scope:
$ref: '#/components/schemas/Scope'
clusterId:
$ref: '#/components/schemas/ClusterIdOptional'
departmentId:
description: The id of the department. Must be specified for department scoped assets.
type:
- string
- 'null'
minLength: 1
projectId:
description: The id of the project. Must be specified for project scoped assets.
type:
- integer
- 'null'
format: int32
autoDelete:
description: The asset will be deleted automatically. This is intended for internal use.
type:
- boolean
- 'null'
default: false
workloadSupportedTypes:
$ref: '#/components/schemas/WorkloadSupportedTypes'
private:
description: The asset will be private to the user who created it. supported only for docker registry and
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/runai/refs/heads/main/openapi/runai-datasources-api-openapi.yml