Hubfly spaceDocs
Console

Managed Databases API · Dashboard

SQL & data browser

Dashboard API reference for running SQL, reading a database schema, and paging through or changing table rows in Hubfly space Managed Databases.

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. Send readOnly: true for queries that only read; they run as a role that cannot write. With readOnly: false statements run as the admin user. Both need database:query.
  2. Bound results with maxRows and timeoutMs; large exports belong in the export endpoints.
  3. Read the schema before browsing or editing rows of a table.

Run a read-only query

curl
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/query" \
  -H "Authorization: Bearer $HUBFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"database":"app","sql":"select now()","readOnly":true,"maxRows":100}'

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 (4)

These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.

Open interactive API explorer
POSTRun SQLDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/query

Runs one or more SQL statements against the database and returns each statement's columns, rows, row count, duration and any error, plus server notices. Read-only requests run as a role that cannot write; with readOnly: false statements run as the admin user.

  • Requires database:query.
  • sql is limited to 100 KB. maxRows defaults to 500 (max 5000) and timeoutMs to 30000 (1000-60000); results over maxRows or 2 MB are marked truncated, and a result that still does not fit returns 413 MANAGED_OUTPUT_LIMIT.
  • Limited to 120 console requests a minute per user (429 RATE_LIMITED).
  • Results are sent with cache-control: no-store. The audit log records only that a query ran, not its text.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
