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
- Choose the
hubflypreset (HUBFLY_REALTIME_URL,HUBFLY_REALTIME_APP_ID,HUBFLY_REALTIME_KEY,HUBFLY_REALTIME_SECRET) or thelaravelpreset (PUSHER_*andVITE_PUSHER_*). - Set
clientPrefixto also write browser-safe copies for your framework, such asNEXT_PUBLIC_orVITE_. The secret is never given a client prefix. - Redeploy the Cell containers so they read the new variables.
Bind an app to a Next.js project
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.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/bindings/create | Bind an app to a project |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/bindings | List app bindings |
| DELETE | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/bindings/:bindingId/delete | Remove an app binding |
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:adminandproject:editontargetProjectId, which must be a Cell project (409 MANAGED_BINDING_TARGET_UNSUPPORTED). - With the
hubflypreset,clientPrefixNEXT_PUBLIC_,VITE_orPUBLIC_also writes<prefix>HUBFLY_REALTIME_URLand<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.
keyIdmust be an active key of the app (default the newest):409 MANAGED_REALTIME_KEY_NOT_ACTIVE. Hubfly space never writesHUBFLY_REALTIME_E2E_KEYS.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
appId | string | Yes |
targetProjectId | string | Yes |
preset | hubfly | laravel | No |
clientPrefix | none | NEXT_PUBLIC_ | VITE_ | PUBLIC_ | No |
keyId | string | No |
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 responseResponse 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
| 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" }, "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 requiresproject:editon the bound project. - Unknown binding:
404 MANAGED_BINDING_NOT_FOUND.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
bindingId | path | Yes | string | — |
removeVariables | 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" }, "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
- Realtime overview and workflows
- Realtime protocol reference (WebSocket, server API and webhooks)
- All Realtime API sections
- Dashboard errors and status codes