Skip to main content

Create Node

POST/api/v1/nodes/

Query parameters

  • project_idQuerystringoptional

    Identifier of the project to scope the request to. Optional; if omitted, the account's default project is used.

    • optional
    • if omitted, the request is applied to the default project
    example{{project_id}}
  • apikeyQuerystringoptional

    API key for authenticating the create node request

    • required
    • non-empty string
    example{{api_key}}
  • locationQuerystringoptional

    Location identifier for the node

    • must be a non-empty string
    • should be a valid location code
    example{{location}}

Request body

application/json

object
labelstring

Free-form label applied to the node. Used to organize nodes in the console and in resource filtering. Use "default" if you have no labelling scheme.

exampledefault
  • non-empty string
  • max length 50 characters
namestringrequired

Human-readable identifier for the node. Appears in the dashboard, billing reports, and as the hostname on the provisioned VM. Must be unique within the project.

exampleE1LC-2-6GB-272
  • non-empty string, 3-50 characters
  • allowed characters are letters, digits, and hyphens
  • must be unique within the project
regionstringrequired

Region code where the node will be provisioned. Region availability depends on the chosen plan and image - verify with the plans API before submitting.

examplencr
  • required
  • must match a valid region code (e.g. `ncr`, `delhi`, `chennai`)
planstringrequired

Plan SKU that selects vCPU, RAM, disk, and instance series. Plan identifiers are returned by the plans API and follow the convention <series>-<vCPU>vCPU-<RAM>RAM-<DISK>DISK-<series>-<template>-<image>-<region>.

exampleE1-2vCPU-6RAM-0DISK-E1LC-Onetemplate-Ubuntu24.04-Delhi
  • required
  • must reference an existing plan SKU returned by the plans API
  • the plan's region must match the `region` field
imagestringrequired

OS image name to install on the node. Use the OS plans API to list supported images for a given plan/region.

exampleUbuntu-24.04-Distro
  • required
  • non-empty string
  • allowed characters are letters, digits, hyphens, and periods
image_idinteger

Numeric image identifier corresponding to image. Provide this in addition to image for deterministic image selection (avoids ambiguity when an image name maps to multiple internal records). Cannot be combined with multi-node create - omit when number_of_instances > 1.

example12345
  • positive integer
  • must reference an image that exists in the chosen region
  • omit when `number_of_instances > 1`
is_saved_imageboolean

Set true to provision from a previously saved image template (a snapshot the user has captured and saved). When true, saved_image_template_id must be supplied.

examplefalse
saved_image_template_idinteger

Identifier of the saved-image template to clone from. Required when is_saved_image is true, otherwise must be null.

examplenull
  • required when `is_saved_image` is true
  • must be null when `is_saved_image` is false
  • must reference a saved-image template owned by the project
ssh_keysarrayrequired

SSH public keys to inject into the node's authorized_keys. Provide at least one key - password authentication is disabled by default. Keys are added for the OS's default admin user (e.g. ubuntu, centos).

  • required
  • at least one entry
  • each entry must be a valid SSH public key in OpenSSH format
  • no duplicate keys
start_scriptsarray

Shell scripts to execute via cloud-init the first time the node boots. Run sequentially as root. Use to install packages, fetch config, or register the node with an orchestrator.

  • each entry must be a valid shell script (max 16 KB)
  • scripts run as root via cloud-init `runcmd`
  • failures do not block boot but are logged to /var/log/cloud-init.log
disable_passwordboolean

Disable password authentication for the default OS user. Strongly recommended for production nodes. SSH key authentication continues to work.

exampletrue
diskinteger

Root disk size in GB. Only honored for E1-series plans (other plan series include a fixed root disk and ignore this field). To extend the root disk after creation, use the increase-root-storage endpoint.

example250
  • positive integer
  • minimum varies by plan; check plans API
  • only applies to E1-series plans
backupsboolean

Enable CDP backups on the node from creation. CDP creates continuous block-level backups. Billed separately - see the CDP backup plans API.

exampletrue
is_encryption_requiredboolean

Reserved for compliance use cases that require a record of whether encryption was mandated for the workload. Independent of whether encryption is actually enabled (isEncryptionEnabled).

examplefalse
isEncryptionEnabledboolean

Enable LUKS encryption on the node's root volume. When true, encryption_passphrase must be supplied. The passphrase cannot be recovered if lost.

exampletrue
encryption_passphrasestring

LUKS passphrase used to encrypt the root volume. Required when isEncryptionEnabled is true. Stored encrypted; cannot be retrieved or reset afterwards.

exampleApiAuto@123
  • required when `isEncryptionEnabled` is true
  • minimum 8 characters
  • recommended 16+ characters with mixed case, digits, and symbols
  • cannot be recovered if lost
enable_bitninjaboolean

Install and activate BitNinja server-side security on first boot (Linux only). BitNinja provides WAF, malware scanning, and DoS protection. Adds a per-node fee - see License Management.

examplefalse
security_group_idinteger

ID of the security group to attach at creation. If omitted, the project's default security group is used. Use the security groups API to look up IDs.

example12345
  • positive integer
  • must reference a security group in the same project and region
vpc_idinteger

ID of the VPC the node should join. When omitted, the project's default VPC for the region is used. Must be paired with subnet_id.

example12345
  • positive integer
  • VPC must be in the same region as the node
  • required together with `subnet_id`
subnet_idstring

ID of the subnet within vpc_id where the node's primary network interface will be placed. Passed as a string for compatibility with legacy callers.

example282
  • numeric string referencing a subnet inside `vpc_id`
  • required together with `vpc_id`
default_public_ipboolean

Assign an auto-allocated public IPv4 to the node. Set to false if you supply reserve_ip (you cannot have both - the reserved IP would be unused).

examplefalse
reserve_ipstring

Existing reserved public IPv4 address to attach as the node's primary public IP. Get one from the Reserve IP API. Mutually exclusive with default_public_ip: true and with multi-node create.

example1.2.3.4
  • valid IPv4 address that the project owns as a reserved IP
  • omit when `number_of_instances > 1`
  • cannot coexist with `default_public_ip: true`
is_ipv6_availedboolean

Attach an IPv6 address to the node at creation. Region must support IPv6 - check the network capabilities endpoint.

exampletrue
is_privateboolean

Provision the node on a private (dedicated) cluster instead of the shared public cluster. Requires the project to be entitled to a private cluster; additional private-cluster fields may be needed.

examplefalse
ngc_container_idinteger

NVIDIA GPU Cloud (NGC) container template ID to launch on the node. Only applicable to GPU plans. Leave null for general- purpose nodes.

examplenull
  • positive integer or null
  • only valid on GPU-capable plans
number_of_instancesintegerrequired

Number of identical nodes to provision in this request. Setting this above 1 disables reserve_ip and image_id - those flows are reserved for single-node create.

example1
  • required
  • integer between 1 and 5
  • when > 1, omit `reserve_ip` and `image_id`

Responses

200Successful response
object
codeinteger

HTTP status code returned for the Create Node operation

example200
  • integer
  • value between 200 and 299
dataobject
errorsobject
messagestring

Result message indicating the outcome of the node creation request

exampleSuccess
  • must be a non-empty string
  • max length 255 characters