databasestringNo
sqlstringYes
readOnlybooleanYes
maxRowsnumberNo
timeoutMsnumberNo
Complete request schema
{
  "type": "object",
  "properties": {
    "database": {
      "type": "string"
    },
    "sql": {
      "type": "string"
    },
    "readOnly": {
      "type": "boolean"
    },
    "maxRows": {
      "type": "number"
    },
    "timeoutMs": {
      "type": "number"
    }
  },
  "required": [
    "sql",
    "readOnly"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "readOnly": {
              "type": "boolean"
            },
            "durationMs": {
              "type": "number"
            },
            "statements": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "index": {
                    "type": "number"
                  },
                  "command": {
                    "type": "string",
                    "nullable": true
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "error",
                      "ok"
                    ]
                  },
                  "columns": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "number",
                            "boolean",
                            "json",
                            "other",
                            "text",
                            "binary",
                            "datetime"
                          ]
                        }
                      },
                      "required": [
                        "name",
                        "type",
                        "kind"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "rows": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "nullable": true
                      }
                    }
                  },
                  "rowCount": {
                    "type": "number",
                    "nullable": true
                  },
                  "truncated": {
                    "type": "boolean"
                  },
                  "durationMs": {
                    "type": "number"
                  },
                  "error": {
                    "type": "object",
                    "properties": {
                      "message": {
                        "type": "string"
                      },
                      "code": {
                        "type": "string",
                        "nullable": true
                      },
                      "position": {
                        "type": "number",
                        "nullable": true
                      },
                      "detail": {
                        "type": "string",
                        "nullable": true
                      },
                      "hint": {
                        "type": "string",
                        "nullable": true
                      }
                    },
                    "required": [
                      "message",
                      "code",
                      "position",
                      "detail",
                      "hint"
                    ],
                    "additionalProperties": false,
                    "nullable": true
                  }
                },
                "required": [
                  "index",
                  "command",
                  "status",
                  "columns",
                  "rows",
                  "rowCount",
                  "truncated",
                  "durationMs",
                  "error"
                ],
                "additionalProperties": false
              }
            },
            "notices": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "severity": {
                    "type": "string"
                  },
                  "code": {
                    "type": "string",
                    "nullable": true
                  },
                  "message": {
                    "type": "string"
                  }
                },
                "required": [
                  "severity",
                  "code",
                  "message"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "readOnly",
            "durationMs",
            "statements",
            "notices"
          ],
          "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": {
        "readOnly": true,
        "durationMs": 0,
        "statements": [
          {
            "index": 0,
            "command": "string",
            "status": "error",
            "columns": [
              {
                "name": "string",
                "type": "string",
                "kind": "number"
              }
            ],
            "rows": [
              [
                "string"
              ]
            ],
            "rowCount": 0,
            "truncated": true,
            "durationMs": 0,
            "error": {
              "message": "string",
              "code": "string",
              "position": 0,
              "detail": "string",
              "hint": "string"
            }
          }
        ],
        "notices": [
          {
            "severity": "string",
            "code": "string",
            "message": "string"
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETRead the database schemaDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/schema

Returns the schemas, tables, views and columns of one database (the default database unless database is set), with row estimates, sizes, column types, nullability, primary keys and defaults. truncated is true when the database has more than 2000 tables.

  • Requires database:read.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
databasequeryNostring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "database": {
              "type": "string"
            },
            "truncated": {
              "type": "boolean"
            },
            "schemas": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "tables": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "table",
                            "view",
                            "materialized_view"
                          ]
                        },
                        "rowEstimate": {
                          "type": "number",
                          "nullable": true
                        },
                        "sizeBytes": {
                          "type": "number",
                          "nullable": true
                        },
                        "columns": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string"
                              },
                              "nullable": {
                                "type": "boolean"
                              },
                              "primaryKey": {
                                "type": "boolean"
                              },
                              "defaultValue": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "name",
                              "type",
                              "nullable",
                              "primaryKey",
                              "defaultValue"
                            ],
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "name",
                        "kind",
                        "rowEstimate",
                        "sizeBytes",
                        "columns"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "name",
                  "tables"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "database",
            "truncated",
            "schemas"
          ],
          "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": {
        "database": "string",
        "truncated": true,
        "schemas": [
          {
            "name": "string",
            "tables": [
              {
                "name": "string",
                "kind": "table",
                "rowEstimate": 0,
                "sizeBytes": 0,
                "columns": [
                  {
                    "name": "string",
                    "type": "string",
                    "nullable": true,
                    "primaryKey": true,
                    "defaultValue": "string"
                  }
                ]
              }
            ]
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
POSTInsert, update or delete rowsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/tables/rows/change

Changes rows in one table: insert adds a row from values, update changes the row identified by key, and delete removes the rows identified by keys. Returns the number of rows affected.

  • Requires database:query.
  • update needs key; delete needs 1-500 keys (400 MANAGED_ROW_KEY_REQUIRED). Only tables with a primary key can be edited (409 MANAGED_NO_PRIMARY_KEY).
  • Values are sent as strings or null. Limited to 120 console requests a minute per user.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
databasestringNo
schemastringYes
tablestringYes
actionupdate | delete | insertYes
valuesobjectNo
keyobjectNo
keysobject[]No
Complete request schema
{
  "type": "object",
  "properties": {
    "database": {
      "type": "string"
    },
    "schema": {
      "type": "string"
    },
    "table": {
      "type": "string"
    },
    "action": {
      "type": "string",
      "enum": [
        "update",
        "delete",
        "insert"
      ]
    },
    "values": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "nullable": true
      }
    },
    "key": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "nullable": true
      }
    },
    "keys": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {
          "type": "string",
          "nullable": true
        }
      }
    }
  },
  "required": [
    "schema",
    "table",
    "action"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "affected": {
              "type": "number"
            }
          },
          "required": [
            "affected"
          ],
          "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": {
        "affected": 0
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETBrowse table rowsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/tables/rows

Returns one page of rows from a table or view with column details, the primary key, whether more rows follow and whether the table can be edited. Supports ordering by one column and one filter.

  • Requires database:query.
  • limit defaults to 100 (max 500). filterOp is one of eq, neq, lt, lte, gt, gte, like, ilike, is_null, not_null; other values are ignored.
  • Limited to 120 console requests a minute per user; the response is sent with cache-control: no-store.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
databasequeryNostring—
schemaqueryYesstring—
tablequeryYesstring—
limitqueryNonumber—
offsetqueryNonumber—
orderByqueryNostring—
orderDirectionqueryNostring—
filterColumnqueryNostring—
filterOpqueryNostring—
filterValuequeryNostring—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "columns": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "number",
                      "boolean",
                      "json",
                      "other",
                      "text",
                      "binary",
                      "datetime"
                    ]
                  },
                  "nullable": {
                    "type": "boolean"
                  },
                  "primaryKey": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "name",
                  "type",
                  "kind",
                  "nullable",
                  "primaryKey"
                ],
                "additionalProperties": false
              }
            },
            "rows": {
              "type": "array",
              "items": {
                "type": "array",
                "items": {
                  "type": "string",
                  "nullable": true
                }
              }
            },
            "primaryKey": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "hasMore": {
              "type": "boolean"
            },
            "editable": {
              "type": "boolean"
            }
          },
          "required": [
            "columns",
            "rows",
            "primaryKey",
            "hasMore",
            "editable"
          ],
          "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": {
        "columns": [
          {
            "name": "string",
            "type": "string",
            "kind": "number",
            "nullable": true,
            "primaryKey": true
          }
        ],
        "rows": [
          [
            "string"
          ]
        ],
        "primaryKey": [
          "string"
        ],
        "hasMore": true,
        "editable": true
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }

Related guides

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