Skip to content

Create database API Reference

POST
/tenants/{tenant}/databases
 
curl --request POST \
  --url https://api.kupe.cloud/api/v1/tenants/acme/databases \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "backup": { "retention": 7, "schedule": "Daily" }, "deletionProtection": true, "engine": "postgres", "highAvailability": false, "name": "orders-db", "resources": { "cpu": "500m", "memory": "1Gi", "storage": "10Gi" }, "version": "18" }'

Create a managed PostgreSQL database. It is provisioned asynchronously: poll the GET endpoint until status.phase is “Running”.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
tenant
required
string

Tenant name

Request Body

Section titled “ Request Body ”

Database configuration

Media type application/json
object
backup

Backup settings. Omit to take the defaults: 7 days, Daily. Refused while the platform does not offer backups.

object
retention

How far back the backups reach, in days: 7 to 35. Default 7.

integer
Example 
7
schedule

How many full backups are kept within the retention period. Daily keeps one for every day. DailyThenWeekly keeps one for each of the last 7 days and one a week before that. The points you can recover to are the same either way; recovering to an older point takes longer. Default Daily.

string
Allowed values: Daily DailyThenWeekly
Example 
Daily
deletionProtection

Must be false before the database can be deleted. Default true.

boolean
Example 
true
engine

Database engine. Only “postgres” is supported; it is also the default.

string
Allowed values: postgres
Example 
postgres
highAvailability

Run two instances with one synchronous standby. Default false.

boolean
Example 
false
name

Database name: a DNS-1035 label (starts with a letter) without “–”. At most 44 characters, and at most 56 minus the length of the tenant name.

string
Example 
orders-db
resources

Per-instance CPU, memory and storage. All three are required.

object
cpu

CPU in cores or millicores, without a unit: “500m”, “2” or “0.5”. At most 20 characters.

string
Example 
500m
memory

Memory with a unit suffix (Ki, Mi, Gi, Ti, Pi, Ei or k, M, G, T, P, E): “1Gi”, “512Mi”. At most 20 characters.

string
Example 
1Gi
storage

Storage with a unit suffix, as for memory: “10Gi”. Grows only. At most 20 characters.

string
Example 
10Gi
version

Engine major version. Omit to take the platform default.

string
Example 
18

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Database created

Media type application/json
object
backup

Backup settings. Null when the database has never set them: it keeps the defaults, 7 days and Daily.

object
retention

How far back the backups reach, in days. Absent when never set: the default, 7, applies.

integer
schedule

How many full backups are kept within the retention period: Daily keeps one for every day, DailyThenWeekly one for each of the last 7 days and one a week before that.

string
Allowed values: Daily DailyThenWeekly
createdAt
string
deletionProtection
boolean
engine
string
generation

Generation increments on every spec change; compare with status.observedGeneration.

integer
highAvailability
boolean
name
string
resourceVersion
string
resources
object
cpu

CPU in cores or millicores, without a unit: “500m”, “2” or “0.5”. At most 20 characters.

string
memory

Memory with a unit suffix (Ki, Mi, Gi, Ti, Pi, Ei or k, M, G, T, P, E): “1Gi”, “512Mi”. At most 20 characters.

string
storage

Storage with a unit suffix, as for memory: “10Gi”. Grows only. At most 20 characters.

string
status
object
backupSizeBytes

Bytes every full backup and all WAL kept for the database take up in storage, manual backups included. 0 until measured.

integer
conditions

Conditions include CredentialsRotating: True (reason RotationPending) while a requested rotation is not yet applied.

Array<object>
object
key
additional properties
currentVersion

CurrentVersion is the full engine version running.

string
instancesDesired
integer
instancesReady
integer
lastBackupAt

When the newest full backup finished (RFC 3339). Empty until the first backup completes.

string
phase
string
Allowed values: Pending Provisioning Running Upgrading Degraded Terminating
previousVersion

PreviousVersion is set while a major upgrade is in progress.

string
recoveryWindow

The oldest and newest points you can recover the database to. Null until the backups report them.

object
earliest

The oldest point you can recover to (RFC 3339).

string
latest

The newest point you can recover to: the newest WAL saved (RFC 3339).

string
rotations

Rotations is the credential rotation state of each role. Wait for a rotation by polling until rotations.{role}.appliedAt equals the requestedAt the rotate-credentials call returned and delivered is true. If requestedAt moves to another token first, a newer rotation replaced it: wait for that one instead.

object
owner
object
appliedAt

