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"
}
| Field | Required | Description |
|---|---|---|
projectName | Yes | Unique project identifier |
orgId | Yes | Organization ID (used in namespace: {orgId}-{projectName}) |
databaseType | Yes | POSTGRESQL |
tier | Yes | FREE, STANDARD, or ENTERPRISE |
backup | No | Backup configuration |
parameters | No | PostgreSQL parameters |
tags | No | K8s labels applied to the cluster |
postgresVersion | No | e.g. "16", "17" (defaults to operator default) |
password | No | The 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}