Network Volume

General conventions

• Base URL: BASE_API_URL
• Path: /bff/v1/networkvolume/{orgIdentifier}/workspaces/{workspaceIdentifier}/{action}
• Method: All endpoints use POST.
• Service-specific headers: X-Region: <region>
• Common headers (apiClient): X-Org-Id, X-Workspace-Id, X-User-Id
• Response envelope: { "code": "", "message": "", "data": ..., "total": 0 }
• Parameters: Query actions pass parameters via query string (body {}); all other actions pass parameters via JSON body.

Endpoints

Volume

#	Action	Query param	Body	Purpose
1	network-volume.list	status, sort_by, sort_type (asc | desc)	{}	List volumes
2	network-volume.create	—	{ name, capacity_gb }	Create volume
3	network-volume.update	—	{ volume_id, capacity_gb }	Expand capacity
4	network-volume.delete	—	{ volume_id }	Delete volume
5	network-volume.calculateprice	—	{}	Get unit price
6	network-volume.checkname	name	{}	Check duplicate name

S3 adapter key

#	Action	Query param	Body	Purpose
7	network-volume.lists3keys	—	{}	List S3 keys + S3 status
8	network-volume.creates3key	—	{ name }	Create S3 key (timeout 90s)
9	network-volume.gets3key	—	{ key_id }	S3 key details
10	network-volume.deletes3key	—	{ key_id }	Delete S3 key

Constraints

Field	Rule
name	Max 16 characters, regex ^[a-zA-Z][a-zA-Z0-9-]*$ (must start with a letter; letters, digits, - allowed)
capacity_gb	50 to 3000 GB (default 50)
Default mount point	/mnt/hps

Request body

2. network-volume.create

{ "name": "my-volume", "capacity_gb": 100 }

3. network-volume.update — increase capacity only

{ "volume_id": "...", "capacity_gb": 200 }

8. network-volume.creates3key

{ "name": "my-key" }

Responses

Action	Response (data)
network-volume.list	[{ id, name, vast_config_id, region_code, capacity_gb, endpoint, status, last_error, created_at, created_by, updated_at, updated_by }] (total in envelope)
network-volume.create / update / delete	Volume: same fields as list + vast_resources{ quota, view_policy, view }
network-volume.calculateprice	{ capacity_gb, price, price_per_gb_hour, hourly_cost, monthly_cost, total, currency_code, price_info{ currency, value, unit } } — FE priority: price_per_gb_hour → price → price_info.value; default currency USD
network-volume.checkname	{ is_duplicate: boolean } (FE also accepts isDuplicate, duplicated, exists, wrapped in data, or a bare boolean)

Enums

• volume status: ACTIVE, CREATING, PROCESSING, DELETING, DELETED, ERROR (on ERROR, inspect last_error)
• Region display: Ha Noi, Tokyo

Error codes

Error format

On error, HTTP status ≠ 2xx and the body has the following shape:

{ "code": "EQ-RESOURCE-00001", "message": "...", "params": { "quotaLevel": "Workspace" }, "role_based": true }

• role_based: true — the error message depends on the caller's role (MANAGEMENT / WS_ADMIN / MEMBER) and params.quotaLevel.
• HTTP 401 — the client logs out.

Common error codes (billing / quota / gateway)

Code	Meaning
INSUFFICIENT_BALANCE	Insufficient credits (role-based). Role MANAGEMENT auto-opens the top-up modal.
INSUFFICIENT_PERMISSIONS	The caller does not have permission to perform this action.
EQ-RESOURCE-00001	Quota reached (role-based, per params.quotaLevel).
EQ-RESOURCE-SYSTEM-LIMIT	Resource quota reached (params.name).
BFF-CREATING-CONCURRENCY	Another resource is being created in this workspace/service.
route_not_found	Endpoint does not exist.
method_not_allowed	Wrong method. Only POST is accepted.
request_too_large	Body exceeds 64 KB.
invalid_token	Token is invalid or expired.
gateway_internal_error	Internal gateway error.
upstream_unavailable	Backend service is temporarily unavailable.
gateway_timeout	Backend service timed out.