> ## 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 database cluster ## OpenAPI ````yaml /api-reference/specs/database.yaml post /v1/clusters openapi: 3.0.3 info: title: Basaltic Database API version: 1.0.0 description: | Managed database clusters — provision an engine, convert a single node to high availability, fail over between members and restore from a backup. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://database.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] paths: /v1/clusters: post: tags: - Database summary: Create a database cluster operationId: createCluster parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateClusterRequest' responses: '202': description: Accepted — cluster provisioning started content: application/json: schema: $ref: '#/components/schemas/ClusterResponse' '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: CreateClusterRequest: type: object required: - name - engine_type - flavor_id - storage_gb - networks properties: name: type: string example: prod-orders-db description: type: string example: Primary orders database engine_type: type: string enum: - postgres - valkey example: postgres engine_version: type: string description: >- e.g. '17' for postgres. Defaults to the engine's current default when omitted. example: '17' flavor_id: type: string format: uuid description: >- Compute flavor each cluster member runs on. Must be a database-family flavor. example: e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1 storage_gb: type: integer minimum: 1 example: 100 instance_count: type: integer minimum: 1 default: 1 description: > Node count. Postgres: 1 = single-node; 2+ adds Patroni HA members (max 10). Valkey: 1 = single-node; 3 = primary + replicas with Sentinel (2 is rejected; max 3). example: 1 admin_user: type: string description: Optional; defaults to "admin". Postgres-safe identifier only. pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ example: admin default_database: type: string description: Optional; defaults to "default". Postgres-safe identifier only. pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ example: default key_names: type: array description: >- Platform-operator break-glass only. Stamps SSH keypairs onto the cluster's managed VMs, which run the platform's own software; a tenant reaches its database over the cluster endpoint, never over SSH. Accepted only from the platform account and only with `database:StampBreakGlassKeys` — any other account setting it is rejected with 400 `INVALID_INPUT`. items: type: string parameter_group_id: type: string format: uuid description: > Binds the cluster to a parameter group whose settings its members boot with and converge to. Omitted means engine defaults. The group must match the cluster's engine type and major version. example: 1a2b3c4d-5e6f-4071-8293-a4b5c6d7e8f9 assign_public_ip: type: boolean default: true description: > Endpoint exposure. True (the default) allocates a floating IP per endpoint, and requires the cluster's subnet to carry a default route (0.0.0.0/0) to an internet gateway — a public cluster on a subnet without one is rejected before anything is provisioned. False allocates no floating IP: endpoints resolve to member addresses inside the VPC, which is how a cluster is placed on a private subnet. IPv6 reachability is unaffected either way — it follows the subnet's ::/0 route, as it does for every other resource. example: true networks: type: array minItems: 1 description: At least one network interface is required. items: $ref: '#/components/schemas/NICRequest' metadata: $ref: '#/components/schemas/Metadata' tags: $ref: '#/components/schemas/Tags' restore_from: $ref: '#/components/schemas/RestoreFrom' ClusterResponse: type: object properties: cluster: $ref: '#/components/schemas/Cluster' NICRequest: type: object description: A network interface attachment for the cluster's members. required: - subnet_id properties: subnet_id: type: string format: uuid example: d4e5f6a7-b8c9-4012-d3e4-f5a6b7c8d9e0 ip_address: type: string description: Optional fixed IP; auto-allocated from the subnet when omitted. example: 192.168.1.50 mac: type: string description: Optional fixed MAC; auto-generated when omitted. example: fa:16:3e:4f:5a:2b security_group_ids: type: array items: type: string format: uuid example: - d1b6f3a8-4c2e-4a9d-8f7b-1e5c3a2d9b4f Metadata: type: object additionalProperties: type: string example: environment: production team: backend Tags: type: object additionalProperties: type: string example: environment: production team: backend RestoreFrom: type: object description: | Bootstrap the new cluster from an existing backup instead of a fresh initdb. The source backup must belong to the same account and be in status=succeeded. Single-node only in the current pass. required: - backup_id properties: backup_id: type: string format: uuid description: > Any succeeded backup of the source cluster whose `restorable` is true. A backup with `restorable: false` predates the platform recording pgbackrest labels, so it can only be restored while it is the source cluster's most recent succeeded backup, and is refused otherwise — pgbackrest would silently restore the newest instead. example: 3c4d5e6f-7081-4293-a4b5-c6d7e8f9a0b1 recovery_target_time: type: string format: date-time description: | RFC3339 timestamp for point-in-time recovery — pgbackrest replays WAL forward from the base backup until this time, then stops. Empty = restore to the latest available WAL. example: '2026-01-15T08:00:00Z' Cluster: type: object required: - id - crn - name - engine_type - engine_version - flavor_id - storage_gb - instance_count - assign_public_ip - status - tags - created_at - updated_at properties: id: type: string format: uuid example: 9b2e4c7a-1f3d-4a8e-bc25-6d0f1a2b3c4d crn: type: string description: IAM resource CRN example: >- crn:database:sa-saopaulo-1:my-account:cluster/9b2e4c7a-1f3d-4a8e-bc25-6d0f1a2b3c4d name: type: string example: prod-orders-db description: type: string example: Primary orders database engine_type: type: string enum: - postgres - valkey example: postgres engine_version: type: string description: e.g. '17' for postgres example: '17' flavor_id: type: string format: uuid description: >- Compute flavor each cluster member runs on. Must be a database-family flavor. example: e5f6a7b8-c9d0-4123-e4f5-a6b7c8d9e0f1 storage_gb: type: integer minimum: 1 example: 100 instance_count: type: integer minimum: 1 description: > Node count. Postgres: 1 = single-node; 2+ adds Patroni HA members (max 10). Valkey: 1 = single-node; 3 = primary + replicas with Sentinel (2 is rejected; max 3). Does not guarantee a completed failover drill for every topology. example: 1 assign_public_ip: type: boolean description: > Whether the cluster's endpoints are backed by floating IPs and reachable from the internet. False means every endpoint resolves to a member's in-VPC address and the cluster is reachable only from the VPC. example: true patroni_managed: type: boolean description: > Whether postgres here runs under Patroni. Not the same question as instance_count >= 2: a cluster converted from single-node is Patroni-managed with one member — able to take a replica, not yet HA. Adding a replica requires this, not the node count. example: false parameter_group_id: type: string format: uuid example: 1a2b3c4d-5e6f-4071-8293-a4b5c6d7e8f9 status: type: string description: > Lifecycle status of the cluster. `converting` is a single-node postgres cluster being adopted into Patroni — the node restarts under a new supervisor, so replica adds, failovers and further conversions are refused while it holds. `restoring` is a cluster whose data is being overwritten in place: it is neither active nor building, and must not be read as serving current data. enum: - pending - building - active - modifying - converting - restoring - failing-over - deleting - deleted - error example: active fault: $ref: '#/components/schemas/Fault' endpoints: type: array items: $ref: '#/components/schemas/Endpoint' instances: type: array items: $ref: '#/components/schemas/Instance' admin_user: type: string description: Bootstrap admin/superuser role name. pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ example: admin admin_secret_id: type: string format: uuid description: secrets service id holding the admin password. example: 2b3c4d5e-6f70-4182-93a4-b5c6d7e8f9a0 default_database: type: string pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$ example: default metadata: $ref: '#/components/schemas/Metadata' 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' deleted_at: type: string format: date-time example: '2026-01-16T09: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 Fault: type: object description: Error detail attached to a resource in status=error. required: - code - message - at properties: code: type: string example: provision_failed message: type: string example: compute instance failed to boot details: type: string example: quota exceeded in subnet at: type: string format: date-time example: '2026-01-15T09:31:00Z' Endpoint: type: object description: One writer/reader/admin connection endpoint for a cluster. required: - id - kind - dns_name - port properties: id: type: string format: uuid example: a7b8c9d0-e1f2-4345-a6b7-c8d9e0f1a2b3 kind: type: string description: Which role this endpoint targets. enum: - writer - reader - admin example: writer floating_ip_id: type: string format: uuid description: > The endpoint's public floating IP. Absent on clusters created with assign_public_ip=false, whose endpoints resolve to a member's in-VPC address instead. Connect by dns_name in both cases. example: f6a7b8c9-d0e1-4234-f5a6-b7c8d9e0f1a2 ip_address: type: string description: > The address `dns_name` currently answers with — the floating IP on a public endpoint, or the serving member's in-VPC address on a private one. Absent while it cannot be resolved, e.g. an endpoint whose member is still provisioning. It is resolved per request and a private endpoint's changes on failover, so connect by `dns_name` and use this for the things a name cannot express, such as a security-group rule. example: 203.0.113.50 dns_name: type: string example: orders-db.my-account.db.sa-saopaulo-1.basaltic.sh port: type: integer minimum: 1 maximum: 65535 example: 5432 Instance: type: object description: One VM-shaped member of a cluster. required: - id - role - status properties: id: type: string format: uuid example: b8c9d0e1-f2a3-4456-b7c8-d9e0f1a2b3c4 member_name: type: string description: >- Cluster member name — pass as failover target_member to promote this node. example: dbaas-b8c9d0e1-0 compute_instance_id: type: string format: uuid example: c9d0e1f2-a3b4-4567-c8d9-e0f1a2b3c4d5 boot_volume_id: type: string format: uuid example: d0e1f2a3-b4c5-4678-d9e0-f1a2b3c4d5e6 role: type: string description: Member role within the cluster. enum: - primary - replica example: primary status: type: string example: running agent_version: type: string description: > Version of the in-VM management agent this member reported in its last heartbeat. Absent when the member has not reported one — it has not beat yet, or it runs an agent released before the field existed. Absent means unknown: never assume it matches another member's. example: 1.7.12-1 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. ````