> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Create a load balancer ## OpenAPI ````yaml /api-reference/specs/loadbalancer.yaml post /v1/load-balancers openapi: 3.0.3 info: title: Basaltic Load Balancer API version: 1.0.0 description: | Managed load balancers: listeners, target pools, health checks and the TLS certificates a listener terminates. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://loadbalancer.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] paths: /v1/load-balancers: post: tags: - Load Balancers summary: Create a load balancer operationId: createLoadBalancer parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateLoadBalancerRequest' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/LoadBalancerResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateLoadBalancerRequest: type: object required: - name - type - vpc_id - subnet_id - flavor_id - security_group_ids properties: name: type: string description: 1..127 chars of [A-Za-z0-9._-] example: web-lb type: type: string enum: - application - network example: application vpc_id: type: string format: uuid description: VPC the LB will live in. Must match subnet_id's VPC. example: c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9 subnet_id: type: string format: uuid description: >- Subnet the LB instances attach to. The virtual IP is allocated from this subnet. example: d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0 flavor_id: type: string format: uuid description: Compute flavor for each LB instance. example: e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1 replica_count: type: integer minimum: 1 maximum: 10 default: 1 description: Number of LB compute instances. Defaults to 1; pick >=2 for HA. example: 2 floating_ip_id: type: string format: uuid description: Optional FIP attached on create for public exposure. example: f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2 security_group_ids: type: array description: >- Security groups attached to every replica NIC (AWS ALB shape). A VPC NIC with no security group denies all data traffic, so the listener port(s) must be opened by a security group listed here. Re-applied to replacement replicas. The LB's own control-plane path (agent config + heartbeat via the metadata endpoint) is always-allowed and needs none. items: type: string format: uuid example: - d1b6f3a8-4c2e-4a9d-8f7b-1e5c3a2d9b4f key_names: type: array description: >- Platform-operator break-glass only. Stamps SSH keypairs onto the replica VMs, which run the platform's own envoy and lbaas-agent; a tenant reaches the load balancer over its VIP, never over SSH. Accepted only from the platform account and only with `loadbalancer:StampBreakGlassKeys` — any other account setting it is rejected with 400 `INVALID_INPUT`. items: type: string example: - ops-breakglass tags: $ref: '#/components/schemas/Tags' LoadBalancerResponse: type: object properties: load_balancer: $ref: '#/components/schemas/LoadBalancer' Tags: type: object additionalProperties: type: string example: environment: production team: backend LoadBalancer: type: object required: - id - crn - account_id - name - type - status - vpc_id - subnet_id - flavor_id - replica_count - tags - created_at - updated_at properties: id: type: string format: uuid example: 4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c crn: type: string description: IAM resource CRN example: >- crn:loadbalancer:sa-saopaulo-1:my-account:loadbalancer/4e1f8c2a-9b3d-4f6e-8a1c-2d5e7f9a0b3c account_id: type: string format: uuid example: 6f9619ff-8b86-4d01-b42d-00cf4fc964ff name: type: string example: web-lb type: type: string enum: - application - network description: ALB-shape (L7) vs NLB-shape (L4) example: application status: type: string enum: - provisioning - active - error - deleting example: active error_message: type: string example: subnet has no free addresses vpc_id: type: string format: uuid description: VPC the LB lives in. example: c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9 subnet_id: type: string format: uuid description: Subnet hosting the LB's compute instances and VIP. example: d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0 flavor_id: type: string format: uuid description: >- Compute flavor each LB instance runs on. Must be a loadbalancer-family flavor. example: e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1 replica_count: type: integer minimum: 1 maximum: 10 description: Number of LB compute instances. >=2 for HA. example: 2 vip_v4: type: string description: >- Virtual IP for the load balancer; traffic is distributed to backends per connection. example: 203.0.113.50 vip_v6: type: string description: Internal IPv6 VIP (set when the subnet is dual-stack). example: 2001:db8::32 public_vip_v6: type: string description: >- Public IPv6 GUA for the load balancer — the v6 analogue of a floating IP (IPv6 has no NAT, so this address is itself the public ingress, anycast-advertised). Set on an internet-facing LB in a dual-stack subnet. example: 2a13:9500:1a6:101::a floating_ip_id: type: string format: uuid description: Optional FIP attached for public exposure. NULL ⇒ private-only LB. example: f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2 dns_name: type: string example: web-lb.my-account.lb.sa-saopaulo-1.basaltic.sh description: >- Convenience hostname auto-published for the load balancer, `{name}.{account-handle}.lb.{region}.{base-domain}`. Resolves to the floating IP on an internet-facing LB and to the private VIP otherwise. Omitted in regions where auto-DNS is not configured — the VIP and FIP stay authoritative either way. tags: $ref: '#/components/schemas/Tags' created_at: type: string format: date-time example: '2026-01-15T09:30:00Z' updated_at: type: string format: date-time example: '2026-01-15T09:30:00Z' Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters request_id: type: string format: uuid description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 Conflict: description: Resource conflict (e.g., already exists, invalid state) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CONFLICT message: Resource with this name already exists request_id: 550e8400-e29b-41d4-a716-446655440000 UnprocessableEntity: description: | The request is well-formed but cannot be processed as sent. On the operations that accept `Idempotency-Key` this is the key-reuse case: the key was first seen with a different request payload, so replaying the stored outcome would answer a question the caller did not ask. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_KEY_REUSED message: >- This Idempotency-Key was already used with a different request payload request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: SignatureAuth: type: apiKey in: header name: Authorization description: > Request signing with an access key issued to a service account. An HMAC-SHA256 over a canonical form of the request, close to AWS SigV4. The `basaltic` CLI signs for you. Send `Authorization`, `X-Date` (UTC, `YYYYMMDDTHHMMSSZ`) and `X-Nonce` (random per request); add `X-Content-Sha256` to bind a body, and `X-Amz-Security-Token` when using temporary credentials. ``` Authorization: BASALTIC-HMAC-SHA256 Credential=///basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature= ``` `` is the region code you are calling, or `global` for the global services. A signature is valid for 5 minutes from `X-Date`, and mutating requests are replay-guarded on the nonce. **Full signing procedure, including a working implementation:** https://docs.basaltic.sh/authentication ## Rate limits There is no global request budget. A limit applies only where an operation documents a `429`, and that operation says what it counts. Those responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and, on a `429`, `Retry-After` — read them rather than hard-coding a number. Retrying before `Retry-After` is refused and extends the window. Everything else is bounded by quota, not by request rate. ````