Shared Storage APIs | hosted·ai Documentation

The Hosted AI platform provides shared storage volumes that can be attached to GPUaaS instances for persistent data storage across multiple compute sessions. This guide covers the complete lifecycle of shared storage management, from creation to billing.

Key Concepts

Shared Volume: Persistent storage that can be shared across multiple GPUaaS instances
Storage Block: Predefined storage configurations that determine size and characteristics
Pool Subscription: The process of subscribing to a GPUaaS pool with attached shared volumes
Resource Policy: Controls which shared storage resources teams can access
Billing Segments: Time-based billing periods with different pricing policies

API Reference

Core Shared Volume APIs

Method	Endpoint	Purpose	Auth Required
`POST`	`/api/shared-volumes`	Create shared volume	API Key
`GET`	`/api/shared-volumes`	List shared volumes	API Key
`DELETE`	`/api/shared-volumes/{id}`	Delete shared volume	API Key
`GET`	`/api/shared-volumes/shared-storage-blocks`	Get storage options	API Key

GPUaaS Integration APIs

Method	Endpoint	Purpose	Auth Required
`GET`	`/api/gpuaas/pool/shared-volumes`	Get pool-compatible volumes	API Key
`POST`	`/api/gpuaas/pool/subscribe`	Subscribe with shared volumes	API Key
`POST`	`/api/gpuaas/calculate-pool-subscription`	Calculate costs	API Key

Billing APIs

Method	Endpoint	Purpose	Auth Required
`GET`	`/api/team-billing/shared-storage/{team_id}/{start_date}/{end_date}/{interval}/{region_id}`	Get billing data	RBAC: TeamBilling.Read

Shared Volume Management

Creating a Shared Volume

Endpoint: POST /api/shared-volumes

Request Body:

json

{
  "name": "my-shared-volume",
  "storage_block_id": "storage-block-uuid",
  "team_id": "team-uuid",
  "region_id": 123
}

Response:

json

{
  "id": 123,
  "name": "my-shared-volume",
  "storage_block_id": "storage-block-uuid",
  "team_id": "team-uuid",
  "region_id": 123,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "deleted_at": null
}

Listing Shared Volumes

Endpoint: GET /api/shared-volumes

Query Parameters:

page: Page number (default: 0)
per_page: Items per page (default: 25)
sort: Sort field (e.g., "created_at")
order: Sort order ("asc" or "desc")
filter: Filter criteria

Response:

json

