openapi: 3.0.1
info:
  title: DataCrunch Public Balance Volumes API
  description: Public REST API for DataCrunch, a European GPU cloud. The API lets you deploy and manage GPU/CPU instances, query instance types and real-time availability, manage OS images and startup scripts, SSH keys, block storage volumes, retrieve account balance, and deploy and operate serverless container deployments for inference. Authentication uses the OAuth 2.0 Client Credentials flow to obtain a short-lived Bearer access token.
  termsOfService: https://datacrunch.io/legal/terms-of-service
  contact:
    name: DataCrunch Support
    url: https://docs.datacrunch.io/
  version: '1.0'
servers:
- url: https://api.datacrunch.io/v1
security:
- bearerAuth: []
tags:
- name: Volumes
paths:
  /volumes:
    get:
      operationId: listVolumes
      tags:
      - Volumes
      summary: List volumes
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A list of volumes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Volume'
    post:
      operationId: createVolume
      tags:
      - Volumes
      summary: Create a volume
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVolumeRequest'
      responses:
        '201':
          description: Volume created; returns its id.
          content:
            application/json:
              schema:
                type: string
    put:
      operationId: volumeAction
      tags:
      - Volumes
      summary: Perform a volume action
      description: Run an action against one or more volumes (attach, detach, delete, resize, clone, rename).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VolumeActionRequest'
      responses:
        '202':
          description: Action accepted.
  /volumes/{volume_id}:
    get:
      operationId: getVolume
      tags:
      - Volumes
      summary: Get a volume by id
      parameters:
      - name: volume_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Volume details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteVolume
      tags:
      - Volumes
      summary: Delete a volume
      parameters:
      - name: volume_id
        in: path
        required: true
        schema:
          type: string
      - name: is_permanent
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Volume deleted.
  /volumes/trash:
    get:
      operationId: listTrashedVolumes
      tags:
      - Volumes
      summary: List soft-deleted volumes
      responses:
        '200':
          description: A list of volumes in trash.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Volume'
  /volume-types:
    get:
      operationId: listVolumeTypes
      tags:
      - Volumes
      summary: List volume types
      responses:
        '200':
          description: A list of volume types.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
components:
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CreateVolumeRequest:
      type: object
      required:
      - type
      - name
      - size
      properties:
        type:
          type: string
          example: NVMe
        name:
          type: string
        size:
          type: integer
          description: Size in GB.
        instance_id:
          type: string
          description: Optional instance to attach to on creation.
        location_code:
          type: string
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    VolumeActionRequest:
      type: object
      required:
      - id
      - action
      properties:
        id:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        action:
          type: string
          enum:
          - attach
          - detach
          - delete
          - rename
          - resize
          - clone
        instance_id:
          type: string
        name:
          type: string
        size:
          type: integer
        is_permanent:
          type: boolean
    Volume:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          example: NVMe
        size:
          type: integer
          description: Size in GB.
        status:
          type: string
        is_os_volume:
          type: boolean
        target:
          type: string
        location_code:
          type: string
        instance_id:
          type: string
        created_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer access token obtained from POST /oauth2/token via the OAuth 2.0 Client Credentials grant.