Hubfly spaceDocs
Console

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

  1. Read the configuration to get the editable settings and the current generation.
  2. Validate a change, then apply it with the same generation. Choose restart: "now" or "later" for settings that need a restart.
  3. Every applied change is kept in the history and can be reverted.

Read the configuration

curl
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.

Open interactive API explorer
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.
  • generation must be the value from GET .../config; if the configuration changed in the meantime the operation fails with MANAGED_CONFIG_CONFLICT.
  • Send either changes (up to 200 keys) or raw (up to 64 KB), not both. Invalid settings return 400 MANAGED_CONFIG_INVALID with details.errors; no effective change returns 400 MANAGED_CONFIG_UNCHANGED.
  • Asynchronous: returns an operationId and the new revision; poll the instance operation until it ends.
  • SQLite instances return 409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
generationnumberYes
changesobjectNo
rawstringNo
restartnow | laterYes
notestringNo
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 response
    Response 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.
  • limit defaults to 50 and is capped at 200.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
limitqueryNonumber—
Responses
  • 200 — Successful response
    Response 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 generation back when applying or reverting changes.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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.
  • generation must be the current value from GET .../config; a stale value fails the operation with MANAGED_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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
revisionIdstringYes
generationnumberYes
restartnow | laterYes
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 response
    Response 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) or raw (up to 64 KB), not both (400 MANAGED_CONFIG_AMBIGUOUS).
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
changesobjectNo
rawstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "changes": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "nullable": true
      }
    },
    "raw": {
      "type": "string"
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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.
  • database defaults to the instance's default database. Other engines return 409 MANAGED_FEATURE_UNSUPPORTED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
databasequeryNostring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
databasestringNo
namestringYes
Complete request schema
{
  "type": "object",
  "properties": {
    "database": {
      "type": "string"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
extensionNamepathYesstring—
databasequeryNostring—
cascadequeryNoboolean—
Responses
  • 200 — Successful response
    Response 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"
      }
    }

Related guides

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top