Managed databases API
Provision, scale, back up, and restore dedicated managed PostgreSQL databases.
Base path: /v1/workspaces/{workspace_id}/managed-databases
Credentials are stored in Secrets — responses never return raw passwords.
See also: Databases
Create / list
| Method | Path | Permission | Notes |
|---|---|---|---|
POST | /v1/workspaces/{workspace_id}/managed-databases | write | 202 — body: engine (postgresql — the only engine offered; any other engine is 400), name, resource_tier (small|medium — CPU/memory/storage sizing only; single-replica, no HA tier exists yet) |
GET | same | read | List clusters |
Create returns { "managed_database_id": "…", "run_id": "…" }; poll the run to follow progress. resource_tier defaults to small. Once it's ready, a new database gets a daily backup schedule with 30-day retention, where backups are available on the cell.
Each database also has dataplane_status (connected, not_connected, or null while it isn't up) and dataplane_connection_name, the name to pass as connection to the Data Vault API. If it's not_connected, call POST …/{id}/dataplane/register: it returns dataplane_status, dataplane_connection_name and, when it still fails, a short detail. It returns 409 if the database isn't up, and has its own rate limit (10 per minute by default).
Names: 2 to 40 characters, starting with a lowercase letter, then lowercase letters, digits and hyphens, ending with a letter or digit. The names of built-in data connectors (for example postgresql, mongodb, redis) are reserved. Invalid or reserved names return 422.
Errors on create:
| Status | Meaning |
|---|---|
| 400 | Engine isn't offered |
| 409 | Name already in use in the workspace, or the workspace has reached its managed-database quota. The name conflict body has error_code managed_database_name_conflict |
| 422 | Name is invalid or reserved |
| 503 | Managed databases aren't enabled in this environment |
Rate limits (defaults, per client address; 429 when exceeded): create 5 per minute, delete 10, scale 5, backup 5, restore 3, rotate credentials 2.
Get / scale / delete
| Method | Path | Permission | Notes |
|---|---|---|---|
GET | …/{id} | read | |
POST | …/{id}/dataplane/register | write | Retry connecting the database to the data API. 200 with the result |
PATCH | …/{id} | write | 202 — { "resource_tier": "medium" } |
DELETE | …/{id} | delete | 202 — backup_disposition: retain_30d | delete_now |
GET | …/{id}/runs/{run_id} | read | Poll async saga |
Backups and restore
| Method | Path | Permission |
|---|---|---|
POST / GET | …/{id}/backups | write / read |
GET / DELETE | …/{id}/backups/{backup_id} | read / delete |
PUT / GET | …/{id}/backup-schedule | write / read |
POST | …/{id}/restore | write (202) |
An on-demand backup fails straight away with a clear message when backups aren't available on the cell. Backup create takes an optional retention_period, a number followed by d (days) or h (hours), such as 30d or 12h, up to 365 days. Omitting it uses the platform default.
Restore body: backup_id, new_name, optional resource_tier, restore_time (PITR — restore to any timestamp within the retention window; omit to restore the backup as taken).
Retained (orphan) backups:
| Method | Path | Permission |
|---|---|---|
GET | …/retained-backups | read |
POST | …/retained-backups/restore | write (202) |
Rotate credentials
POST /v1/workspaces/{workspace_id}/managed-databases/{id}/rotate-credentialsPermission: write · 202 Accepted