> ## 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 an instance pool > Create a pool from a launch template and a desired count. The desired_count instances are spawned synchronously; a background reconciler then converges member_count toward desired_count as it's changed. min_count/max_count default to desired_count. The top-level `tags` label the pool itself; `template.tags` are stamped on every instance it launches. ## OpenAPI ````yaml /api-reference/specs/compute.yaml post /v1/instance-pools openapi: 3.0.3 info: title: Basaltic Compute API version: 1.0.0 description: | Virtual machine instances, and the images, flavors, SSH keypairs and instance pools they are built from. Covers the whole instance lifecycle: start, stop, reboot, resize and reinstall. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://compute.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] paths: /v1/instance-pools: post: tags: - Compute summary: Create an instance pool description: | Create a pool from a launch template and a desired count. The desired_count instances are spawned synchronously; a background reconciler then converges member_count toward desired_count as it's changed. min_count/max_count default to desired_count. The top-level `tags` label the pool itself; `template.tags` are stamped on every instance it launches. operationId: createInstancePool parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InstancePoolCreateRequest' responses: '201': description: Pool created; initial instances spawned. content: application/json: schema: $ref: '#/components/schemas/InstancePoolResponse' '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' security: - SignatureAuth: [] 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: InstancePoolCreateRequest: type: object description: >- Two shapes are accepted for the launch config. `template` is the current one — the same fields instance create takes. The flat fields beside it are the shape pools shipped with; they still work, and the response renders both, so nothing written against either has to move. They are alternatives, not layers: sending `template` together with any flat launch field is refused with a 400 rather than resolved by a precedence rule you would have to know to predict what your replicas boot as. The pool's own fields — name, description, tags, sizing — stay at the top level in both shapes, because they describe the pool rather than the instances in it. A flavor and a primary subnet are required either way: as `template.flavor_id` + `template.networks[0].subnet_id`, or as the flat `flavor_id` + `subnet_id`. required: - name properties: name: type: string example: web-asg description: type: string tags: allOf: - $ref: '#/components/schemas/Tags' description: >- Labels on the pool resource, for IAM conditions (`basalt:RequestTag/` here, `basalt:ResourceTag/` on later operations) and cost attribution. They are not propagated to the instances the pool launches; `template.tags` is that set. A pool field, so it may be sent with either launch-config shape — unlike the deprecated flat fields below, it does not conflict with `template`. Replica tags are only reachable through `template.tags`. template: $ref: '#/components/schemas/InstancePoolTemplate' flavor_id: type: string format: uuid deprecated: true description: Superseded by `template.flavor_id`. image_id: type: string format: uuid deprecated: true description: Superseded by `template.image_id`. subnet_id: type: string format: uuid deprecated: true description: Superseded by `template.networks[0].subnet_id`. security_group_ids: type: array items: type: string format: uuid deprecated: true description: Superseded by `template.networks[0].security_group_ids`. keypair_names: type: array items: type: string deprecated: true description: Superseded by `template.key_names`. user_data: type: string format: byte deprecated: true description: Superseded by `template.user_data`. metadata: allOf: - $ref: '#/components/schemas/Metadata' deprecated: true description: Superseded by `template.metadata`. iam_role_id: type: string format: uuid deprecated: true description: Superseded by `template.iam_role_id`. boot_volume_size_gb: type: integer minimum: 1 maximum: 16384 deprecated: true description: Superseded by `template.boot_volume_size_gb`. boot_volume_type: type: string enum: - ssd - nvme deprecated: true description: Superseded by `template.boot_volume_type`. extra_nics: type: array items: $ref: '#/components/schemas/PoolTemplateNIC' deprecated: true description: Superseded by `template.networks[1:]`. data_volumes: type: array items: $ref: '#/components/schemas/PoolTemplateVolume' deprecated: true description: Superseded by `template.data_volumes`. assign_public_ip: type: boolean deprecated: true description: Superseded by `template.assign_public_ip`. desired_count: type: integer minimum: 0 maximum: 100 example: 2 min_count: type: integer minimum: 0 maximum: 100 example: 1 max_count: type: integer minimum: 1 maximum: 100 example: 3 InstancePoolResponse: type: object properties: instance_pool: $ref: '#/components/schemas/InstancePool' Tags: type: object additionalProperties: type: string example: environment: production team: backend InstancePoolTemplate: type: object description: >- The pool's launch config, in the shape a standalone instance create takes: same field names, same types, same meanings, so a client that can build an instance can build a pool of them without a second, narrower contract to learn. It belongs to the pool. There is no separate launch-template resource to create, version or share between pools. Networking is one ordered `networks` list, index 0 being the primary NIC, replacing the flat `subnet_id` + `extra_nics` split. `ip_address` and `mac` are part of that shared NIC shape but are refused here: every replica launches from this one template, so a fixed address would have the second replica ask for one the first already holds. properties: flavor_id: type: string format: uuid image_id: type: string description: >- Image to clone each replica's boot disk from. Accepts the same three forms instance create does: an image id, `name:version`, or a bare `name`. Unlike instance create, the reference is resolved ONCE, when the pool is created, and the resulting image id is what every replica boots — including replacements spawned months later. A tag re-resolved per replica would let a heal boot a newer build than its siblings, and a pool whose members are quietly not identical is the premise of the primitive breaking silently. To move a pool to a new build, change the template. boot_volume_size_gb: type: integer minimum: 1 maximum: 16384 boot_volume_type: type: string enum: - ssd - nvme description: Boot disk tier for every replica; omitted = the region default. networks: type: array description: >- Per-replica interfaces. Index 0 is the primary NIC and is required; the rest are extras. items: $ref: '#/components/schemas/NetworkConfig' data_volumes: type: array description: >- Blank per-replica data volumes, created and reclaimed with each replica. items: $ref: '#/components/schemas/PoolTemplateVolume' key_name: type: string description: SSH keypair name to authorize on every replica. key_names: type: array items: type: string description: SSH keypair names to authorize on every replica. user_data: type: string format: byte description: Base64-encoded user data (cloud-init), stamped on every replica. metadata: $ref: '#/components/schemas/Metadata' tags: allOf: - $ref: '#/components/schemas/Tags' description: >- Tags stamped on every instance this template launches. These are the replicas' tags, not the pool's — the pool's own labels are the top-level `tags`, and the two are independent. Changing them affects FUTURE launches only. The instances already running keep the tags they were launched with, so between the change and a refresh the pool holds members carrying two different tag sets; `stale_instance_count` is how many are still on the old one. POST /v1/instance-pools/{pool_id}/refresh rolls them onto the current template. iam_role_id: type: string format: uuid description: >- IAM role attached to every replica, reachable from its IMDS endpoint. assign_public_ip: type: boolean description: >- The older spelling of `networks[0].assign_public_ip`: each replica gets a floating IP on its PRIMARY NIC, allocated by the reconciler and released on scale-in. Per-NIC flags live on `networks[]`, and a replica can be public on a secondary interface while its primary stays private. Metadata: type: object additionalProperties: type: string example: environment: production team: backend PoolTemplateNIC: type: object description: One extra per-replica network interface. required: - subnet_id properties: subnet_id: type: string format: uuid security_group_ids: type: array items: type: string format: uuid assign_public_ip: type: boolean default: false description: >- Give THIS interface a floating IP on every replica, independently of the primary's. One allocation per replica per interface, each counted against the account's floating_ips quota and released on scale-in. PoolTemplateVolume: type: object description: >- One blank per-replica data volume, created with each replica and deleted with it. A mount_path makes the in-guest agent format (fstype, default ext4, only if blank) and mount it. required: - size_gb properties: size_gb: type: integer example: 100 volume_type: type: string enum: - ssd - nvme mount_path: type: string example: /data fstype: type: string example: ext4 delete_on_termination: type: boolean default: true description: >- Whether the volume is destroyed with the instance (default) or released back to available on teardown. Honoured on a pool template too: a replica scaled in, replaced or torn down with the pool releases the volume instead of destroying it when this is false. InstancePool: type: object description: >- A launch template plus a desired count. Creating a pool spawns desired_count instances; a reconciler converges member_count toward desired_count as it changes. member_count is how many members the pool holds; live_count is how many of them are running. A pool carries two tag sets and they answer different questions. `tags` labels the pool resource — that is what an IAM condition reads as `basalt:ResourceTag/` and what a cost report groups by, and it reaches no instance. `template.tags` is the set stamped on every replica the pool launches. properties: id: type: string format: uuid readOnly: true example: 8f2a1c3d-4e5b-4a6f-9c0d-1e2f3a4b5c6d crn: type: string readOnly: true description: >- Cloud Resource Name. This is the value an IAM policy statement must name to scope a permission to this pool alone; a policy written against anything else will not match. example: >- crn:compute:sa-saopaulo-1:my-account:instance-pool/8f2a1c3d-4e5b-4a6f-9c0d-1e2f3a4b5c6d account_id: type: string format: uuid readOnly: true name: type: string example: web-asg description: type: string example: Front-end autoscaling group flavor_id: type: string format: uuid image_id: type: string format: uuid subnet_id: type: string format: uuid user_data: type: string format: byte desired_count: type: integer minimum: 0 maximum: 100 example: 2 min_count: type: integer minimum: 0 maximum: 100 example: 1 max_count: type: integer minimum: 1 maximum: 100 example: 3 live_count: type: integer readOnly: true description: >- How many members are UP — bound instances in vm_state `running`. This is the number to alert or scale on. It can sit below member_count while a replica boots, and below desired_count on an `active` pool whose members have stopped. example: 2 member_count: type: integer readOnly: true description: >- How many instances the pool holds, running or not. This is what the reconciler converges toward desired_count and what `status` reflects, so member_count == desired_count with live_count below it means the pool has the members it was asked for and some of them are not up. example: 2 refresh_in_progress: type: boolean readOnly: true description: >- True while a rolling replacement requested through POST /v1/instance-pools/{pool_id}/refresh is still running. It clears itself once every member is on the current template. The pool reads `scaling` for the duration, since it runs one instance over its target while a replacement comes up. example: false stale_instance_count: type: integer readOnly: true description: >- How many members were launched from a template other than the pool's current one — that is, how many a refresh would replace. Non-zero after editing `template` and before refreshing, which is the signal that a template change has not been rolled out yet. example: 0 status: type: string enum: - active - scaling - error - deleting readOnly: true description: > Where the pool is against its target. `active` means member_count == desired_count — the pool holds the members it was asked for. It is not a claim that all of them are up; read live_count for that. `scaling` means it does not, and the reconciler is converging it: after a create, after a desired_count change, and for the length of an instance refresh, which runs the pool one instance over its target while a replacement comes up. `error` carries the last failure in error_message and is still reconciled — the pool keeps being retried. `deleting` is a teardown in flight. example: active error_message: type: string readOnly: true description: >- The last failure the reconciler recorded, cleared when the pool reaches its target. Set alongside status `error`, and left in place through a later resize — a pool that failed to spawn and is being scaled again has not yet proved the failure is behind it. managed_by: type: string readOnly: true example: customer security_group_ids: type: array items: type: string format: uuid keypair_names: type: array items: type: string iam_role_id: type: string format: uuid boot_volume_size_gb: type: integer minimum: 1 maximum: 16384 boot_volume_type: type: string enum: - ssd - nvme extra_nics: type: array items: $ref: '#/components/schemas/PoolTemplateNIC' data_volumes: type: array items: $ref: '#/components/schemas/PoolTemplateVolume' assign_public_ip: type: boolean description: >- Each replica gets a floating IP on its PRIMARY NIC, allocated by the reconciler and released on scale-in. Secondary interfaces carry their own flag — read `template.networks[]` or `extra_nics[]` for those. metadata: $ref: '#/components/schemas/Metadata' tags: allOf: - $ref: '#/components/schemas/Tags' description: >- Labels on the POOL itself, for IAM conditions (`basalt:ResourceTag/`) and cost attribution. They are attached to nothing else: no instance the pool launches carries them. The tags a replica is launched with are `template.tags`. Unlike the other top-level fields beside this one, `tags` is not a projection of the launch template — it is the pool's own set, and PATCHable on its own. template: allOf: - $ref: '#/components/schemas/InstancePoolTemplate' readOnly: true description: >- The same launch config as the flat fields above, rendered in instance-create's shape. Both are always emitted and they cannot disagree — this is a projection of the one stored template, not a second copy of it. Read this one; the flat fields are kept for clients written before it existed. 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 NetworkConfig: type: object required: - subnet_id properties: subnet_id: type: string format: uuid description: Subnet to attach the NIC to (required). example: 9b2e4f1a-3c5d-4e6f-8a90-1b2c3d4e5f60 ip_address: type: string description: | Optional fixed IP. Must be in the subnet's CIDR and not currently allocated to another interface. An address is picked automatically when omitted. example: 10.0.1.42 mac: type: string description: | Optional MAC address. Must be locally-administered (`X2:`, `X6:`, `XA:`, `XE:` in the first octet). Generated when omitted. example: 02:1a:2b:3c:4d:5e security_group_ids: type: array items: type: string format: uuid example: c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f description: | Security groups to attach to this NIC at provision time. Each must be owned by the same account. Empty list = no per-NIC ACLs (the platform's default-allow stays in force). assign_public_ip: type: boolean default: false description: | Allocate a floating IP and attach it to THIS interface once it exists. Per NIC, so a secondary interface can carry the public address while the primary stays private, and an instance with several public interfaces gets one address each. Each address is a separate floating-IP allocation: it counts against the account's floating_ips quota and is billed like any other. It is released when the instance is torn down — an address you allocated yourself and attached to the same NIC is not, and survives the instance. The interface's subnet must already route 0.0.0.0/0 to an internet gateway. Without that the address would be silently unreachable, so the launch fails instead. 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. ````