The storage class configuration API enables administrators to define, manage, and customize how storage classes are used across the NVIDIA Run:ai platform. Through this API, you can configure access modes, volume modes, and claim size restrictions for persistent volume claims (PVCs). These settings help standardize storage behavior, enforce organization-wide policies, and ensure consistent resource allocation across workloads.
openapi: 3.0.3
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 Storage Class Configuration 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: Storage Class Configuration
description: 'The storage class configuration API enables administrators to define, manage, and customize how storage classes are used across the NVIDIA Run:ai platform. Through this API, you can configure access modes, volume modes, and claim size restrictions for persistent volume claims (PVCs). These settings help standardize storage behavior, enforce organization-wide policies, and ensure consistent resource allocation across workloads.
'
paths:
/api/v1/storage-class-configuration:
get:
summary: List storage class configurations
description: Retrieves a list of storage class configurations defined in the system.
operationId: list_storage_class_configuration
tags:
- Storage Class Configuration
x-csp: true
parameters:
- $ref: '#/components/parameters/StorageClassConfigurationFilterBy'
- $ref: '#/components/parameters/StorageClassConfigurationSortBy'
- $ref: '#/components/parameters/SortOrder'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Executed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/StorageClassConfigurationListResponse'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'500':
$ref: '#/components/responses/500InternalServerError'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
post:
summary: Create storage class configuration
description: 'Creates a new storage class configuration in the NVIDIA Run:ai platform.
This endpoint enables administrators to define storage class behavior and customize their usage settings.
'
operationId: create_storage_class_configuration
tags:
- Storage Class Configuration
x-csp: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StorageClassConfigurationCreationRequest'
responses:
'201':
description: Executed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/StorageClassConfiguration'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'500':
$ref: '#/components/responses/500InternalServerError'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
/api/v1/storage-class-configuration/{id}:
get:
summary: Get storage class configuration by id
description: 'Retrieves a specific storage class configuration by its unique identifier. Use this endpoint to view detailed information about the configuration, including its permissions and customization options.
'
operationId: get_storage_class_configuration_by_id
x-csp: true
tags:
- Storage Class Configuration
parameters:
- $ref: '#/components/parameters/StorageClassConfigurationId'
- name: tenantId
in: query
required: false
schema:
type: integer
responses:
'200':
description: Storage class configuration
content:
application/json:
schema:
$ref: '#/components/schemas/StorageClassConfiguration'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'500':
$ref: '#/components/responses/500InternalServerError'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
patch:
summary: Patch storage class configuration by id
description: Partially updates an existing storage class configuration by its unique identifier. Use this endpoint to modify specific fields, such as permissions, customization values, or attributes, without replacing the entire configuration.
operationId: patch_storage_class_configuration_by_id
x-csp: true
tags:
- Storage Class Configuration
parameters:
- $ref: '#/components/parameters/StorageClassConfigurationId'
- name: tenantId
in: query
required: false
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StorageClassConfigurationPatchRequest'
responses:
'200':
description: Storage class configuration
content:
application/json:
schema:
$ref: '#/components/schemas/StorageClassConfiguration'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'500':
$ref: '#/components/responses/500InternalServerError'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
put:
summary: Update storage class configuration by id
description: Updates an existing storage class configuration by its unique identifier. Use this endpoint to fully replace an existing configuration, including permissions and customization settings.
operationId: update_storage_class_configuration_by_id
x-csp: true
tags:
- Storage Class Configuration
parameters:
- $ref: '#/components/parameters/StorageClassConfigurationId'
- name: tenantId
in: query
required: false
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StorageClassConfigurationUpdateRequest'
responses:
'200':
description: Storage class configuration
content:
application/json:
schema:
$ref: '#/components/schemas/StorageClassConfiguration'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'500':
$ref: '#/components/responses/500InternalServerError'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
delete:
summary: Delete storage class configuration by id
description: Deletes a specific storage class configuration by its unique identifier. Use this endpoint to permanently remove configurations that are no longer needed.
operationId: delete_storage_class_configuration_by_id
x-csp: true
tags:
- Storage Class Configuration
parameters:
- $ref: '#/components/parameters/StorageClassConfigurationId'
- name: tenantId
in: query
required: false
schema:
type: integer
responses:
'204':
description: Storage class configuration deleted
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'404':
$ref: '#/components/responses/404NotFound'
'500':
$ref: '#/components/responses/500InternalServerError'
'503':
$ref: '#/components/responses/503ServiceUnavailable'
components:
schemas:
AttributesCustomization:
description: Defines additional annotation attributes to be applied to PVCs created under this storage class. Each attribute describes an annotation key and its expected value format, display name, and purpose.
type: array
items:
$ref: '#/components/schemas/PvcAddedAttribute'
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
AllowedForEphemeralVolumes:
type: boolean
nullable: true
description: Allows workloads to create ephemeral volumes using this storage class. When disabled, users cannot (a) create PVC assets with autoDelete=true and ephemeral=true, or (b) include PVC instances with isEphemeral=false that use this storage class.
StorageClassConfigurationListResponse:
type: object
required:
- storageClassConfigurations
properties:
storageClassConfigurations:
description: A list of storage class configuration objects. Each object defines the configuration details for a specific storage class.
type: array
items:
$ref: '#/components/schemas/StorageClassConfiguration'
next:
type: integer
example: 1
StorageClassCustomization:
description: Optional UI/policy controls that define defaults and requirements when creating PVCs with this storage class.
properties:
accessMode:
$ref: '#/components/schemas/AccessModeCustomization'
volumeMode:
$ref: '#/components/schemas/VolumeModeCustomization'
claimSize:
$ref: '#/components/schemas/ClaimSizeCustomization'
attributes:
$ref: '#/components/schemas/AttributesCustomization'
type: object
nullable: true
AccessModeCustomization:
description: Controls whether PVC access modes are required and what defaults to apply.
properties:
required:
type: boolean
description: If true, the accessMode field is mandatory when creating a PVC that uses this storage class.
nullable: true
default:
$ref: '#/components/schemas/PvcAccessModes'
supportedValues:
$ref: '#/components/schemas/PvcSupportedAccessModes'
type: object
nullable: true
StorageClassName:
description: The name of the storage class to which the configuration applies.
type: string
example: Standard
AllowDataSharing:
type: boolean
nullable: true
description: Allows creation of PVCs using a shared volume.
ClaimSizeCustomization:
description: Defines the default, supported units, and range constraints for PVC claim sizes. These settings control the requested storage capacity when creating a PVC using this storage class.
properties:
default:
$ref: '#/components/schemas/PvcClaimSize'
supportedUnits:
description: 'Units supported for specifying PVC sizes. Valid values: "MB", "MiB", "GB", "GiB", "TB", "TiB".'
type: array
items:
type: string
enum:
- MB
- MiB
- GB
- GiB
- TB
- TiB
min:
$ref: '#/components/schemas/PvcClaimMinSize'
max:
$ref: '#/components/schemas/PvcClaimMaxSize'
step:
$ref: '#/components/schemas/PvcClaimStepSize'
type: object
nullable: true
PvcClaimSize:
description: 'Requested size for the PVC. Mandatory when existingPvc is false. Recommended sizes: TB/GB/MB/TIB/GIB/MIB'
type: string
pattern: ^([+]?[0-9.]+)([eEinumkKMGTP]*[-+]?[0-9]*)$
example: 1G
nullable: true
TenantId:
description: The id of the tenant.
type: integer
format: int32
example: 1001
PvcAddedAttributeFormat:
type: string
description: 'Defines the data type the attribute can accept. Enum: "text" "number" "boolean"'
enum:
- text
- number
- boolean
nullable: true
AllowedForAssets:
type: boolean
nullable: true
description: Determines whether PVC assets can be created using this storage class.
PvcAddedAttribute:
description: Attribute that is added to any PVC of a given storage class.
required:
- key
properties:
key:
type: string
minLength: 1
description: 'The annotation key for the PVC. Must comply with Kubernetes naming rules: ≤63 characters, beginning and ending with an alphanumeric character ([A-Za-z0-9]), and may include dashes (-), underscores (_), or dots (.).'
maxLength: 63
pattern: ^([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]$
example: dnsname
format:
description: 'Defines the data type the attribute can accept. Enum: "text" "number" "boolean"'
$ref: '#/components/schemas/PvcAddedAttributeFormat'
display:
type: string
minLength: 1
description: User-friendly display name for the attribute, shown in the UI.
nullable: true
example: DNS Name
description:
type: string
minLength: 1
description: A description of the attribute's purpose or expected values.
nullable: true
example: The host name of the DNS
placeholder:
type: string
minLength: 1
description: Example or hint text for the attribute's value, displayed as a watermark or help message in the UI.
nullable: true
example: enter hostname or IP address
required:
description: Indicates whether this attribute is mandatory.
type: boolean
nullable: true
example: 'true'
defaultValue:
description: Default value assigned to the attribute when not explicitly provided.
type: string
minLength: 1
nullable: true
example: my.dns.com
validationRegexp:
description: Regular expression used to validate user input for text attributes.
type: string
minLength: 1
nullable: true
example: ^[a-zA-Z0-9.-_]+$
minValue:
description: Minimum allowed value for attributes of type number.
type: number
minLength: 1
nullable: true
example: '100'
maxValue:
description: Maximum allowed value for attributes of type number.
type: number
minLength: 1
nullable: true
example: '200'
step:
description: Defines the incremental step between allowed numeric values (for example, 1, 0.1).
type: number
minLength: 1
nullable: true
example: '5'
validationError:
description: Custom validation error message shown if input fails validation. If omitted, a default error message is generated automatically.
type: string
minLength: 1
nullable: true
example: Invalid URL
nullable: true
type: object
PvcClaimMinSize:
description: 'Minimum claim size allowed for PVCs created with this storage class. Mandatory when existingPvc = false. Recommended values: TB, GB, MB, TIB, GIB, MIB.'
type: string
pattern: ^([+]?[0-9.]+)([eEinumkKMGTP]*[-+]?[0-9]*)$
example: 1G
nullable: true
ScopeClusterId:
description: The ID of the cluster.
type: string
format: uuid
PvcClaimMaxSize:
description: 'Maximum claim size allowed for PVCs created with this storage class. Mandatory when existingPvc = false. Recommended values: TB, GB, MB, TIB, GIB, MIB.'
type: string
pattern: ^([+]?[0-9.]+)([eEinumkKMGTP]*[-+]?[0-9]*)$
example: 1G
nullable: true
AllowedForWorkloads:
type: boolean
nullable: true
description: Allows workloads to include PVCs that use this storage class. When disabled, users cannot (a) include non-existing PVC assets created with this class in asset-based submissions, or (b) attach PVCs with existing=false to workloads using this class.
PvcSupportedAccessModes:
description: Defines the access modes supported by the given storage class. These values indicate which access configurations can be used when creating PVCs with this class.
properties:
readWriteOnce:
description: Indicates whether the readWriteOnce access mode is supported. This mode allows a volume to be mounted as read/write by a single node.
type: boolean
default: true
nullable: true
readOnlyMany:
description: Indicates whether the readOnlyMany access mode is supported. This mode allows a volume to be mounted as read-only by many nodes.
type: boolean
default: true
nullable: true
readWriteMany:
description: Indicates whether the readWriteMany access mode is supported. This mode allows a volume to be mounted as read/write by many nodes.
type: boolean
default: true
nullable: true
nullable: true
type: object
PvcVolumeMode:
description: Default volume mode for the PVC. Choose between Filesystem (default) or Block.
type: string
enum:
- Filesystem
- Block
nullable: true
AllowedForPersistentVolumes:
type: boolean
nullable: true
description: Allows workloads to create persistent volumes using this storage class. When disabled, users cannot (a) create PVC assets with autoDelete=true and ephemeral=true, or (b) include PVC instances with isEphemeral=false that use this storage class.
StorageClassConfigurationUpdateRequest:
type: object
properties:
permissions:
$ref: '#/components/schemas/StorageClassPermissions'
customization:
$ref: '#/components/schemas/StorageClassCustomization'
StorageClassConfigurationCreationRequest:
type: object
required:
- scopeType
- scopeId
- name
properties:
tenantId:
type: integer
nullable: true
allOf:
- $ref: '#/components/schemas/TenantId'
scopeType:
type: string
description: the scope type of the configuration.
enum:
- cluster
default: cluster
example: cluster
scopeId:
$ref: '#/components/schemas/ScopeClusterId'
name:
$ref: '#/components/schemas/StorageClassName'
permissions:
$ref: '#/components/schemas/StorageClassPermissions'
customization:
$ref: '#/components/schemas/StorageClassCustomization'
PvcClaimStepSize:
description: Defines the incremental step between allowed numeric values (for example, 1, 0.1).
type: string
pattern: ^([+]?[0-9.]+)([eEinumkKMGTP]*[-+]?[0-9]*)$
example: 1G
nullable: true
StorageClassPermissions:
type: object
nullable: true
description: Defines the access permissions and behavioral rules for this storage class.
properties:
allowedForAssets:
$ref: '#/components/schemas/AllowedForAssets'
allowedForWorkloads:
$ref: '#/components/schemas/AllowedForWorkloads'
allowedForEphemeralVolumes:
$ref: '#/components/schemas/AllowedForEphemeralVolumes'
allowedForPersistentVolumes:
$ref: '#/components/schemas/AllowedForPersistentVolumes'
allowDataSharing:
$ref: '#/components/schemas/AllowDataSharing'
VolumeModeCustomization:
description: Defines whether the volumeMode field is required when creating PVCs and specifies default and supported modes for the storage class.
properties:
required:
type: boolean
description: Indicates whether the volumeMode field is mandatory when creating a PVC.
nullable: true
default:
$ref: '#/components/schemas/PvcVolumeMode'
supportedValues:
description: Lists which volume modes are supported for this storage class.
type: object
nullable: true
properties:
filesystem:
type: boolean
description: Indicates whether filesystem mode is supported. Filesystem allows the volume to be mounted as a filesystem, enabling the usage of directories and files.
default: true
nullable: true
block:
type: boolean
description: Indicates whether block mode is supported. Exposes the volume as a block storage, which can be formatted or used by applications directly without a filesystem.
default: true
nullable: true
type: object
nullable: true
PvcAttributesToRemove:
description: optional list of attributes that you wish to remove
properties:
attributesToRemove:
type: array
items:
type: string
example:
- dnsname
- dnsip
type: object
nullable: true
StorageClassConfiguration:
type: object
required:
- id
- tenantId
- scopeType
- scopeId
- name
properties:
id:
description: The unique identifier of the storage class configuration.
type: string
format: uuid
tenantId:
$ref: '#/components/schemas/TenantId'
scopeType:
description: 'Currently supported value: ''cluster'', which is also the default.'
type: string
enum:
- cluster
default: cluster
example: cluster
scopeId:
$ref: '#/components/schemas/ScopeClusterId'
name:
$ref: '#/components/schemas/StorageClassName'
permissions:
$ref: '#/components/schemas/StorageClassPermissions'
customization:
$ref: '#/components/schemas/StorageClassCustomization'
StorageClassConfigurationPatchRequest:
type: object
properties:
permissions:
$ref: '#/components/schemas/StorageClassPermissions'
customization:
type: object
allOf:
- $ref: '#/components/schemas/StorageClassCustomization'
- $ref: '#/components/schemas/PvcAttributesToRemove'
nullable: true
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
default: true
nullable: true
readOnlyMany:
description: Mount the volume as read-only by many nodes.
type: boolean
default: false
nullable: true
readWriteMany:
description: Mount the volume as read/write by many nodes.
type: boolean
default: false
nullable: true
nullable: true
type: object
parameters:
StorageClassConfigurationFilterBy:
name: filterBy
in: query
required: false
description: Filter results by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal, =@ contains, !@ Does not contains, =^ Starts with and =$ Ends with. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=.
schema:
type: array
items:
type: string
pattern: ^(name|tenantId|scopeType|scopeId)(==|!=|<=|>=|=@|!@|=\^|=\$).+$
example:
- name!=some-name
explode: false
StorageClassConfigurationSortBy:
name: sortBy
in: query
required: false
description: Sort results by a parameters.
schema:
type: string
enum:
- name
- tenantId
- scopeType
- scopeId
SortOrder:
name: sortOrder
in: query
required: false
description: Sort results in descending or ascending order.
schema:
type: string
enum:
- asc
- desc
default: asc
Limit:
name: limit
in: query
required: false
description: The maximum number of entries to return.
schema:
type: integer
format: int32
default: 50
minimum: 1
maximum: 500
Offset:
name: offset
in: query
required: false
description: The offset of the first item returned in the collection.
schema:
type: integer
format: int32
example: 100
StorageClassConfigurationId:
name: id
in: path
required: true
schema:
type: string
description: unique identifier of the storage class configuration
responses:
404NotFound:
description: The specified resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 404
message: Resource id not found.
500InternalServerError:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 500
message: Something went wrong.
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.
400BadRequest:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 400
message: Required parameter is missing
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer authentication
x-tagGroups:
- name: Organizations
tags:
- Clusters
- Departments
- Reports
- NodePools
- Nodes
- Projects
- Tenant
- Logo
- Researcher Command Line Interface
- Researcher Command Line Interface Deprecated
- Administrator Command Line Interface
- Network Topologies
- name: Authentication and Authorization
tags:
- Access Keys
- Access rules
- Permissions
- Applications
- Service Accounts
- Roles
- Tokens
- Users
- User Applications
- Idps
- Me
- Settings
- Org unit
- name: Audit
tags:
- AuditLogs
- name: Datavolumes
tags:
- Datavolumes
- name: Workloads
tags:
- Events
- Pods
- Workloads
- Workloads V2
- NVIDIA NIM
- Workspaces
- Trainings
- Inferences
- Revisions
- Distributed
- Workloads batch
- Workload properties
- Workload templates
- Distributed Inferences
- name: Workload assets
tags:
- Compute
- Credentials
- Datasources
- Environment
- Storage Classes
- Storage Class Configuration
- Git
- HostPath
- NFS
- PVC
- Registry
- S3
- ConfigMap
- Secret
- Template
- name: Policies
tags:
- Policy
- name: Notifications
tags:
- Notification State
- Notification Types
- NotificationChannels
- Subscriptions
- name: AI Applications
tags:
- AI Applications