NVIDIA Run:ai Datavolumes API

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 Datavolumes 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: Datavolumes
paths:
  /api/v1/datavolumes:
    get:
      summary: List datavolumes in permitted scopes
      description: Get requested datavolumes.
      operationId: get_datavolumes
      tags:
      - Datavolumes
      parameters:
      - $ref: '#/components/parameters/DatavolumesRequestType'
      - $ref: '#/components/parameters/DatavolumesUsableInProjectId'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/DatavolumesSortBy'
      - $ref: '#/components/parameters/SortOrder'
      - $ref: '#/components/parameters/DatavolumesFilter'
      - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: Executed successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                - datavolumes
                properties:
                  next:
                    type: integer
                    example: 1
                  datavolumes:
                    $ref: '#/components/schemas/DatavolumesNoSharedScopes'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
    post:
      summary: Create a datavolume
      operationId: create_datavolume
      tags:
      - Datavolumes
      requestBody:
        description: The datavolume to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatavolumeCreationFields'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Datavolume'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
  /api/v1/datavolumes/{datavolumeId}:
    get:
      summary: Get datavolume
      operationId: get_datavolume
      tags:
      - Datavolumes
      parameters:
      - $ref: '#/components/parameters/DatavolumeId'
      responses:
        '200':
          description: Executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Datavolume'
        '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 datavolume
      operationId: delete_datavolume
      tags:
      - Datavolumes
      parameters:
      - $ref: '#/components/parameters/DatavolumeId'
      responses:
        '202':
          $ref: '#/components/responses/202Accepted'
        '204':
          $ref: '#/components/responses/204NoContent'
        '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 datavolume
      operationId: patch_datavolume
      tags:
      - Datavolumes
      parameters:
      - $ref: '#/components/parameters/DatavolumeId'
      requestBody:
        description: Datavolume to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatavolumePatchFields'
      responses:
        '200':
          description: Executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatavolumeNoSharedScopes'
        '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/datavolumes/name-availability:
    get:
      summary: Data volumes name availability.
      description: Checks if a specified data volume name is available under the given scope (e.g., project or department). Returns a 204 No Content response if the name is available, or 409 Conflict if the name is already in use.
      operationId: datavolume_name_availability
      tags:
      - Datavolumes
      parameters:
      - $ref: '#/components/parameters/DataVolumeName'
      - $ref: '#/components/parameters/ClusterIdRequired'
      responses:
        '204':
          description: The name is available to use
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '409':
          $ref: '#/components/responses/409Conflict'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
  /api/v1/datavolumes/count:
    get:
      summary: Count data volumes.
      description: Retrieve the number of data volumes.
      operationId: count_datavolumes
      tags:
      - Datavolumes
      parameters:
      - $ref: '#/components/parameters/DatavolumesRequestType'
      - $ref: '#/components/parameters/DatavolumesUsableInProjectId'
      - $ref: '#/components/parameters/DatavolumesFilter'
      - $ref: '#/components/parameters/Search'
      responses:
        '200':
          description: Executed successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                properties:
                  count:
                    type: integer
                    format: int64
                    example: 1
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
  /api/v1/datavolumes/{datavolumeId}/sharedScopes:
    patch:
      summary: Patch the datavolume's shared scopes
      operationId: patch_datavolume_shared_scopes
      tags:
      - Datavolumes
      parameters:
      - $ref: '#/components/parameters/DatavolumeId'
      requestBody:
        description: Requested SharedScopes of the datavolume to patch.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SharedScopesPatchRequest'
      responses:
        '200':
          description: Executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedScopes'
        '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'
    get:
      summary: Get the datavolume's shared scopes
      operationId: get_datavolume_shared_scopes
      tags:
      - Datavolumes
      parameters:
      - $ref: '#/components/parameters/DatavolumeId'
      responses:
        '200':
          description: Executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedScopes'
        '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:
  parameters:
    DatavolumesFilter:
      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|projectId|clusterId|departmentId|projectName|createdAt|createdBy|phase)(==|!=|<=|>=|=@|!@|=\^|=\$).+$
        example:
        - name!=some-datavolume-name
      explode: false
    DatavolumeId:
      name: datavolumeId
      in: path
      required: true
      description: The id of the datavolume to retrieve
      example: 71f69d83-ba66-4822-adf5-55ce55efd210
      schema:
        type: string
        format: uuid
    Search:
      name: search
      in: query
      required: false
      description: Filter results by a free text search.
      schema:
        type: string
        example: test project
    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
    DatavolumesRequestType:
      name: requestType
      in: query
      required: true
      description: Which datavolumes would be returned in the response. Originated - datavolumes that are originated in the permitted scopes of the caller. UsableInProject - datavolumes that can be used in a specific project; if you use this value, you must also provide the project ID in the "usableInProjectId" query param.
      schema:
        $ref: '#/components/schemas/DatavolumeRequestType'
    SortOrder:
      name: sortOrder
      in: query
      required: false
      description: Sort results in descending or ascending order.
      schema:
        type: string
        enum:
        - asc
        - desc
        default: asc
    DatavolumesUsableInProjectId:
      name: usableInProjectId
      in: query
      required: false
      description: Only when using "UsableInProject" requestType; Filter results for only datavolumes that are shared with - or originated in - the project.
      schema:
        type: string
        example: '5'
    DataVolumeName:
      name: dataName
      in: query
      required: true
      description: the name of the datavolume
      schema:
        type: string
        minLength: 1
    ClusterIdRequired:
      name: clusterId
      in: query
      description: The id of the cluster
      required: true
      schema:
        type: string
        format: uuid
        example: d73a738f-fab3-430a-8fa3-5241493d7128
    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
    DatavolumesSortBy:
      name: sortBy
      in: query
      required: false
      description: Sort results by a parameters.
      schema:
        type: string
        enum:
        - name
        - projectId
        - clusterId
        - departmentId
        - projectName
        - createdAt
        - createdBy
        - phase
  schemas:
    HttpResponse:
      required:
      - code
      - message
      properties:
        code:
          type: integer
          minimum: 100
          maximum: 599
        message:
          type: string
    DatavolumeRequestType:
      type: string
      description: Which datavolumes to return in the GET datavolumes response. Originated - datavolumes that are originated in the permitted scopes of the caller. UsableInProject - datavolumes that can be used in a specific project; if you use this value, you must also provide the project ID in the "usableInProjectId" query param.
      example: Originated
      enum:
      - Originated
      - UsableInProject
    DatavolumeNoSharedScopes:
      allOf:
      - $ref: '#/components/schemas/DatavolumeInnerFields'
      - type: object
        required:
        - status
        properties:
          status:
            $ref: '#/components/schemas/DatavolumeStatus'
    SharedScopesPatchRequest:
      type: object
      properties:
        add:
          type: array
          items:
            $ref: '#/components/schemas/SharedScopeBase'
          maxLength: 50
        remove:
          type: array
          items:
            $ref: '#/components/schemas/SharedScopeBase'
          maxLength: 50
    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
    EnrichmentDataFields1:
      type: object
      required:
      - projectName
      properties:
        projectName:
          type: string
          example: project-a
        departmentId:
          type: string
          example: department-a
        clusterId:
          $ref: '#/components/schemas/ClusterId'
    DatavolumePatchFields:
      type: object
      properties:
        description:
          type: string
          maxLength: 127
          example: Results of experiment X
    Conditions1:
      type: array
      items:
        $ref: '#/components/schemas/Condition2'
      x-schema-name: Conditions
    DatavolumesNoSharedScopes:
      type: array
      items:
        $ref: '#/components/schemas/DatavolumeNoSharedScopes'
      x-schema-name: DatavolumesNoSharedScopes
    Condition2:
      type: object
      required:
      - type
      - status
      properties:
        type:
          description: The type of the condition, such as Failed or Available. See Types of domain status conditions.
          type: string
          example: PvcsCreated
        status:
          type: string
          description: The status of the condition, such as True, False or Unknown.
          example: 'False'
        message:
          type: string
          description: An optional, human-readable message providing more details about the condition.
          example: Failed to create pvc in namespace 'runai-proj1'
        reason:
          type: string
          description: The reason for the Failed condition. Not applicable to other types of condition.
          example: ErrorCreatingPvc
        lastTransitionTime:
          description: A timestamp of when the condition was created or the last time time the condition transitioned from one status to another.
          type: string
          nullable: true
          format: date-time
          example: '2022-01-01T03:49:52.531Z'
    SharedScope:
      allOf:
      - $ref: '#/components/schemas/SharedScopeBase'
      - type: object
        required:
        - scopeName
        properties:
          scopeName:
            type: string
            description: The name of the scope
            example: project-a
          createdAt:
            type: string
            format: date-time
          createdBy:
            type: string
            example: user@run.ai
    ClusterId:
      description: The id of the cluster.
      type: string
      format: uuid
      example: 71f69d83-ba66-4822-adf5-55ce55efd210
    SharedScopes:
      type: array
      items:
        $ref: '#/components/schemas/SharedScope'
      x-schema-name: SharedScopes
    DatavolumeCreationFields:
      type: object
      required:
      - name
      - projectId
      - originPvcName
      properties:
        name:
          type: string
          maxLength: 63
          pattern: ^[a-z][-a-z0-9]{0,62}$
          example: datavolume-a
          description: The name of the new data volume.
        description:
          type: string
          maxLength: 127
          description: A brief description of the data volume and its purpose.
          example: Results of experiment X
        originPvcName:
          description: The name of the existing PVC that the new data volume is based on.
          type: string
          example: pvc-a
        projectId:
          description: The ID of the project whose namespace contains the origin PVC.
          type: string
          example: '5'
        shouldDeleteOriginalVolume:
          description: True is not supported. This parameter will be removed in a future release.
          type: boolean
          default: false
          example: false
        useOriginalVolume:
          description: If true, the original storage volume will be used together with the data volume. Default true as long as "shouldDeleteOriginalVolume" is false.
          type: boolean
          default: true
          example: true
          nullable: true
    DatavolumePhase:
      type: string
      description: Phase of the Datavolume in the cluster
      example: Ready
      enum:
      - Ready
      - NotReady
      - Creating
      - Deleting
      - Unknown
    DatavolumeStatus:
      type: object
      required:
      - phase
      properties:
        phase:
          $ref: '#/components/schemas/DatavolumePhase'
        phaseMessage:
          type: string
          description: Message explaining the phase of the Datavolume in the cluster
          example: Failed to copy pvc to project 'project-a'
        conditions:
          $ref: '#/components/schemas/Conditions1'
        datavolumePvcName:
          type: string
          description: The name of the copied PVC that is created in the cluster in the project namespace
          example: datavolume-pvc-1
        datavolumePvName:
          type: string
          description: The name of the PV that is created in the cluster - copied from the one that was attached to the original pvc
          example: datavolume-pv-1
    SharedScopeBase:
      type: object
      required:
      - scopeType
      - scopeId
      properties:
        scopeType:
          $ref: '#/components/schemas/ScopeType2'
        scopeId:
          type: string
          example: a418ed33-9399-48c0-a890-122cadd13bfd
    BaseFields:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          example: 71f69d83-ba66-4822-adf5-55ce55efd210
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        createdBy:
          type: string
          example: user@run.ai
        updatedBy:
          type: string
          example: user@run.ai
    ScopeType2:
      type: string
      enum:
      - cluster
      - department
      - project
    DatavolumeInnerFields:
      allOf:
      - $ref: '#/components/schemas/BaseFields'
      - $ref: '#/components/schemas/DatavolumeCreationFields'
      - $ref: '#/components/schemas/EnrichmentDataFields1'
    Datavolume:
      allOf:
      - $ref: '#/components/schemas/DatavolumeInnerFields'
      - type: object
        required:
        - status
        properties:
          sharedScopes:
            description: Will be returned only if the user has the required permissions to view those scopes
            type: array
            items:
              $ref: '#/components/schemas/SharedScope'
          status:
            $ref: '#/components/schemas/DatavolumeStatus'
  responses:
    202Accepted:
      description: Accepted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpResponse'
          example:
            code: 202
            message: Request has been accepted.
    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.
    204NoContent:
      description: No Content.
    503ServiceUnavailable:
      description: unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 503
            message: Please try again in few minutes.
    409Conflict:
      description: The specified resource already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 409
            message: Resource with this name already exists
    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