Rename, scale, or resize a load balancer

curl --request PATCH \
  --url https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "web-lb",
  "replica_count": 3,
  "flavor_id": "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1",
  "tags": {
    "environment": "production",
    "team": "backend"
  }
}
'

import requests

url = "https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}"

payload = {
    "name": "web-lb",
    "replica_count": 3,
    "flavor_id": "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1",
    "tags": {
        "environment": "production",
        "team": "backend"
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'web-lb',
    replica_count: 3,
    flavor_id: 'e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1',
    tags: {environment: 'production', team: 'backend'}
  })
};

fetch('https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'web-lb',
    'replica_count' => 3,
    'flavor_id' => 'e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1',
    'tags' => [
        'environment' => 'production',
        'team' => 'backend'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}"

	payload := strings.NewReader("{\n  \"name\": \"web-lb\",\n  \"replica_count\": 3,\n  \"flavor_id\": \"e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1\",\n  \"tags\": {\n    \"environment\": \"production\",\n    \"team\": \"backend\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"web-lb\",\n  \"replica_count\": 3,\n  \"flavor_id\": \"e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1\",\n  \"tags\": {\n    \"environment\": \"production\",\n    \"team\": \"backend\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"web-lb\",\n  \"replica_count\": 3,\n  \"flavor_id\": \"e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1\",\n  \"tags\": {\n    \"environment\": \"production\",\n    \"team\": \"backend\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "load_balancer": {
    "id": "4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c",
    "crn": "crn:loadbalancer:sa-saopaulo-1:my-account:loadbalancer/4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c",
    "account_id": "6f9619ff-8b86-4d01-b42d-00cf4fc964ff",
    "name": "web-lb",
    "type": "application",
    "status": "active",
    "vpc_id": "c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9",
    "subnet_id": "d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0",
    "flavor_id": "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1",
    "replica_count": 2,
    "tags": {
      "environment": "production",
      "team": "backend"
    },
    "created_at": "2026-01-15T09:30:00Z",
    "updated_at": "2026-01-15T09:30:00Z",
    "error_message": "subnet has no free addresses",
    "vip_v4": "203.0.113.50",
    "vip_v6": "2001:db8::32",
    "public_vip_v6": "2a13:9500:1a6:101::a",
    "floating_ip_id": "f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2",
    "dns_name": "web-lb.my-account.lb.sa-saopaulo-1.basaltic.sh"
  }
}

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid request parameters",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You don't have permission to perform this action",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

PATCH

load-balancers

{id}

Rename, scale, or resize a load balancer

curl --request PATCH \
  --url https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "web-lb",
  "replica_count": 3,
  "flavor_id": "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1",
  "tags": {
    "environment": "production",
    "team": "backend"
  }
}
'

import requests

url = "https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}"

payload = {
    "name": "web-lb",
    "replica_count": 3,
    "flavor_id": "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1",
    "tags": {
        "environment": "production",
        "team": "backend"
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'web-lb',
    replica_count: 3,
    flavor_id: 'e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1',
    tags: {environment: 'production', team: 'backend'}
  })
};

