Hubfly spaceDocs
Console

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

  1. Read the network settings first. Allowlist updates must send the revision you read, so concurrent edits do not overwrite each other.
  2. An empty allowlist with public access on accepts any address over TLS. Add CIDR entries (up to 64) to restrict it.
  3. Bind the instance to a Cell project to write DATABASE_URL (PostgreSQL, MySQL) or LIBSQL_URL and LIBSQL_AUTH_TOKEN (libSQL) into that project.

Bind the database to a Cell project

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

Open interactive API explorer
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) or realtime:admin (realtime servers).
  • revision must equal the current allowlist revision from the network endpoint; otherwise 409 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 operationId and the new revision; poll the instance operation until it ends. The instance must be running or stopped (409 MANAGED_INVALID_STATE).
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
entriesobject[]Yes
revisionnumberYes
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 response
    Response 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) or realtime:read (realtime servers).
  • Pass revision back when replacing the allowlist.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
enabledbooleanYes
Complete request schema
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [
    "enabled"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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:admin on the database and project:edit on 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).
  • envKey uses 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
targetProjectIdstringYes
envKeystringNo
databaseNamestringNo
createUserbooleanNo
accessread_only | read_writeNo
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 response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
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"
                  },
                  "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; also project:edit on the app unless removeVariable=false.
  • Set removeVariable=false to keep the app's variables in place.
  • An unknown connection returns 404 MANAGED_BINDING_NOT_FOUND.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
bindingIdpathYesstring—
removeVariablequeryNoboolean—
Responses
  • 200 — Successful response
    Response 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"
      }
    }

Related guides

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