Load Balancers API

List load balancers

GET /api/v1/load-balancers

const { data: lbs } = await puchify.loadBalancers.list({ status: "running" })

lbs = puchify.load_balancers.list(status="running")

lbs, err := client.LoadBalancers.List(ctx, &puchify.LBListParams{
  Status: puchify.String("running"),
})

puchify lb list --status running

curl https://api.puchify.com/api/v1/load-balancers \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Query parameters:

Parameter	Type	Description
`cursor`	string	Pagination cursor
`limit`	integer (1-100)	Results per page (default 50)
`status`	string	Filter by status (`creating`, `running`, `deleted`)
`sort`	`name` \| `created_at`	Sort field
`order`	`asc` \| `desc`	Sort direction

Create a load balancer

POST /api/v1/load-balancers

const { data: lb } = await puchify.loadBalancers.create({
  name: "web-lb",
  region: "us-east",
  algorithm: "least_connections",
  port: 443,
  protocol: "https",
})

lb = puchify.load_balancers.create(
  name="web-lb",
  region="us-east",
  algorithm="least_connections",
  port=443,
  protocol="https",
)

lb, err := client.LoadBalancers.Create(ctx, &puchify.CreateLBInput{
  Name: "web-lb", Region: "us-east",
  Algorithm: puchify.String("least_connections"),
  Port: puchify.Int(443), Protocol: puchify.String("https"),
})

puchify lb create --name web-lb --region us-east --algorithm least_connections --port 443

curl -X POST https://api.puchify.com/api/v1/load-balancers \
  -H "Authorization: Bearer $PUCHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"web-lb","region":"us-east","algorithm":"least_connections","port":443,"protocol":"https"}'

Request body:

Field	Type	Required	Description
`name`	string	yes	Load balancer name (2-40 chars)
`region`	string	yes	Region ID
`algorithm`	`round_robin` \| `least_connections` \| `ip_hash`	no	Balancing algorithm (default: `round_robin`)
`port`	integer	no	Frontend port (default: 80 for HTTP, 443 for HTTPS)
`protocol`	`http` \| `https` \| `tcp`	no	Frontend protocol (default: `http`)
`health_check_path`	string	no	HTTP health check path (default: `/health`)
`sticky_sessions`	boolean	no	Enable cookie-based session stickiness (default: false)
`ssl_certificate_id`	string	no	SSL certificate ID for HTTPS termination

Get a load balancer

GET /api/v1/load-balancers/{id}

const { data: lb } = await puchify.loadBalancers.get("lb_abc123")

lb = puchify.load_balancers.get("lb_abc123")

lb, err := client.LoadBalancers.Get(ctx, "lb_abc123")

puchify lb get lb_abc123

curl https://api.puchify.com/api/v1/load-balancers/lb_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Update a load balancer

PATCH /api/v1/load-balancers/{id}

const { data: lb } = await puchify.loadBalancers.update("lb_abc123", {
  algorithm: "round_robin",
})

lb = puchify.load_balancers.update("lb_abc123", algorithm="round_robin")

lb, err := client.LoadBalancers.Update(ctx, "lb_abc123", &puchify.UpdateLBInput{
  Algorithm: puchify.String("round_robin"),
})

puchify lb update lb_abc123 --algorithm round_robin

curl -X PATCH https://api.puchify.com/api/v1/load-balancers/lb_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"algorithm":"round_robin"}'

Request body:

Field	Type	Required	Description
`algorithm`	`round_robin` \| `least_connections` \| `ip_hash`	no	Balancing algorithm
`port`	integer	no	Frontend port
`protocol`	`http` \| `https` \| `tcp`	no	Frontend protocol
`health_check_path`	string	no	HTTP health check path
`sticky_sessions`	boolean	no	Enable/disable session stickiness

Delete a load balancer

DELETE /api/v1/load-balancers/{id}

await puchify.loadBalancers.delete("lb_abc123")

puchify.load_balancers.delete("lb_abc123")

err := client.LoadBalancers.Delete(ctx, "lb_abc123")

puchify lb delete lb_abc123

curl -X DELETE https://api.puchify.com/api/v1/load-balancers/lb_abc123 \
  -H "Authorization: Bearer $PUCHIFY_API_KEY"

Attach a backend server

POST /api/v1/load-balancers/{id}/attach

const { data: lb } = await puchify.loadBalancers.attach("lb_abc123", {
  server_id: "svr_def456",
  port: 8080,
})

lb = puchify.load_balancers.attach("lb_abc123", server_id="svr_def456", port=8080)

lb, err := client.LoadBalancers.Attach(ctx, "lb_abc123", &puchify.LBAttachInput{
  ServerID: "svr_def456", Port: puchify.Int(8080),
})

puchify lb attach lb_abc123 --server-id svr_def456 --port 8080

curl -X POST https://api.puchify.com/api/v1/load-balancers/lb_abc123/attach \
  -H "Authorization: Bearer $PUCHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"svr_def456","port":8080}'

Request body:

Field	Type	Required	Description
`server_id`	string	yes	Server ID to attach
`port`	integer	no	Backend port (defaults to the frontend port)

Detach a backend server

POST /api/v1/load-balancers/{id}/detach

const { data: lb } = await puchify.loadBalancers.detach("lb_abc123", {
  server_id: "svr_def456",
})

lb = puchify.load_balancers.detach("lb_abc123", server_id="svr_def456")

lb, err := client.LoadBalancers.Detach(ctx, "lb_abc123", &puchify.LBDetachInput{
  ServerID: "svr_def456",
})

puchify lb detach lb_abc123 --server-id svr_def456

curl -X POST https://api.puchify.com/api/v1/load-balancers/lb_abc123/detach \
  -H "Authorization: Bearer $PUCHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"svr_def456"}'

Request body:

Field	Type	Required	Description
`server_id`	string	yes	Server ID to detach

Polling for readiness

const lb = await puchify.loadBalancers.waitFor("lb_abc123", "running", {
  timeout: 300_000,
  pollInterval: 5_000,
})

lb = puchify.load_balancers.wait_for("lb_abc123", "running", timeout=300)

lb, err := puchify.WaitFor(ctx, client.LoadBalancers.Get, "lb_abc123", "running",
  puchify.WithTimeout(5*time.Minute),
)

Response shape

{
  "data": {
    "id": "lb_abc123",
    "name": "web-lb",
    "status": "running",          // creating | running | deleted
    "region": "us-east",
    "algorithm": "least_connections",
    "protocol": "https",
    "port": 443,
    "ipv4": "203.0.113.50",
    "health_check_path": "/health",
    "sticky_sessions": true,
    "backends": [
      {
        "server_id": "svr_def456",
        "port": 8080,
        "status": "healthy"       // healthy | unhealthy | draining
      }
    ],
    "created_at": "2026-05-28T10:30:00Z",
    "updated_at": "2026-05-28T10:32:00Z"
  },
  "meta": {
    "persistence": "synced"
  }
}

Error codes

Code	Description
`404`	Load balancer or backend server not found
`409`	Backend server is already attached
`422`	Invalid protocol/port combination or region unavailable

Load Balancers API

On this page