fetch('https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'web-lb',
    'replica_count' => 3,
    'flavor_id' => 'e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1',
    'tags' => [
        'environment' => 'production',
        'team' => 'backend'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}"

	payload := strings.NewReader("{\n  \"name\": \"web-lb\",\n  \"replica_count\": 3,\n  \"flavor_id\": \"e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1\",\n  \"tags\": {\n    \"environment\": \"production\",\n    \"team\": \"backend\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"web-lb\",\n  \"replica_count\": 3,\n  \"flavor_id\": \"e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1\",\n  \"tags\": {\n    \"environment\": \"production\",\n    \"team\": \"backend\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://loadbalancer.{region}.basaltic.sh/v1/load-balancers/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"web-lb\",\n  \"replica_count\": 3,\n  \"flavor_id\": \"e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1\",\n  \"tags\": {\n    \"environment\": \"production\",\n    \"team\": \"backend\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "load_balancer": {
    "id": "4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c",
    "crn": "crn:loadbalancer:sa-saopaulo-1:my-account:loadbalancer/4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c",
    "account_id": "6f9619ff-8b86-4d01-b42d-00cf4fc964ff",
    "name": "web-lb",
    "type": "application",
    "status": "active",
    "vpc_id": "c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9",
    "subnet_id": "d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0",
    "flavor_id": "e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1",
    "replica_count": 2,
    "tags": {
      "environment": "production",
      "team": "backend"
    },
    "created_at": "2026-01-15T09:30:00Z",
    "updated_at": "2026-01-15T09:30:00Z",
    "error_message": "subnet has no free addresses",
    "vip_v4": "203.0.113.50",
    "vip_v6": "2001:db8::32",
    "public_vip_v6": "2a13:9500:1a6:101::a",
    "floating_ip_id": "f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2",
    "dns_name": "web-lb.my-account.lb.sa-saopaulo-1.basaltic.sh"
  }
}

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid request parameters",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You don't have permission to perform this action",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Authorizations

Authorization

string

header

required

BASALTIC-HMAC-SHA256 request signing for service-account (access-key) auth. An AWS-SigV4-style scheme: an HMAC-SHA256 over a canonical request, keyed by a signing key derived from your secret access key. The basaltic CLI does this for you; the steps below are for a non-CLI client.

Headers you send

Authorization (this scheme) — format below.
X-Date: request time in UTC, compact ISO-8601 basic: YYYYMMDDTHHMMSSZ (e.g. 20240115T103000Z). Must be within 5 minutes of server time.
X-Nonce: random per-request value (e.g. 16+ bytes of hex). Required — it is what makes each signature unique so the server can reject replays. X-Date alone is not enough (one-second resolution; UNSIGNED-PAYLOAD never enters the canonical request).
X-Content-Sha256 (optional): lowercase-hex SHA-256 of the request body, to bind the exact bytes to the signature — the server re-hashes and rejects a mismatch. Omit it, and put the literal UNSIGNED-PAYLOAD in the body-hash slot, for an empty body or a streaming upload that shouldn't be buffered.

Authorization header format

Authorization: BASALTIC-HMAC-SHA256 Credential=<access_key_id>/<date>/<region>/<service>/basaltic_request, SignedHeaders=<h1>;<h2>, Signature=<hex>

<date>: YYYYMMDD (the day part of X-Date).
<region>: target region code (e.g. sa-saopaulo-1), or global for the region-agnostic (IAM) endpoints.
<service>: basaltic.
SignedHeaders: the covered header names, lowercased and sorted, joined by ; — at minimum host;x-date;x-nonce (all three required).
Signature: lowercase hex from step 4.
Note the , (comma + space) between the three Authorization parameters.

Step 1 — canonical request

Join these six lines with \n (LF):

<HTTP-METHOD>
<canonical-path>
<canonical-query>
<canonical-headers>
<signed-headers>
<body-hash>

canonical-path: the URL-escaped request path (e.g. /v1/compute/instances).
canonical-query: each query key and value URL-encoded, sorted by key then value, joined by &; empty string when there is no query.
canonical-headers: for each signed header, name:value (name lowercased, value trimmed), sorted by name, each followed by a trailing \n.
signed-headers: the same names, lowercased, sorted, joined by ;.
body-hash: lowercase-hex SHA-256 of the body, or the literal UNSIGNED-PAYLOAD.

Step 2 — string to sign

Join with \n:

BASALTIC-HMAC-SHA256
<date>T000000Z
<date>/<region>/<service>/basaltic_request
<hex SHA-256 of the canonical request>

The second line is the credential date at midnight — NOT the X-Date value — and the third is the credential scope without the access-key id.

Step 3 — derive the signing key (HMAC chain over your secret)

kDate    = HMAC-SHA256("BASALTIC" + <secret_access_key>, <date>)
kRegion  = HMAC-SHA256(kDate, <region>)
kService = HMAC-SHA256(kRegion, <service>)
kSigning = HMAC-SHA256(kService, "basaltic_request")

Step 4 — signature

