Managed Databases API · Dashboard
Config & extensions
Read, validate, apply and revert engine settings, and install PostgreSQL extensions.
Base URL: https://api.hubfly.space. Use a Dashboard bearer token authorized for the project. Replace :projectId in each path with the Dashboard project ID. JSON routes use Content-Type: application/json.
Database instances live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the database instance ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the database permissions must hold that exact permission.
How to use these endpoints
- Read the configuration to get the editable settings and the current
generation. - Validate a change, then apply it with the same
generation. Chooserestart: "now"or"later"for settings that need a restart. - Every applied change is kept in the history and can be reverted.
Read the configuration
curl "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/config" \
-H "Authorization: Bearer $HUBFLY_TOKEN"The response uses the standard Dashboard envelope: ok, data, and meta on success. On failure, use the returned error code and message to decide whether to correct the request or retry. The exact schema and response codes for each operation are below.
Endpoint reference
Dashboard endpoints (8)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/config/apply | Apply configuration changes |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/config/history | List configuration revisions |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/config | Read engine configuration |
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/config/revert | Revert to a configuration revision |
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/config/validate | Validate configuration changes |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/extensions | List PostgreSQL extensions |
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/extensions/install | Install a PostgreSQL extension |
| DELETE | /api/v1/projects/:projectId/managed/instances/:instanceId/extensions/:extensionName/delete | Remove a PostgreSQL extension |
POSTApply configuration changesDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/config/apply
Validates and applies engine settings to a PostgreSQL or MySQL database, either as individual changes (set a value or null to reset it) or as the full raw file, and records a new revision. Settings that need a restart wait for one unless restart is now.
- Requires
database:admin. generationmust be the value fromGET .../config; if the configuration changed in the meantime the operation fails withMANAGED_CONFIG_CONFLICT.- Send either
changes(up to 200 keys) orraw(up to 64 KB), not both. Invalid settings return400 MANAGED_CONFIG_INVALIDwithdetails.errors; no effective change returns400 MANAGED_CONFIG_UNCHANGED. - Asynchronous: returns an
operationIdand the new revision; poll the instance operation until it ends. - SQLite instances return
409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
generation | number | Yes |
changes | object | No |
raw | string | No |
restart | now | later | Yes |
note | string | No |
Complete request schema
{
"type": "object",
"properties": {
"generation": {
"type": "number"
},
"changes": {
"type": "object",
"additionalProperties": {
"type": "string",
"nullable": true
}
},
"raw": {
"type": "string"
},
"restart": {
"type": "string",
"enum": [
"now",
"later"
]
},
"note": {
"type": "string"
}
},
"required": [
"generation",
"restart"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "revisionId": { "type": "string" }, "revisionNumber": { "type": "number" }, "operationId": { "type": "string" }, "restartRequired": { "type": "array", "items": { "type": "string" } } }, "required": [ "revisionId", "revisionNumber", "operationId", "restartRequired" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "revisionId": "string", "revisionNumber": 0, "operationId": "string", "restartRequired": [ "string" ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList configuration revisionsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/config/history
Lists the database's configuration revisions, newest first, each with its number, state, note, the settings it changed and who made it.
- Requires
database:read. limitdefaults to 50 and is capped at 200.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
limit | query | No | number | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "number" }, "state": { "type": "string" }, "note": { "type": "string", "nullable": true }, "diff": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "from": { "type": "string", "nullable": true }, "to": { "type": "string", "nullable": true }, "restartRequired": { "type": "boolean" } }, "required": [ "key", "from", "to", "restartRequired" ], "additionalProperties": false } }, "actor": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "id", "name" ], "additionalProperties": false, "nullable": true }, "createdAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "number", "state", "note", "diff", "actor", "createdAt" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "items": [ { "id": "string", "number": 0, "state": "string", "note": "string", "diff": [ { "key": "string", "from": "string", "to": "string", "restartRequired": true } ], "actor": { "id": "string", "name": "string" }, "createdAt": "string" } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead engine configurationDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/config
Returns the database's current engine settings with their values, defaults, types, limits, descriptions and whether each is editable or needs a restart, plus the raw configuration file and the current generation.
- Requires
database:read. - Available for PostgreSQL and MySQL; SQLite returns
409 MANAGED_FEATURE_UNSUPPORTED. - Pass
generationback when applying or reverting changes.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "generation": { "type": "number" }, "lastGoodGeneration": { "type": "number" }, "pendingRestart": { "type": "array", "items": { "type": "string" } }, "rawFormat": { "type": "string", "enum": [ "postgresql_conf", "mysql_cnf" ] }, "raw": { "type": "string" }, "settings": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string", "nullable": true }, "defaultValue": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "string", "boolean", "duration", "bytes", "integer", "real", "enum" ] }, "unit": { "type": "string", "nullable": true }, "min": { "type": "string", "nullable": true }, "max": { "type": "string", "nullable": true }, "enumValues": { "type": "array", "items": { "type": "string" }, "nullable": true }, "category": { "type": "string" }, "description": { "type": "string", "nullable": true }, "restartRequired": { "type": "boolean" }, "locked": { "type": "boolean" }, "editable": { "type": "boolean" }, "modified": { "type": "boolean" } }, "required": [ "key", "value", "defaultValue", "type", "unit", "min", "max", "enumValues", "category", "description", "restartRequired", "locked", "editable", "modified" ], "additionalProperties": false } }, "revisionNumber": { "type": "number", "nullable": true } }, "required": [ "generation", "lastGoodGeneration", "pendingRestart", "rawFormat", "raw", "settings", "revisionNumber" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "generation": 0, "lastGoodGeneration": 0, "pendingRestart": [ "string" ], "rawFormat": "postgresql_conf", "raw": "string", "settings": [ { "key": "string", "value": "string", "defaultValue": "string", "type": "string", "unit": "string", "min": "string", "max": "string", "enumValues": [ "string" ], "category": "string", "description": "string", "restartRequired": true, "locked": true, "editable": true, "modified": true } ], "revisionNumber": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTRevert to a configuration revisionDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/config/revert
Applies the configuration file saved with an earlier revision as a new revision. Settings that need a restart wait for one unless restart is now.
- Requires
database:admin. generationmust be the current value fromGET .../config; a stale value fails the operation withMANAGED_CONFIG_CONFLICT.- Asynchronous: returns an
operationId; poll the instance operation until it ends. - An unknown revision returns
404 MANAGED_CONFIG_REVISION_NOT_FOUND.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
revisionId | string | Yes |
generation | number | Yes |
restart | now | later | Yes |
Complete request schema
{
"type": "object",
"properties": {
"revisionId": {
"type": "string"
},
"generation": {
"type": "number"
},
"restart": {
"type": "string",
"enum": [
"now",
"later"
]
}
},
"required": [
"revisionId",
"generation",
"restart"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "revisionId": { "type": "string" }, "revisionNumber": { "type": "number" }, "operationId": { "type": "string" }, "restartRequired": { "type": "array", "items": { "type": "string" } } }, "required": [ "revisionId", "revisionNumber", "operationId", "restartRequired" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "revisionId": "string", "revisionNumber": 0, "operationId": "string", "restartRequired": [ "string" ] }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTValidate configuration changesDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/config/validate
Checks proposed settings or a full configuration file without applying them. Returns whether they are valid, errors and warnings, the resulting file, a diff and the settings that would need a restart.
- Requires
database:admin. - Send either
changes(up to 200 keys) orraw(up to 64 KB), not both (400 MANAGED_CONFIG_AMBIGUOUS).
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
changes | object | No |
raw | string | No |
Complete request schema
{
"type": "object",
"properties": {
"changes": {
"type": "object",
"additionalProperties": {
"type": "string",
"nullable": true
}
},
"raw": {
"type": "string"
}
},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "nullable": true }, "line": { "type": "number", "nullable": true }, "message": { "type": "string" } }, "required": [ "key", "line", "message" ], "additionalProperties": false } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "nullable": true }, "line": { "type": "number", "nullable": true }, "message": { "type": "string" } }, "required": [ "key", "line", "message" ], "additionalProperties": false } }, "restartRequired": { "type": "array", "items": { "type": "string" } }, "raw": { "type": "string" }, "diff": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "from": { "type": "string", "nullable": true }, "to": { "type": "string", "nullable": true }, "restartRequired": { "type": "boolean" } }, "required": [ "key", "from", "to", "restartRequired" ], "additionalProperties": false } } }, "required": [ "valid", "errors", "warnings", "restartRequired", "raw", "diff" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "valid": true, "errors": [ { "key": "string", "line": 0, "message": "string" } ], "warnings": [ { "key": "string", "line": 0, "message": "string" } ], "restartRequired": [ "string" ], "raw": "string", "diff": [ { "key": "string", "from": "string", "to": "string", "restartRequired": true } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList PostgreSQL extensionsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/extensions
Lists the extensions available in a PostgreSQL database with installed and default versions, a description and whether Hubfly space allows installing them.
- Requires
database:read. databasedefaults to the instance's default database. Other engines return409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
database | query | No | string | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "installedVersion": { "type": "string", "nullable": true }, "defaultVersion": { "type": "string", "nullable": true }, "allowed": { "type": "boolean" }, "description": { "type": "string", "nullable": true } }, "required": [ "name", "installedVersion", "defaultVersion", "allowed", "description" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "items": [ { "name": "string", "installedVersion": "string", "defaultVersion": "string", "allowed": true, "description": "string" } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTInstall a PostgreSQL extensionDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/extensions/install
Installs an extension into a PostgreSQL database (the default database unless database is set). Only extensions listed as allowed can be installed.
- Requires
database:admin. - Other engines return
409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
database | string | No |
name | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"database": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "name": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETERemove a PostgreSQL extensionDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/extensions/:extensionName/delete
Drops an extension from a PostgreSQL database (the default database unless database is set). With cascade=true objects that depend on it are dropped as well.
- Requires
database:admin. - Other engines return
409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
extensionName | path | Yes | string | — |
database | query | No | string | — |
cascade | query | No | boolean | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "dropped": { "type": "boolean" } }, "required": [ "dropped" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "requestId", "timestamp" ], "additionalProperties": false } }, "required": [ "ok", "data", "meta" ], "additionalProperties": false }Example response
{ "ok": true, "data": { "dropped": true }, "meta": { "requestId": "string", "timestamp": "string" } }