DataCrunch Object Storage API

openapi: 3.2.0
info:
  title: Verda Cloud Public Object Storage API
  description: '# Introduction


    Verda Cloud API allows you to deploy, control instances & more via external code. ## Open API schema


    Download OpenAPI 3.1.0 schema here: /v1/openapi.json


    The API is a RESTful API over HTTPS, all requests & responses use JSON as the data exchange format. ## Official SDKs


    The following SDK packages maintained by Verda Cloud and use this API:


    - **Python SDK**: https://github.com/verda-cloud/sdk-python

    - **Go SDK**: https://github.com/verda-cloud/verdacloud-sdk-go

    - **Terraform** and **OpenTofu** provider: https://github.com/verda-cloud/terraform-provider-verda


    # Quick Start Guide


    We use OAuth 2.0 Client Credentials authentication scheme. You can generate credentials via the console UI https://console.verda.com for external applications to use Verda API. The credentials are used to generate Access & Refresh tokens. All requests to this API must be authenticated using the Access token, except for a few open endpoints. Access tokens have a short lifespan, and can be regenerated using the Refresh token. ## 1. Get Credentials from the Verda Cloud Dashboard


    Go to the Project page => **Keys** => **Cloud API Credentials** section and click on **Create**. These credentials will be used like a username & password for your application. Store the client secret safely - like a password. ## 2. Generate Access Token


    An Access Token is needed to be sent with any API call for authentication. The Access Token has a limited lifetime and is expired after a while as defined in `expires_in`. It is used as a bearer token


    ### To get an access token, call the token endpoint with the credentials obtained in step 1:


    ```json http

    {

    "method": "post",

    "url": "https://api.verda.com/v1/oauth2/token",

    "headers": {

    "Content-Type": "application/json"

    },

    "body": {

    "grant_type": "client_credentials",

    "client_id": "",

    "client_secret": ""

    }

    }

    ```


    A valid response would look similar to this:


    ```json

    {

    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoZXkiOiJ5b3UgYWN1YWxseSBjaGVja2VkIHRoaXM_In0.0RjcdKQ1NJP9gbRyXITE6LFFLwKGzeeshuubnkkfkb8",

    "token_type": "Bearer",

    "expires_in": 3600,

    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3b3ciOiJhbmQgdGhpcyB0b28_In0.AC5gk-o-MOptUgrouEErlhr8WT3Hg_RR6px6A0I7ZEk",

    "scope": "cloud-api-v1"

    }

    ```


    `access_token` is the token value, to be used in the next step. `expires_in` is the duration in seconds until the token is expired. `refresh_token` can be used to create a new access token if expired. When an Access Token expires, create a new one using the refresh token:


    ```json http

    {

    "method": "post",

    "url": "https://api.verda.com/v1/oauth2/token",

    "headers": {

    "Content-Type": "application/json"

    },

    "body": {

    "grant_type": "refresh_token",

    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3b3ciOiJhbmQgdGhpcyB0b28_In0.AC5gk-o-MOptUgrouEErlhr8WT3Hg_RR6px6A0I7ZEk"

    }

    }

    ```


    The response will include a new token. ## 3. Make REST API Calls


    That''s it, you are ready to use the API, don''t forget to add the Access Token to your calls:


    Let''s call the `/balance` endpoint. Add the Access Token value to the `Authorization` header, preceded by the "Bearer" string and a space:


    ```json http

    {

    "method": "get",

    "url": "https://api.verda.com/v1/balance",

    "headers": {

    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoZXkiOiJ5b3UgYWN1YWxseSBjaGVja2VkIHRoaXM_In0.0RjcdKQ1NJP9gbRyXITE6LFFLwKGzeeshuubnkkfkb8"

    }

    }

    ```


    # Rate Limits


    Authenticated public API requests are rate limited per project in 60 second windows. ## Limits enforced


    - **Project limit**: 500 requests per minute for all authenticated API requests made for the same project

    - **Endpoint limit**: 60 requests per minute for the same project, HTTP method, and request path combination


    The endpoint limit key includes the full request path. Route-specific endpoint policies override the regular endpoint limit for the matching request path.'
  version: v1
  contact:
    name: Verda Cloud Oy
    url: https://verda.com
    email: info@verda.com
servers:
- url: https://api.verda.com
security:
- bearer: []
tags:
- name: Object Storage
  description: 'S3-compatible object storage. Manage access keys, and buckets. Read more about our object storage support here.


    **Beta:** Object Storage API is under active development and may change without notice.'