Signature = lowercase_hex( HMAC-SHA256(kSigning, <string-to-sign>) )

Example (POST with a JSON body)

X-Date: 20240115T103000Z
X-Nonce: 7f3a9c2e1b84d056
X-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Authorization: BASALTIC-HMAC-SHA256 Credential=BCAK1234567890ABCDEF/20240115/global/basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature=a1b2c3d4e5f6...

Request validity

Valid for 5 minutes from the X-Date timestamp.
The signature must cover at least host, x-date, and x-nonce.
Mutating requests (POST/PUT/PATCH/DELETE) that present a signed nonce are anti-replay guarded for the drift window; omitting X-Nonce is rejected.

Rate limits

There is no global request budget: a limit applies only where an operation documents a 429 response, and each such endpoint counts its own fixed window. Everything else is bounded by quota, not by request rate.

Per-endpoint request limits

A few endpoints are limited in front of the handler, counted per caller — the authenticated principal when the request carries credentials, the client IP otherwise. On this API surface that is the public region catalogue, GET /v1/regions: it guards no secret, and the budget is there because the catalogue is unauthenticated and database-backed.

An operation that is limited says so by documenting a 429. These responses — 429 and 2xx — carry the budget, so a client can pace itself instead of discovering the ceiling by hitting it:

X-RateLimit-Limit — requests allowed per window on this endpoint. Authoritative: read it rather than hard-coding a number.
X-RateLimit-Remaining — requests left in the window (0 on a 429).
X-RateLimit-Reset — seconds until the window resets. A duration, not a timestamp, so it needs no clock agreement.
Retry-After — on a 429 only; seconds to wait. Never zero.

Over the limit the response is 429 with error code RATE_LIMITED. Honor Retry-After — retrying sooner is refused and extends the window, since the refused attempt is itself counted.

Service-level limits

Some resources meter the work itself rather than the request, and are documented on the operation. They return 429 with their own error code and no rate-limit headers, because the budget is not a per-endpoint window: sending email is capped per (account, identity) per second (EMAIL_RATE_LIMIT), and charge attempts are capped per invoice (INVOICE_PAYMENT_ATTEMPTS_EXHAUSTED).

Path Parameters

string<uuid>

required

Example:

"4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c"

Body

application/json

name

string

Example:

"web-lb"

replica_count

integer

Resize the set of load balancer instances. Scale-out provisions the new replicas in sequence; scale-in removes the highest-indexed replicas best-effort. 1..10.

Required range: 1 <= x <= 10

Example:

3

flavor_id

string<uuid>

Resize each replica to a different compute flavor. Must be a loadbalancer-family flavor.

A running instance cannot change size in place, so the request records the new size and returns; the replicas already up are then replaced one at a time in the background. The load balancer temporarily runs one replica over replica_count while it does: the extra replica comes up on the new flavor and starts serving before any replica on the old one is retired, so the number serving never drops below replica_count — a resize does not cost you capacity, at any replica count.

Expect it to take several minutes, and poll GET /v1/load-balancers/{id}/replicas to watch: a replica has been replaced when its instance_id changes, and the resize is done when every flavor_id there matches this one.

The one exception is a load balancer already at the maximum of 10 replicas, which has nowhere to grow. There the replicas are replaced in place and 9 serve while each replacement boots.

Rejected up front if the account does not have the compute quota for the replacement replica, so a resize cannot half-apply and leave the load balancer short.

Example:

"e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1"

Response

load_balancer

object

Show child attributes

Overview

Identity and account

Quota

Audit

Billing

Compute

Database

Registry

Network

Load balancer

DNS

Certificate

Storage

KMS

Secrets

Queue

Notifications

Email

Telemetry

Rename, scale, or resize a load balancer

Authorizations

Headers you send

Authorization header format

Step 1 — canonical request

Step 2 — string to sign

Step 3 — derive the signing key (HMAC chain over your secret)

Step 4 — signature

Example (POST with a JSON body)

Request validity

Rate limits

Per-endpoint request limits

Service-level limits

Path Parameters

Body

Response