Skip to main content
POST
Restore a backup into this cluster, in place

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

  • <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):

  • 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:

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)

Step 4 — signature

Example (POST with a JSON body)

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

​
cluster_id
string<uuid>
required

Body

application/json

Restore a backup INTO THIS CLUSTER, overwriting its data. Destructive and irreversible.

A pre-restore backup is taken automatically before anything is overwritten, so there is a way back from a mistaken restore.

​
backup_id
string<uuid>
required

The backup to restore. May be a backup of THIS cluster (the common "undo a bad migration" case) or of another cluster in the same account, in which case this cluster is granted read on that backup bucket for the duration and it is revoked afterwards. Must satisfy the same rules as a create-time restore — see restore_from.backup_id.

Example:

"3c4d5e6f-7081-4293-a4b5-c6d7e8f9a0b1"

​
confirm
string
required

Must equal the cluster's name. Restoring overwrites live data and cannot be undone, so consent has to be something that cannot arrive by accident — a retried request, a stale tab, a script looping over ids.

Example:

"prod-orders-db"

​
recovery_target_time
string<date-time>

RFC3339 timestamp for point-in-time recovery — WAL is replayed forward from the backup until this time, then stops.

Example:

"2026-01-15T08:00:00Z"

Response

Restore accepted; the pre-restore backup has been requested.

​
cluster
object