Create a server

Creating an instance is a single call to your workspace's instances endpoint. It returns a workflow right away and provisions the machine in the background, so you create the server first and then poll until it is running.

POST /v1/workspaces/{wid}/instances

Two request shapes

Every create request carries a type field that selects one of two shapes:

• PLAN: provision from a preset plan. The plan fixes the CPU, memory, storage, and bandwidth, and you send a single plan ID.
• CUSTOM: size the instance yourself. You send the full per-part specs (group, cpu, memory_bytes, bandwidth, and a storage list).

type is required. If you leave it out the request is rejected before anything else is validated. The fields outside the specs (name, region, image, networking, and so on) are the same for both shapes.

Minimum request

Both shapes require name and a placement (region). A CUSTOM request additionally requires group, cpu, memory_bytes, bandwidth, and at least one storage disk.

curl -X POST "https://api.galaxygate.net/v1/workspaces/$WORKSPACE_ID/instances" \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CUSTOM",
    "name": "web-01",
    "region": "NA_01",
    "group": "RYZEN",
    "cpu": 2,
    "memory_bytes": 4294967296,
    "bandwidth": {
      "upload_bytes_sec": 125000000,
      "download_bytes_sec": 125000000
    },
    "storage": [
      { "size_bytes": 85899345920, "boot": true }
    ],
    "image": 45,
    "ips": [
      { "family": "IPv4", "ddos": false },
      { "family": "IPv6" }
    ],
    "start": true
  }'

A PLAN request is shorter, because the plan carries the specs:

curl -X POST "https://api.galaxygate.net/v1/workspaces/$WORKSPACE_ID/instances" \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PLAN",
    "name": "web-01",
    "region": "NA_01",
    "plan": 12,
    "image": 45,
    "start": true
  }'

Shared fields

These fields apply to both shapes.

• type (string, required): PLAN or CUSTOM.
• name (string, required): the instance name. It must be a valid hostname.
• region (string, required): where to deploy. One of NA_01 or PRIVATE_CLOUD. You must supply either a region or a node.
• image (integer, optional): the ID of a template, backup, or ISO to provision from. A template or backup is restored onto the boot disk; an ISO is attached as a boot device. See Choose a source image.
• ips (array, optional): floating IPs to allocate and attach. See Networking.
• start (boolean, optional): start the instance immediately after it is created.
• boot (string, optional): boot mode, either DISK or ISO.
• cloud_init (string, optional): a cloud-config YAML string to run on first boot. See Run code with cloud-init.
• disable_cloud_init (boolean, optional): turn off vendor cloud-init features on the instance.
• vpcs (array of integers, optional): VPC IDs to attach at creation. Each one gets its own private NIC and an IP allocated from that VPC's range.

PLAN fields

• plan (integer, required): the plan ID to provision from. The plan sets the CPU, memory, storage, and bandwidth.

When you create from a plan and omit ips, the instance is given one IPv4 and one IPv6 address by default.

CUSTOM fields

• group (string, required): the service group, one of UNDEFINED, LIGHTNING, RYZEN, or DEDICATED.
• cpu (integer, required): number of vCPU cores, from 1 to 256.
• memory_bytes (integer, required): memory in bytes, from 512 MiB (536870912) to 512 GiB. For example, 4294967296 is 4 GiB.
• bandwidth (object, required): the network caps. Both sub-fields are required:
  • upload_bytes_sec (integer): upload speed in bytes per second, from 125000 (1 Mbps) to 1250000000 (10 Gbps).
  • download_bytes_sec (integer): download speed in bytes per second, over the same range.
• storage (array, required): the instance's disks. Send at least one, and exactly one must be the boot disk. Each entry is:
  • size_bytes (integer, required): disk size in bytes, from 10 GB (10485760000) to 1 TB.
  • boot (boolean): whether this is the boot disk. Exactly one disk in the list must set boot to true.
  • backing (string, optional): storage backing, either LOCAL (the default) or CEPH.

When you create a custom instance and omit ips, the instance is created with no public IPs. List the IPs you want explicitly.

Choose a source image

To install an operating system, pass the image field with the ID of a template, backup, or ISO. In the panel wizard this is the step that reads "Select a template, backup or ISO to provision from." A template or backup is restored onto the boot disk; an ISO is attached as a boot device and is typically paired with boot set to ISO. If you omit image, the instance provisions with an empty boot disk.

Networking

The ips field is a list of floating IPs to allocate and attach. Each entry has:

• family (string, required): the IP family, either IPv4 or IPv6.
• ddos (boolean, optional): allocate the address from a DDoS-protected pool. This applies to IPv4 addresses.

To request one address of each family, send two entries:

"ips": [
  { "family": "IPv4", "ddos": false },
  { "family": "IPv6" }
]

Poll until it is running

The call returns a workflow, which means provisioning has started but not finished. Poll the instance until it is ready:

curl "https://api.galaxygate.net/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN"

While provisioning runs, the instance's state is PENDING. It becomes AVAILABLE once provisioning finishes (or FAILED if it did not complete). When you also asked the API to start it, the online field flips to true once the machine is powered on and booting. Poll until state is AVAILABLE, then give a fresh instance a minute to finish booting before your first connection attempt.

If you are creating many servers in a loop and start seeing 429 Too Many Requests, slow your polling down and back off.

In the panel

On the Instances page in dash.galaxygate.net, the New Instance button opens a wizard: choose a region, choose an instance from the plan table (or set custom specs), select a template, backup, or ISO to provision from, then confirm. The wizard walks the same fields shown above and submits when you click Create Instance.

The panel wizard walks the same fields (choose a region and a plan), then Create Instance (circled) submits them.

Picking a plan from the table submits a PLAN request, and setting custom specs submits a CUSTOM request. The form does the same thing as the API request on this page.

Tear it down

Deleting an instance is also a single call. It returns a workflow and runs in the background, and it is permanent:

DELETE /v1/instances/{id}

curl -X DELETE "https://api.galaxygate.net/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN"

This cannot be undone

Deleting an instance destroys the server and its disk. There is no recovery afterward. Make sure you have a snapshot or backup first if you might want the data back.

If a termination is still pending and you change your mind, cancel it. The body takes the instance ID:

curl -X POST "https://api.galaxygate.net/v1/commands/cancel-termination" \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "instance": 1526665089190330368 }'

Next step

Power controls to start and stop the server, or Run code with cloud-init to have it configure itself at boot.