Load balancers

A network load balancer is an IP address that the platform distributes across a set of member instances. Workspace members interact with load balancers through the workspace-scoped paths described below. Creating and deleting a load balancer require staff access and use flat /v1/net-lbs paths. Each member instance must configure the load balancer address inside the guest, for example on its loopback interface, to answer traffic. All path parameters are required and use string IDs. Request bodies are required where shown. See Workspaces and scope and Pagination for the conventions these endpoints follow.

List load balancers

GET/v1/workspaces/{wid}/net-lbsList load balancers in a workspace

Returns the load balancers owned by a workspace, with pagination.

Path parameters

Name	Type	Description
wid	string	Workspace ID

All query parameters are optional.

Query parameters

Name	Type	Description
q	string	Quick search by name or ID
id	string[]	Filter to specific load balancer IDs
name	string	Filter by name
address	string	Filter by IP address
owner	string[]	Filter by workspace ID
instances	string[]	Filter to balancers that have any of these instance IDs as members

Plus the shared pagination parameters. Returns a paged list of load balancer objects, each containing id, name, address, and nullable owner (workspace summary).

curl https://api.galaxygate.net/v1/workspaces/42/net-lbs \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -A 'curl/8.5'

Fetch a load balancer

GET/v1/workspaces/{wid}/net-lbs/{bid}Fetch load balancer detail

Path parameters

Name	Type	Description
wid	string	Workspace ID
bid	string	Load balancer ID

Returns the load balancer detail: id, name, address, and nullable owner (workspace summary).

Update a load balancer

PATCH/v1/workspaces/{wid}/net-lbs/{bid}Update load balancer settings

Updates load balancer settings. All body fields are optional. Omit a field to leave it unchanged.

Path parameters

Name	Type	Description
wid	string	Workspace ID
bid	string	Load balancer ID

Request body

Field	Type	Description
name	string	Rename the load balancer, 4 to 32 characters
address	string	Staff only. Change the IPv4 address or whole CIDR block. Ignored for workspace members.
owner	string	Staff only. Reassign by workspace ID. Ignored for workspace members.

Returns nothing on success (200 OK).

List member instances

GET/v1/workspaces/{wid}/net-lbs/{bid}/instancesList member instances

Returns the instances currently attached to the load balancer, with pagination.

Path parameters

Name	Type	Description
wid	string	Workspace ID
bid	string	Load balancer ID

Query parameters

All query parameters are optional.

Name	Type	Description
q	string	Quick search
ip	string	IP address filter
id	string[]	Instance IDs
name	string	Instance name filter
node	string[]	Node IDs
sku	string[]	Product identifiers
iso	string[]	ISO IDs
boot	string	DISK or ISO
online	boolean	Online or offline instances
state	string[]	PENDING, AVAILABLE, FAILED, SUSPENDED, DELETING, or UNPLACED
terminating	boolean	Instances scheduled for termination
backup_plan	string[]	Backup plan IDs
region	string	NA_01
vpc	string[]	VPC IDs
os	string	WINDOWS, LINUX, or BSD
owner	string[]	Workspace IDs

Plus the shared pagination parameters.

Returns a paged list of instance summaries, each containing id and name.

Add a member instance

PUT/v1/workspaces/{wid}/net-lbs/{bid}/instances/{iid}Attach an instance to a load balancer

Attaches an instance to the load balancer. The caller needs write permission on both resources. The instance must have an IPv4 address and must not already be attached. Responds 202 Accepted because the attachment is asynchronous.

Path parameters

Name	Type	Description
wid	string	Workspace ID
bid	string	Load balancer ID
iid	string	Instance ID to attach

No request body. Returns 202 Accepted with a WorkflowData object. See Asynchronous operations.

Remove a member instance

DELETE/v1/workspaces/{wid}/net-lbs/{bid}/instances/{iid}Detach an instance from a load balancer

Detaches an instance from the load balancer. Responds 202 Accepted because the detachment is asynchronous.

Path parameters

Name	Type	Description
wid	string	Workspace ID
bid	string	Load balancer ID
iid	string	Instance ID to detach

No request body. Returns 202 Accepted with a WorkflowData object. See Asynchronous operations.

---

Flat endpoints

These endpoints use paths without a workspace prefix. Creating and deleting require staff access. Fetch, update, and membership operations check permissions on the target resources.

Create a load balancer

POST/v1/net-lbsCreate a load balancer

Requires staff access. Creates a load balancer with an optional owning workspace. The address must be an IPv4 address or a whole CIDR block, for example 203.0.113.0/28.

Request body

Field	Type	Required	Description
name	string	yes	Display name, 4 to 32 characters
address	string	yes	IPv4 address or whole CIDR block to assign
owner	string or null	no	Owning workspace ID. Omit or send null to leave unowned.

curl -X POST https://api.galaxygate.net/v1/net-lbs \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -A 'curl/8.5' \
  -d '{
    "name": "lb-203-0-113-10",
    "address": "203.0.113.10",
    "owner": "42"
  }'

Returns 200 OK with id, name, address, and nullable owner.

Delete a load balancer

DELETE/v1/net-lbs/{bid}Delete a load balancer

Requires staff access. Deletes a load balancer and queues network updates for its members. This is asynchronous and responds 202 Accepted.

Path parameters

Name	Type	Description
bid	string	Load balancer ID

Returns 202 Accepted with no body.

List load balancers across workspaces

GET/v1/net-lbsSearch load balancers across workspaces

No path parameters or request body. All query parameters are optional.

Query parameters

Name	Type	Description
q	string	Quick search by name or ID
id	string[]	Load balancer IDs
name	string	Name filter
address	string	IP address filter
owner	string[]	Workspace IDs
instances	string[]	Member instance IDs

Plus the shared pagination parameters.

Returns 200 OK with a paged list of load balancer objects with id, name, address, and nullable owner.

Fetch by ID

GET/v1/net-lbs/{bid}Fetch by ID

Path parameters

Name	Type	Description
bid	string	Load balancer ID

Returns 200 OK with id, name, address, and nullable owner.

Update by ID

PATCH/v1/net-lbs/{bid}Update by ID

Path parameters

Name	Type	Description
bid	string	Load balancer ID

Request body

All fields are optional. The body is required.

Field	Type	Description
name	string	Display name, 4 to 32 characters
address	string	Staff only. IPv4 address or whole CIDR block
owner	string	Staff only. New owning workspace ID

Staff fields are ignored for workspace members.

Returns 200 OK with no body.

List members by ID

GET/v1/net-lbs/{bid}/instancesList members by ID

Path parameters

Name	Type	Description
bid	string	Load balancer ID

Accepts the optional query parameters in List member instances, including shared pagination parameters.

Returns 200 OK with a paged list of instance summaries containing id and name.

Attach a member by ID

PUT/v1/net-lbs/{bid}/instances/{iid}Attach a member by ID

Path parameters

Name	Type	Description
bid	string	Load balancer ID
iid	string	Instance ID

No request body. Requires write permission on both resources. The instance must have an IPv4 address and must not already be attached.

Returns 202 Accepted with a WorkflowData object for the queued network update.

Detach a member by ID

DELETE/v1/net-lbs/{bid}/instances/{iid}Detach a member by ID

Path parameters

Name	Type	Description
bid	string	Load balancer ID
iid	string	Instance ID

No request body. Requires write permission on both resources.

Returns 202 Accepted with a WorkflowData object for the queued network update.