Skip to content
excalibase
api-reference
Provisioningbeta

API Reference

Self-hosting. This page is for operating your own Excalibase install. On Excalibase Cloud the platform runs the provisioner for you: create, back up and restore projects in Studio. The routes below belong to your install's control plane, not to api.excalibase.io.

Base URL: http://localhost:24005/api

Provisioning

List all instances

GET /provision

Returns an array of all provisioned database instances.

Provision a new database

POST /provision
{
  "projectName": "my-db",
  "orgId": "myorg",
  "databaseType": "POSTGRESQL",
  "tier": "STANDARD",
  "backup": { "enabled": true, "schedule": "0 2 * * *", "retention": 30 },
  "parameters": { "shared_preload_libraries": "pg_stat_statements" },
  "tags": { "env": "production", "team": "backend" },
  "postgresVersion": "16",
  "databaseName": "myapp",
  "masterUsername": "admin"
}
FieldRequiredDescription
projectNameYesUnique project identifier
orgIdYesOrganization ID (used in namespace: {orgId}-{projectName})
databaseTypeYesPOSTGRESQL
tierYesFREE, STANDARD, or ENTERPRISE
backupNoBackup configuration
parametersNoPostgreSQL parameters
tagsNoK8s labels applied to the cluster
postgresVersionNoe.g. "16", "17" (defaults to operator default)
passwordNoThe owner password, 16 to 128 characters (same rules as a reset). Leave it out and one is generated. The answer to this call carries it once, in password; no other call returns it.

Get instance status

GET /provision/{projectId}

Get credentials

GET /provision/{projectId}/credentials

Returns the connection details: the database, the user, the SSL mode and a connectionUrl template with <host>, <port> and <password> where those go. It never returns a password, and it carries no cluster-internal address; the project's public endpoint and allowlist come from GET /projects/{projectId}/db-endpoint.

The password is shown once, in the answer to the call that sets it: creating the database or resetting the password. Save it then. To get a new one, reset it (below).

Delete instance

DELETE /provision/{projectId}

Removes the K8s namespace, CRDs, and all stored data. Blocked if deletion protection is enabled.

Cost estimation

POST /provision/estimate
{ "tier": "STANDARD" }

Lifecycle Operations

Scale tier

PATCH /provision/{projectId}/scale
{ "tier": "ENTERPRISE" }

Patches the CNPG Cluster CRD with new instance count and resource limits. Triggers rolling addition of replicas.

Resize storage

POST /provision/{projectId}/resize
{ "newSize": "100Gi" }

Upgrade PostgreSQL version

POST /provision/{projectId}/upgrade
{ "version": "17" }

Patches spec.imageName on the Cluster CRD, triggering a rolling restart.

Update parameters

PATCH /provision/{projectId}/parameters
{ "max_connections": "200", "work_mem": "64MB" }

Patches spec.postgresql.parameters and triggers a rolling restart.

Deletion protection

PATCH /provision/{projectId}/deletion-protection
{ "enabled": true }

Get logs

GET /provision/{projectId}/logs?lines=100

Rotate credentials

POST /provision/{projectId}/credentials/rotate

Resets the owner password and returns the new one once in password; it is never shown again. The body is optional:

{ "password": "a passphrase of at least 16 characters" }

Leave it out and one is generated. A chosen password is 16 to 128 characters, with at least 8 different characters, and cannot start with =, +, - or @. If an earlier reset did not finish, a chosen password is refused (409); reset again without one to complete it.

Clone database

POST /provision/{projectId}/clone
{ "newProjectName": "my-db-clone" }

Creates a new cluster using pg_basebackup from the source.

Maintenance window

PUT /provision/{projectId}/maintenance-window
{ "window": "0 3 * * 0", "durationMinutes": 60, "autoMinorVersionUpgrade": true }
GET /provision/{projectId}/maintenance-window

Backup & Restore

Trigger manual backup

POST /provision/{projectId}/backup/trigger

List backups

GET /provision/{projectId}/backup/list

Restore from backup

POST /provision/{projectId}/backup/restore
{
  "newProjectName": "my-db-restored"
}

Answers a restore job (status: RUNNING); poll GET /provision/{projectId}/backup/restore/{jobId}. The copy carries the source's data, end users, API permissions, tracked functions, CORS origins, auth settings and migration history; see what the copy carries.

Point-in-time recovery (PITR)

POST /provision/{projectId}/backup/restore
{
  "newProjectName": "my-db-pitr",
  "targetTime": "2026-03-19T12:00:00Z"
}

Metrics

Current metrics

GET /provision/{projectId}/metrics/current

Returns real-time metrics from CNPG port 9187 + metrics-server CPU/memory. diskUsagePercent, diskUsageGB, diskUsedBytes and diskSizeBytes are the data volume of the fullest instance, as df reads it inside the database container (Postgres and MySQL on Kubernetes); they are null when the volume cannot be read.

Metrics history

GET /provision/{projectId}/metrics/history?limit=30

Metrics SSE stream

GET /provision/{projectId}/metrics/stream

Server-Sent Events stream, emits every 5 seconds.

Performance

Summary

GET /provision/{projectId}/performance/summary

Top queries

GET /provision/{projectId}/performance/top-queries?limit=10

Wait events

GET /provision/{projectId}/performance/wait-events

Enable pg_stat_statements

POST /provision/{projectId}/performance/enable

Audit

Enable pgaudit

POST /provision/{projectId}/audit/enable

Get audit logs

GET /provision/{projectId}/audit/logs?lines=100

Get audit config

GET /provision/{projectId}/audit/config

Snapshots

Export snapshot

POST /provision/{projectId}/snapshot/export
{ "format": "custom", "schemaOnly": false }

List snapshots

GET /provision/{projectId}/snapshot

Download snapshot

GET /provision/{projectId}/snapshot/{snapshotId}/download

Delete snapshot

DELETE /provision/{projectId}/snapshot/{snapshotId}

Migrations

Apply migration

POST /provision/{projectId}/migrations
{ "version": "001", "name": "create_users", "sql": "CREATE TABLE users (id serial PRIMARY KEY, name text)" }

List migrations

GET /provision/{projectId}/migrations

Alerts

Active alerts

GET /alerts

Alert history

GET /alerts/history?limit=100

Alerts for project

GET /alerts/project/{projectId}

Setup

Operator status

GET /setup/status

Install operator

POST /setup/install/{databaseType}

Parameter Groups

CRUD

GET    /parameter-groups
POST   /parameter-groups
GET    /parameter-groups/{name}
PUT    /parameter-groups/{name}
DELETE /parameter-groups/{name}