Managed Databases API · Dashboard
Network & bindings
Turn public access on or off, edit the IP allowlist, and bind the database to a Cell project as environment variables.
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 network settings first. Allowlist updates must send the
revisionyou read, so concurrent edits do not overwrite each other. - An empty allowlist with public access on accepts any address over TLS. Add CIDR entries (up to 64) to restrict it.
- Bind the instance to a Cell project to write
DATABASE_URL(PostgreSQL, MySQL) orLIBSQL_URLandLIBSQL_AUTH_TOKEN(libSQL) into that project.
Bind the database to a Cell project
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/bindings/create" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"targetProjectId":"'"$CELL_PROJECT_ID"'","envKey":"DATABASE_URL","createUser":true,"access":"read_write"}'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 (6)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
| Method | Path | Purpose |
|---|---|---|
| PUT | /api/v1/projects/:projectId/managed/instances/:instanceId/network/allowlist/update | Replace the IP allowlist |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/network | Read network settings |
| PUT | /api/v1/projects/:projectId/managed/instances/:instanceId/network/public-access/update | Turn public access on or off |
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/bindings/create | Connect a database to an app |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/bindings | List connected apps |
| DELETE | /api/v1/projects/:projectId/managed/instances/:instanceId/bindings/:bindingId/delete | Disconnect an app |
PUTReplace the IP allowlistDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/network/allowlist/update
Replaces the instance's IP allowlist with the given CIDR ranges. An empty list opens the instance to every address. On a realtime server the allowlist restricts only the server API; WebSocket clients are never IP-restricted.
- Requires
database:admin(databases) orrealtime:admin(realtime servers). revisionmust equal the current allowlist revision from the network endpoint; otherwise409 MANAGED_ALLOWLIST_CONFLICT.- Up to 64 entries; labels are cut to 64 characters. Invalid or duplicate ranges return
400 MANAGED_INVALID_ALLOWLIST. - Asynchronous: returns an
operationIdand the newrevision; poll the instance operation until it ends. The instance must be running or stopped (409 MANAGED_INVALID_STATE).
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
entries | object[] | Yes |
revision | number | Yes |
Complete request schema
{
"type": "object",
"properties": {
"entries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"cidr": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"cidr"
],
"additionalProperties": false
}
},
"revision": {
"type": "number"
}
},
"required": [
"entries",
"revision"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" }, "revision": { "type": "number" }, "entries": { "type": "number" } }, "required": [ "operationId", "revision", "entries" ], "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": { "operationId": "string", "revision": 0, "entries": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead network settingsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/network
Returns the instance's endpoint host and port, whether public access is on, the IP allowlist with its revision, whether allowlists are supported for this instance and what the allowlist restricts. TLS is always required.
- Requires
database:read(databases) orrealtime:read(realtime servers). - Pass
revisionback when replacing the allowlist.
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": { "publicAccess": { "type": "boolean" }, "endpoint": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "number", "nullable": true } }, "required": [ "host", "port" ], "additionalProperties": false }, "allowlist": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "cidr", "label", "createdAt" ], "additionalProperties": false } }, "openToAll": { "type": "boolean" }, "revision": { "type": "number" }, "tlsRequired": { "const": true, "type": "boolean" }, "allowlistSupported": { "type": "boolean" }, "maxEntries": { "type": "number" }, "allowlistScope": { "type": "string", "enum": [ "connections", "server_api" ] }, "publicAccessEditable": { "type": "boolean" } }, "required": [ "publicAccess", "endpoint", "allowlist", "openToAll", "revision", "tlsRequired", "allowlistSupported", "maxEntries", "allowlistScope", "publicAccessEditable" ], "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": { "publicAccess": true, "endpoint": { "host": "string", "port": 0 }, "allowlist": [ { "cidr": "string", "label": "string", "createdAt": "string" } ], "openToAll": true, "revision": 0, "tlsRequired": true, "allowlistSupported": true, "maxEntries": 0, "allowlistScope": "connections", "publicAccessEditable": true }, "meta": { "requestId": "string", "timestamp": "string" } }
PUTTurn public access on or offDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/network/public-access/update
Allows or blocks connections to a database from the internet. Realtime servers are always public and refuse this call with 409 MANAGED_FEATURE_UNSUPPORTED.
- Requires
database:admin. - Asynchronous: returns an
operationId; poll the instance operation until it ends. - Sending the current value returns
400 MANAGED_NETWORK_UNCHANGED. The instance must be running or stopped (409 MANAGED_INVALID_STATE).
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
enabled | boolean | Yes |
Complete request schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
}
},
"required": [
"enabled"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "operationId": { "type": "string" }, "publicAccess": { "type": "boolean" } }, "required": [ "operationId", "publicAccess" ], "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": { "operationId": "string", "publicAccess": true }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTConnect a database to an appDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/bindings/create
Writes the database's connection URL into an environment variable of a Cell project (DATABASE_URL by default, LIBSQL_URL plus LIBSQL_AUTH_TOKEN for SQLite). The URL uses the admin user, or a new dedicated user when createUser is true; for SQLite a new access token is created. Connecting the same app and variable again replaces the earlier connection.
- Requires
database:adminon the database andproject:editon the target project. - The target must be a Cell project (
409 MANAGED_BINDING_TARGET_UNSUPPORTED) and the database must be running (409 MANAGED_INSTANCE_NOT_RUNNING). envKeyuses up to 128 uppercase letters, numbers and underscores and cannot start with a number (400 MANAGED_INVALID_ENV_KEY).access: "read_only"applies to dedicated users and SQLite tokens. The response never contains the password or token.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
targetProjectId | string | Yes |
envKey | string | No |
databaseName | string | No |
createUser | boolean | No |
access | read_only | read_write | No |
Complete request schema
{
"type": "object",
"properties": {
"targetProjectId": {
"type": "string"
},
"envKey": {
"type": "string"
},
"databaseName": {
"type": "string"
},
"createUser": {
"type": "boolean"
},
"access": {
"type": "string",
"enum": [
"read_only",
"read_write"
]
}
},
"required": [
"targetProjectId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "targetProjectId": { "type": "string" }, "targetProjectName": { "type": "string" }, "envKey": { "type": "string" }, "authTokenEnvKey": { "type": "string", "nullable": true }, "databaseName": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true }, "dedicatedUser": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "targetProjectId", "targetProjectName", "envKey", "authTokenEnvKey", "databaseName", "username", "dedicatedUser", "createdAt" ], "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": { "id": "string", "targetProjectId": "string", "targetProjectName": "string", "envKey": "string", "authTokenEnvKey": "string", "databaseName": "string", "username": "string", "dedicatedUser": true, "createdAt": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList connected appsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/bindings
Lists the apps connected to this database, newest first, with the target project, variable names, database name, username and whether a dedicated user was created. No secrets are returned.
- Requires
database:admin.
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": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "targetProjectId": { "type": "string" }, "targetProjectName": { "type": "string" }, "envKey": { "type": "string" }, "authTokenEnvKey": { "type": "string", "nullable": true }, "databaseName": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true }, "dedicatedUser": { "type": "boolean" }, "createdAt": { "type": "string", "description": "Date string" } }, "required": [ "id", "targetProjectId", "targetProjectName", "envKey", "authTokenEnvKey", "databaseName", "username", "dedicatedUser", "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", "targetProjectId": "string", "targetProjectName": "string", "envKey": "string", "authTokenEnvKey": "string", "databaseName": "string", "username": "string", "dedicatedUser": true, "createdAt": "string" } ] }, "meta": { "requestId": "string", "timestamp": "string" } }
DELETEDisconnect an appDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/bindings/:bindingId/delete
Removes the connection between the database and an app. By default the variables it wrote are removed from the app as well, and a dedicated user created for it is dropped.
- Requires
database:admin; alsoproject:editon the app unlessremoveVariable=false. - Set
removeVariable=falseto keep the app's variables in place. - An unknown connection returns
404 MANAGED_BINDING_NOT_FOUND.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
bindingId | path | Yes | string | — |
removeVariable | query | No | boolean | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "const": true, "type": "boolean" } }, "required": [ "deleted" ], "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": { "deleted": true }, "meta": { "requestId": "string", "timestamp": "string" } }