{
  "data": [
    {
      "id": 123,
      "name": "my-shared-volume",
      "size_in_gb": 100,
      "region_id": "region-uuid",
      "team_id": "team-uuid",
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Deleting a Shared Volume

Endpoint: DELETE /api/shared-volumes/{id}

Response: 204 No Content

Important: Volumes attached to active GPUaaS subscriptions cannot be deleted.

Getting Storage Block Options

Endpoint: GET /api/shared-volumes/shared-storage-blocks

Query Parameters:

team_id: Team UUID (required)
region_id: Region ID as integer (required)

Response:

json

[
  {
    "id": "storage-block-uuid",
    "name": "Shared-100GB",
    "description": "100GB shared storage block",
    "size_in_gb": 100,
    "is_available": true,
    "ephemeral_usage": false,
    "shared_storage_usage": true
  },
  {
    "id": "storage-block-uuid-2",
    "name": "Shared-500GB", 
    "description": "500GB shared storage block",
    "size_in_gb": 500,
    "is_available": true,
    "ephemeral_usage": false,
    "shared_storage_usage": true
  }
]

GPUaaS Integration

Discovery Process

1. Find Compatible Shared Volumes

Endpoint: GET /api/gpuaas/pool/shared-volumes

Query Parameters:

pool_id: GPUaaS pool ID as integer (required)
team_id: Team UUID (required)

Response:

json

[
  {
    "id": 123,
    "name": "my-shared-volume",
    "storage_block_id": "storage-block-uuid",
    "team_id": "team-uuid",
    "region_id": 123,
    "created_at": "2024-01-01T00:00:00Z"
  }
]

2. Calculate Subscription Cost

Endpoint: POST /api/gpuaas/calculate-pool-subscription

Request Body:

json

{
  "pool_id": 123,
  "team_id": "team-uuid",
  "vgpus": 2,
  "vcpus": 4,
  "memory_mb": 8192,
  "instance_type_id": "instance-uuid",
  "ephemeral_storage_block_id": "storage-uuid",
  "shared_volumes": [1, 2, 3],
  "image_id": "image-uuid"
}

Response:

json

{
  "overall_subscription": {
    "total_cost": 125.50,
    "currency": "USD",
    "billing_period": "hourly"
  },
  "gpu_instances": {
    "vgpu_cost": 100.00,
    "cpu_cost": 10.00,
    "memory_cost": 5.00,
    "storage_cost": 8.50,
    "shared_volume_cost": 2.00
  }
}

Subscription Process

Endpoint: POST /api/gpuaas/pool/subscribe

Request Body:

json

{
  "pool_id": 123,
  "team_id": "team-uuid",
  "vgpus": 2,
  "vcpus": 4,
  "memory_mb": 8192,
  "instance_type_id": "instance-uuid",
  "ephemeral_storage_block_id": "storage-uuid",
  "shared_volumes": [1, 2, 3],
  "image_id": "image-uuid"
}

Response: 200 OK (subscription created)

Important Notes:

Shared volumes can only be assigned during subscription creation
No API exists to modify shared volumes on existing subscriptions
To change volumes, you must unsubscribe and re-subscribe

Billing & Analytics

Shared Storage Billing

Endpoint: GET /api/team-billing/shared-storage/{team_id}/{start_date}/{end_date}/{interval}/{region_id}

Path Parameters:

team_id: Team UUID
start_date: Start date (YYYY-MM-DD)
end_date: End date (YYYY-MM-DD)
interval: Billing interval ("daily", "weekly", "monthly")
region_id: Region ID as integer (e.g., 123) or "all"

Response:

json

{
  "team_id": "team-uuid",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "interval": "daily",
  "region_id": 123,
  "total_billing": 123.45,
  "currency_code": "USD",
  "currency_symbol": "$",
  "details": {
    "my-shared-volume": {
      "2024-01-01": {
        "cost": 5.67,
        "hours": 24.0,
        "from": "2024-01-01T00:00:00Z",
        "to": "2024-01-01T23:59:59Z"
      },
      "2024-01-02": {
        "cost": 5.67,
        "hours": 24.0,
        "from": "2024-01-02T00:00:00Z",
        "to": "2024-01-02T23:59:59Z"
      }
    }
  }
}

Billing Calculation

The billing system calculates costs using:

Cost = Duration (hours) × Storage Size (GB) × (Price per GB/hour - Inclusive Amount)

Key Features:

Time-based billing: Precise to the hour
Inclusive amounts: Free tier deducted from costs
Multi-policy support: Handles pricing policy changes over time
Proportional billing: Handles creation/deletion mid-period

Workflows & Examples

Complete Shared Volume Lifecycle

1. Create and Discover

bash

# First, get available storage blocks
curl -X GET "/api/shared-volumes/shared-storage-blocks?team_id=team-123&region_id=456" \
  -H "X-API-Key: your-key"

# Create a shared volume using a storage block
curl -X POST "/api/shared-volumes" \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ml-dataset",
    "storage_block_id": "storage-block-uuid",
    "region_id": 456,
    "team_id": "team-123"
  }'

# List available volumes
curl -X GET "/api/shared-volumes?page=0&per_page=10" \
  -H "X-API-Key: your-key"

2. GPUaaS Integration

bash

# Find compatible volumes for pool
curl -X GET "/api/gpuaas/pool/shared-volumes?pool_id=456&team_id=team-123" \
  -H "X-API-Key: your-key"

# Calculate subscription cost
curl -X POST "/api/gpuaas/calculate-pool-subscription" \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "pool_id": 456,
    "team_id": "team-123",
    "vgpus": 4,
    "vcpus": 8,
    "memory_mb": 16384,
    "instance_type_id": "instance-uuid",
    "ephemeral_storage_block_id": "storage-uuid",
    "shared_volumes": [123],
    "image_id": "image-uuid"
  }'

# Subscribe to pool with shared volume
curl -X POST "/api/gpuaas/pool/subscribe" \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "pool_id": 456,
    "team_id": "team-123",
    "vgpus": 4,
    "vcpus": 8,
    "memory_mb": 16384,
    "instance_type_id": "instance-uuid",
    "ephemeral_storage_block_id": "storage-uuid",
    "shared_volumes": [123],
    "image_id": "image-uuid"
  }'

3. Billing Analysis

bash

# Get monthly billing for all regions
curl -X GET "/api/team-billing/shared-storage/team-123/2024-01-01/2024-01-31/monthly/all" \
  -H "X-API-Key: your-key"

# Get daily billing for specific region (using region ID as integer)
curl -X GET "/api/team-billing/shared-storage/team-123/2024-01-01/2024-01-07/daily/456" \
  -H "X-API-Key: your-key"