paths:
  /v1/object-storage/access-keys:
    get:
      description: Returns all S3-compatible access key pairs for the project.
      operationId: ObjectStorageController_getAccessKeys
      parameters: []
      responses:
        '200':
          description: List of access keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccessKeyPublicResponseDto'
      security:
      - bearer: []
      summary: List access keys
      tags:
      - Object Storage
    post:
      description: Create a new S3-compatible access key pair.
      operationId: ObjectStorageController_createAccessKey
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccessKeyPublicDto'
      responses:
        '201':
          description: Newly created access key pair
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAccessKeyPublicResponseDto'
      security:
      - bearer: []
      summary: Create access key
      tags:
      - Object Storage
  /v1/object-storage/access-keys/{access_key_id}:
    delete:
      description: Permanently delete an access key pair. Any applications using this key will lose access.
      operationId: ObjectStorageController_deleteAccessKey
      parameters:
      - name: access_key_id
        required: true
        in: path
        schema:
          example: 57c99674-9839-4a17-a53e-9202d83b0d9a
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Delete access key
      tags:
      - Object Storage
  /v1/object-storage/buckets:
    get:
      description: Returns all buckets for the project.
      operationId: ObjectStorageController_listBuckets
      parameters: []
      responses:
        '200':
          description: List of buckets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetBucketResponseDto'
      security:
      - bearer: []
      summary: List buckets
      tags:
      - Object Storage
    post:
      description: Create a new S3-compatible bucket. Bucket names are globally unique and must follow S3 naming rules.
      operationId: ObjectStorageController_createBucket
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BucketNameRequestDto'
      responses:
        '201':
          description: Newly created bucket
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBucketResponseDto'
      security:
      - bearer: []
      summary: Create bucket
      tags:
      - Object Storage
  /v1/object-storage/buckets/check-availability/{bucket_name}:
    get:
      description: Check whether a bucket name is available for use.
      operationId: ObjectStorageController_checkBucketNameAvailability
      parameters:
      - name: bucket_name
        required: true
        in: path
        description: Globally unique bucket name (S3 naming rules apply)
        schema:
          example: my-app-uploads
          type: string
      responses:
        '200':
          description: Bucket name availability status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketNameAvailabilityResponseDto'
      security:
      - bearer: []
      summary: Check bucket name availability
      tags:
      - Object Storage
  /v1/object-storage/buckets/{bucket_name}:
    get:
      description: Returns details for a specific bucket including usage statistics.
      operationId: ObjectStorageController_getBucket
      parameters:
      - name: bucket_name
        required: true
        in: path
        description: Globally unique bucket name (S3 naming rules apply)
        schema:
          example: my-app-uploads
          type: string
      responses:
        '200':
          description: Bucket details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBucketResponseDto'
      security:
      - bearer: []
      summary: Get bucket details
      tags:
      - Object Storage
    delete:
      description: Delete an empty bucket. The bucket must have no objects before it can be deleted.
      operationId: ObjectStorageController_deleteBucket
      parameters:
      - name: bucket_name
        required: true
        in: path
        description: Globally unique bucket name (S3 naming rules apply)
        schema:
          example: my-app-uploads
          type: string
      responses:
        '200':
          description: ''
      security:
      - bearer: []
      summary: Delete bucket
      tags:
      - Object Storage
  /v1/object-storage/locations:
    get:
      description: Returns a list of locations that support object storage.
      operationId: ObjectStorageController_getLocations
      parameters: []
      responses:
        '200':
          description: List of locations
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
      security:
      - bearer: []
      summary: Get locations that support object storage
      tags:
      - Object Storage
components:
  schemas:
    AccessKeyPublicResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the access key pair
          example: 7dfc2631-0158-4f74-93f6-6b46dcb90fef
        name:
          type: string
          description: Name of the access key pair
          example: my-key
        access_key:
          type: string
          description: S3-compatible access key
          example: REDACTED_AWS_ACCESS_KEY_ID
        created_at:
          format: date-time
          type: string
          description: When the access key was created
          example: '2024-01-15T14:10:27.114Z'
      required:
      - id
      - name
      - access_key
      - created_at
    BucketNameRequestDto:
      type: object
      properties:
        bucket_name:
          type: string
          description: Globally unique bucket name (S3 naming rules apply)
          example: my-app-uploads
        location_code:
          type: string
          description: Location code
          example: FIN-03
      required:
      - bucket_name
      - location_code
    GetBucketResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the bucket
          example: 7dfc2631-0158-4f74-93f6-6b46dcb90fef
        name:
          type: string
          description: Globally unique bucket name
          example: my-app-uploads
        object_count:
          type: number
          description: Number of objects stored in the bucket
          example: 42
        size_gb:
          type: number
          description: Total size of all objects in GB
          example: 1
        created_at:
          format: date-time
          type: string
          description: When the bucket was created
          example: '2024-01-15T14:10:27.114Z'
      required:
      - id
      - name
      - created_at
    CreateAccessKeyPublicResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the access key pair
          example: 7dfc2631-0158-4f74-93f6-6b46dcb90fef
        name:
          type: string
          description: Name of the access key pair
          example: my-key
        access_key:
          type: string
          description: S3-compatible access key
          example: REDACTED_AWS_ACCESS_KEY_ID
        secret_key:
          type: string
          description: S3-compatible secret key
          example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
        created_at:
          format: date-time
          type: string
          description: When the access key was created
          example: '2024-01-15T14:10:27.114Z'
      required:
      - id
      - name
      - access_key
      - secret_key
      - created_at
    BucketNameAvailabilityResponseDto:
      type: object
      properties:
        is_available:
          type: boolean
          description: Whether the bucket name is available for use
          example: true
      required:
      - is_available
    CreateAccessKeyPublicDto:
      type: object
      properties:
        name:
          type: string
          description: Name of the access key pair
          example: my-key
      required:
      - name
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: '[Generate the token here](#tag/authentication/POST/v1/oauth2/token). Bearer token to authenticate requests to the public API. You can generate a token by calling the `/v1/oauth2/token` endpoint.'
x-provenance:
  method: harvested
  publisher: DataCrunch
  source: https://api.datacrunch.io/v1/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)