AppliedAt is the token of the last rotation the database applied: the new password is in effect in PostgreSQL. The bound credentials Secrets follow it (see Delivered).

string
delivered

Delivered is true once the requested rotation is applied and every binding of the role carries the new password in the credentials Secret of every namespace it lists (true for a role never rotated). The copy into the cluster follows within seconds and is not observed, so a workload restarted the moment this turns true can, rarely, still mount the previous password for a few seconds.

boolean
pending

Pending is true while RequestedAt differs from AppliedAt: the old password still logs in.

boolean
requestedAt

RequestedAt is the token of the last rotation requested; empty if none ever was.

string
readonly
object
appliedAt

AppliedAt is the token of the last rotation the database applied: the new password is in effect in PostgreSQL. The bound credentials Secrets follow it (see Delivered).

string
delivered

Delivered is true once the requested rotation is applied and every binding of the role carries the new password in the credentials Secret of every namespace it lists (true for a role never rotated). The copy into the cluster follows within seconds and is not observed, so a workload restarted the moment this turns true can, rarely, still mount the previous password for a few seconds.

boolean
pending

Pending is true while RequestedAt differs from AppliedAt: the old password still logs in.

boolean
requestedAt

RequestedAt is the token of the last rotation requested; empty if none ever was.

string
readwrite
object
appliedAt

AppliedAt is the token of the last rotation the database applied: the new password is in effect in PostgreSQL. The bound credentials Secrets follow it (see Delivered).

string
delivered

Delivered is true once the requested rotation is applied and every binding of the role carries the new password in the credentials Secret of every namespace it lists (true for a role never rotated). The copy into the cluster follows within seconds and is not observed, so a workload restarted the moment this turns true can, rarely, still mount the previous password for a few seconds.

boolean
pending

Pending is true while RequestedAt differs from AppliedAt: the old password still logs in.

boolean
requestedAt

RequestedAt is the token of the last rotation requested; empty if none ever was.

string
version
string
Example 
{
  "backup": {
    "retention": 7,
    "schedule": "Daily"
  },
  "createdAt": "2026-10-09T10:00:00Z",
  "deletionProtection": true,
  "engine": "postgres",
  "generation": 3,
  "highAvailability": false,
  "name": "orders-db",
  "resourceVersion": "582019",
  "resources": {
    "cpu": "500m",
    "memory": "1Gi",
    "storage": "10Gi"
  },
  "status": {
    "backupSizeBytes": 5368709120,
    "currentVersion": "18.6",
    "instancesDesired": 1,
    "instancesReady": 1,
    "lastBackupAt": "2026-10-21T03:17:00Z",
    "phase": "Pending",
    "previousVersion": "",
    "recoveryWindow": {
      "earliest": "2026-10-14T03:17:00Z",
      "latest": "2026-10-21T09:00:00Z"
    },
    "rotations": {
      "owner": {
        "appliedAt": "2026-10-09T12:00:00.123456789Z",
        "delivered": true,
        "pending": false,
        "requestedAt": "2026-10-09T12:00:00.123456789Z"
      },
      "readonly": {
        "appliedAt": "2026-10-09T12:00:00.123456789Z",
        "delivered": true,
        "pending": false,
        "requestedAt": "2026-10-09T12:00:00.123456789Z"
      },
      "readwrite": {
        "appliedAt": "2026-10-09T12:00:00.123456789Z",
        "delivered": true,
        "pending": false,
        "requestedAt": "2026-10-09T12:00:00.123456789Z"
      }
    }
  },
  "version": "18"
}

Headers

Section titled “ Headers ”
ETag
string

Resource version

400

Section titled “ 400 ”

Validation error, a name too long for the tenant (code DATABASE_NAME_TOO_LONG), a backup retention outside the platform’s range (code DATABASE_BACKUP_RETENTION_OUT_OF_RANGE), backups not offered on this platform (code backups_unavailable), database creation is paused (code creation_paused), or the plan’s database limit is reached (code plan_limit_reached)

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

401

Section titled “ 401 ”

Missing or invalid authentication

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

403

Section titled “ 403 ”

Admin access required

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

404

Section titled “ 404 ”

Databases are not enabled (code databases_unavailable)

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

409

Section titled “ 409 ”

Database name already exists, or the tenant is being deleted (code tenant_terminating), suspended (code tenant_suspended) or awaiting a payment method (code payment_setup_required)

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

429

Section titled “ 429 ”

Rate limit exceeded

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

503

Section titled “ 503 ”

The tenant’s limit is still being set up (a new tenant’s first seconds); retry in a few seconds

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}