Hubfly spaceDocs
Console

Realtime API · Dashboard

App bindings

Write an app's connection settings into 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.

Realtime servers live in a project of type managed; other projects return 409 MANAGED_PROJECT_REQUIRED. Replace :instanceId with the realtime server ID from the instance list. Each endpoint lists the permission it needs; a token scoped to the realtime permissions must hold that exact permission.

How to use these endpoints

  1. Choose the hubfly preset (HUBFLY_REALTIME_URL, HUBFLY_REALTIME_APP_ID, HUBFLY_REALTIME_KEY, HUBFLY_REALTIME_SECRET) or the laravel preset (PUSHER_* and VITE_PUSHER_*).
  2. Set clientPrefix to also write browser-safe copies for your framework, such as NEXT_PUBLIC_ or VITE_. The secret is never given a client prefix.
  3. Redeploy the Cell containers so they read the new variables.

Bind an app to a Next.js project

curl
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/realtime/bindings/create" \
  -H "Authorization: Bearer $HUBFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId":"'"$APP_ID"'","targetProjectId":"'"$CELL_PROJECT_ID"'","preset":"hubfly","clientPrefix":"NEXT_PUBLIC_"}'

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

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

Open interactive API explorer
POSTBind an app to a projectDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/bindings/create

Write an app's connection variables into a Cell project's environment. Preset hubfly (default) writes HUBFLY_REALTIME_URL, HUBFLY_REALTIME_APP_ID, HUBFLY_REALTIME_KEY and HUBFLY_REALTIME_SECRET; preset laravel writes BROADCAST_CONNECTION=pusher, PUSHER_APP_ID, PUSHER_APP_KEY, PUSHER_APP_SECRET, PUSHER_HOST, PUSHER_PORT, PUSHER_SCHEME, PUSHER_APP_CLUSTER and matching VITE_PUSHER_* variables.

  • Requires realtime:admin and project:edit on targetProjectId, which must be a Cell project (409 MANAGED_BINDING_TARGET_UNSUPPORTED).
  • With the hubfly preset, clientPrefix NEXT_PUBLIC_, VITE_ or PUBLIC_ also writes <prefix>HUBFLY_REALTIME_URL and <prefix>HUBFLY_REALTIME_KEY (never the secret).
  • A project holds one binding per preset; binding again replaces the previous one. The secret is stored as a secret variable and is not returned.
  • keyId must be an active key of the app (default the newest): 409 MANAGED_REALTIME_KEY_NOT_ACTIVE. Hubfly space never writes HUBFLY_REALTIME_E2E_KEYS.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
appIdstringYes
targetProjectIdstringYes
presethubfly | laravelNo
clientPrefixnone | NEXT_PUBLIC_ | VITE_ | PUBLIC_No
keyIdstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "appId": {
      "type": "string"
    },
    "targetProjectId": {
      "type": "string"
    },
    "preset": {
      "type": "string",
      "enum": [
        "hubfly",
        "laravel"
      ]
    },
    "clientPrefix": {
      "type": "string",
      "enum": [
        "none",
        "NEXT_PUBLIC_",
        "VITE_",
        "PUBLIC_"
      ]
    },
    "keyId": {
      "type": "string"
    }
  },
  "required": [
    "appId",
    "targetProjectId"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "instanceId": {
              "type": "string"
            },
            "appId": {
              "type": "string"
            },
            "appName": {
              "type": "string"
            },
            "keyId": {
              "type": "string",
              "nullable": true
            },
            "key": {
              "type": "string",
              "nullable": true
            },
            "targetProjectId": {
              "type": "string"
            },
            "targetProjectName": {
              "type": "string"
            },
            "preset": {
              "type": "string",
              "enum": [
                "hubfly",
                "laravel"
              ]
            },
            "clientPrefix": {
              "type": "string",
              "enum": [
                "none",
                "NEXT_PUBLIC_",
                "VITE_",
                "PUBLIC_"
              ]
            },
            "envKeys": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "createdAt": {
              "type": "string",
              "description": "Date string"
            },
            "updatedAt": {
              "type": "string",
              "description": "Date string"
            }
          },
          "required": [
            "id",
            "instanceId",
            "appId",
            "appName",
            "keyId",
            "key",
            "targetProjectId",
            "targetProjectName",
            "preset",
            "clientPrefix",
            "envKeys",
            "createdAt",
            "updatedAt"
          ],
          "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",
        "instanceId": "string",
        "appId": "string",
        "appName": "string",
        "keyId": "string",
        "key": "string",
        "targetProjectId": "string",
        "targetProjectName": "string",
        "preset": "hubfly",
        "clientPrefix": "none",
        "envKeys": [
          "string"
        ],
        "createdAt": "string",
        "updatedAt": "string"
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
GETList app bindingsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/bindings

List the projects this realtime server's apps are bound to, with app, key, preset, client prefix and the variable names each binding wrote. Projects you cannot read appear as "A project you can't access".

  • Requires realtime: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"
                  },
                  "instanceId": {
                    "type": "string"
                  },
                  "appId": {
                    "type": "string"
                  },
                  "appName": {
                    "type": "string"
                  },
                  "keyId": {
                    "type": "string",
                    "nullable": true
                  },
                  "key": {
                    "type": "string",
                    "nullable": true
                  },
                  "targetProjectId": {
                    "type": "string"
                  },
                  "targetProjectName": {
                    "type": "string"
                  },
                  "preset": {
                    "type": "string",
                    "enum": [
                      "hubfly",
                      "laravel"
                    ]
                  },
                  "clientPrefix": {
                    "type": "string",
                    "enum": [
                      "none",
                      "NEXT_PUBLIC_",
                      "VITE_",
                      "PUBLIC_"
                    ]
                  },
                  "envKeys": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "createdAt": {
                    "type": "string",
                    "description": "Date string"
                  },
                  "updatedAt": {
                    "type": "string",
                    "description": "Date string"
                  }
                },
                "required": [
                  "id",
                  "instanceId",
                  "appId",
                  "appName",
                  "keyId",
                  "key",
                  "targetProjectId",
                  "targetProjectName",
                  "preset",
                  "clientPrefix",
                  "envKeys",
                  "createdAt",
                  "updatedAt"
                ],
                "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",
            "instanceId": "string",
            "appId": "string",
            "appName": "string",
            "keyId": "string",
            "key": "string",
            "targetProjectId": "string",
            "targetProjectName": "string",
            "preset": "hubfly",
            "clientPrefix": "none",
            "envKeys": [
              "string"
            ],
            "createdAt": "string",
            "updatedAt": "string"
          }
        ]
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }
DELETERemove an app bindingDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/bindings/:bindingId/delete

Delete a binding and, unless removeVariables is false, remove the variables it wrote that still hold this app's values. Variables you changed or reused are left in place; the response reports variablesRemoved.

  • Requires realtime:admin; removing variables also requires project:edit on the bound project.
  • Unknown binding: 404 MANAGED_BINDING_NOT_FOUND.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
bindingIdpathYesstring—
removeVariablesqueryNoboolean—
Responses
  • 200 — Successful response
    Response schema
    {
      "type": "object",
      "properties": {
        "ok": {
          "const": true,
          "type": "boolean"
        },
        "data": {
          "type": "object",
          "properties": {
            "deleted": {
              "const": true,
              "type": "boolean"
            },
            "variablesRemoved": {
              "type": "number"
            }
          },
          "required": [
            "deleted",
            "variablesRemoved"
          ],
          "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,
        "variablesRemoved": 0
      },
      "meta": {
        "requestId": "string",
        "timestamp": "string"
      }
    }

Related guides

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