GPU Container

General conventions

• Base URL: https://api-neo.fpt.ai/
• Path: api/bff/v1/gpucontainer/{orgIdentifier}/workspaces/{workspaceIdentifier}/{action}
• Method: All endpoints use POST.
• Service-specific headers: X-ENV: <APP_ENV>, X-Region: <region>
• Common headers (apiClient): X-Org-Id, X-Workspace-Id, X-User-Id
• Response: { "data": {...}, "errors": [] }

How to get token and headers

1. Log in to the Portal and navigate to the GPU Container page.
2. Open the Network tab in browser DevTools, select the container.list request to get the API path format (including orgIdentifier and workspaceIdentifier).
3. Copy the following request headers: cookie, x-env, x-org-id, x-region, x-user-id, x-workspace-id.

Endpoints

#	Action	Query params	Body	Purpose
1	container.list	name (search, optional)	{}	List containers
2	container.get	container_id	{}	Container details
3	container.stat	—	{}	Statistics by status
4	container.create	—	See below	Create a container
5	container.start	container_id	{ "action": "START" }	Start
6	container.stop	container_id	{ "action": "STOP" }	Stop
7	container.restart	container_id	{ "action": "RESTART" }	Restart
8	container.delete	container_id	{}	Delete
9	container.edit	container_id	See below	Edit settings / update whitelist
10	container.downloadlog	container_id	{}	Download logs (responseType: blob)
11	container.template.list	—	{}	List templates
12	container.template.config	config_name	{}	Template configuration details
13	container.flavor.list	—	{}	List GPU flavors
14	cost-estimation	—	See below	Cost estimation

Request bodies

4. container.create

{
  "name": "my-container",
  "instance_type": "H100",
  "container_group": "",
  "purpose": "SERVICE",
  "description": "",
  "container_settings": [{
    "enable_ssh": true,
    "authorized_keys": [{ "name": "key1", "ssh_key": "ssh-ed25519 AAAA..." }],
    "image_setting": { "image_url": "...", "image_tag": "latest", "image_user": "", "image_password": "", "fptcloud_official": false },
    "volume_settings": [{ "volume_type": "TEMP_DISK | PERSISTENT_DISK", "mount_path": "/workspace", "mount_capacity": 100 }],
    "advance_setting": {
      "http_ports": [{ "container_port": 8888 }],
      "tcp_ports": [{ "container_port": 22 }],
      "container_envs": [{ "key": "K", "value": "V" }],
      "startup_cmd": { "cmd": [], "args": [] },
      "healthchecks": []
    }
  }],
  "billing_plan": { "billing_type": "PAYG", "billing_level": "NORMAL", "cost_estimate": 0, "currency_code": "USD" }
}

Response: { id, name, status }.

9. container.edit

Send back the full container object (retrieved from container.get) with your changes applied.

Top-level fields: id, status, created_at, updated_at, tenant_id, name, container_group, purpose, instance_type, billing_plan, description, tags, domain, version, deleted.

container_settings[] fields: enable_ssh, authorized_keys, ssh_connect, image_setting, volume_settings[{volume_name?, volume_type, mount_path, mount_capacity}], advance_setting{http_ports, tcp_ports, startup_cmd, container_envs, healthchecks, block_cidrs}.

To update the whitelist only:

{ "block_cidrs": [{ "type": "TCP | HTTP", "ports": [8888], "sources": ["1.2.3.4/32"], "description": "" }] }

14. cost-estimation

{
  "instance_type": "H100",
  "container_settings": [{ "volume_settings": [{ "volume_type": "PERSISTENT_DISK", "mount_path": "/data", "mount_capacity": 100 }] }]
}

Response: { org_id, items: [{ sku, quantity, price }], currency_code, total }.

Responses

Action	Response
container.list	data: { items: ListItem[], total, page?, page_size?, total_pages? }; ListItem: id, name, status, region, org_id, ws_id, created_by, purpose, instance_type, container_group, tenant_id, container_settings[{image_setting, enable_ssh, authorized_keys, ssh_connect}], billing_plan, tags, created_at, updated_at
container.get	Same as ListItem, but container_settings[] is fully populated: image_setting, enable_ssh, authorized_keys, ssh_connect, advance_setting, volume_settings, container_resource, observability.container_monitor{container_metric_url, container_log_url}
container.stat	data: { stats: [{ status, count }] }
container.template.list	data: { items: [{ name, url, icon?, priority?, fptcloud_official? }], total, page?, size? }
container.template.config	{ name, priority, fptcloud_official, purpose, flavor_name, description, instance_type, container_settings[{ image_settings, volume_settings, advanced_setting }] }
container.flavor.list	data: { items: [{ flavor, price_info{currency, value, unit?}, resource{cpu, ram, gpu, vram, temp_disk}, available, region }], total }

Enums

• status: CREATING, RUNNING, STOPPED, PROCESSING, FAILED, DELETING, DELETED
• billing_type: PAYG, SAVING_PLAN_1_WEEK, SAVING_PLAN_1_MONTH, SAVING_PLAN_3_MONTH, SAVING_PLAN_1_YEAR
• billing_level: NORMAL, WARNING, STOPPED, AT_RISK
• volume_type: TEMP_DISK, PERSISTENT_DISK

Error codes

Error format

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

{ "code": "DDI-SYSTEM-00001", "message": "...", "params": {}, "role_based": false }

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

Common error codes (gateway / BFF / billing)

Code	Meaning
INSUFFICIENT_BALANCE	Insufficient credits. Role MANAGEMENT auto-opens the top-up modal; other roles are prompted to contact the owner.
INSUFFICIENT_PERMISSIONS	The caller does not have permission to perform this action.
EQ-RESOURCE-SYSTEM-LIMIT	Resource quota reached (params.name).
BFF-CREATING-CONCURRENCY	Another resource is being created in this workspace/service. Wait for it to complete and try again.
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.

GPU Container error codes

Code	Message
DDI-SYSTEM-00001	The GPU Container service has not been configured for this tenant. Please contact support.
DDI-SYSTEM-00002	An unknown error occurred. Please try again later.