Realtime API · Dashboard
Channels & connections
List occupied channels, inspect a channel and its members, find connections, and disconnect a connection or a user.
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
- List channels by prefix and page through them with
cursor. - Find connections by user, channel or connection ID.
- Disconnect a single connection or every connection of a user, for example after revoking access.
List channels
curl "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/realtime/apps/$APP_ID/channels?prefix=presence-&limit=50" \
-H "Authorization: Bearer $HUBFLY_TOKEN"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 (5)
These JSON routes are served by the Hubfly space Dashboard API and use Dashboard project authorization.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/channels | List occupied channels |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/channels/inspect | Inspect a channel |
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/connections/terminate | Close a connection |
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/users/terminate | Sign out a user everywhere |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/connections | List live connections |
GETList occupied channelsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/channels
List an app's currently occupied channels, ordered by name, with type, subscription count and presence user count. Filter by name prefix and page with cursor.
- Requires
realtime:read. limitdefaults to 100 (max 1000);prefixis at most 200 channel-name characters.- The server must be running:
409 MANAGED_INSTANCE_NOT_RUNNING.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
prefix | query | No | string | — |
limit | query | No | number | — |
cursor | query | No | 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": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "public", "private", "presence", "encrypted" ] }, "subscriptionCount": { "type": "number" }, "userCount": { "type": "number", "nullable": true }, "occupiedAt": { "type": "string", "nullable": true } }, "required": [ "name", "type", "subscriptionCount", "userCount", "occupiedAt" ], "additionalProperties": false } }, "nextCursor": { "type": "string", "nullable": true }, "total": { "type": "number", "nullable": true } }, "required": [ "items", "nextCursor", "total" ], "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": [ { "name": "string", "type": "user", "subscriptionCount": 0, "userCount": 0, "occupiedAt": "string" } ], "nextCursor": "string", "total": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
GETInspect a channelDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/channels/inspect
Return one channel's occupancy, presence members with their userInfo, history position and cached event. membersLimit caps the member list and membersTruncated tells you when more exist.
- Requires
realtime:publish. membersLimitdefaults to 100 (max 1000).- The server must be running:
409 MANAGED_INSTANCE_NOT_RUNNING.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
channel | query | Yes | string | — |
membersLimit | query | No | number | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "public", "private", "presence", "encrypted" ] }, "occupied": { "type": "boolean" }, "subscriptionCount": { "type": "number" }, "userCount": { "type": "number", "nullable": true }, "members": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "userInfo": { "type": "string", "nullable": true }, "connections": { "type": "number" } }, "required": [ "userId", "userInfo", "connections" ], "additionalProperties": false } }, "membersTruncated": { "type": "boolean" }, "history": { "type": "object", "properties": { "mode": { "type": "string" }, "epoch": { "type": "string", "nullable": true }, "head": { "type": "number", "nullable": true }, "oldest": { "type": "number", "nullable": true }, "retainedMessages": { "type": "number" }, "retainedBytes": { "type": "number" } }, "required": [ "mode", "epoch", "head", "oldest", "retainedMessages", "retainedBytes" ], "additionalProperties": false, "nullable": true }, "cache": { "type": "object", "properties": { "present": { "type": "boolean" }, "event": { "type": "string", "nullable": true }, "cachedAt": { "type": "string", "nullable": true } }, "required": [ "present", "event", "cachedAt" ], "additionalProperties": false, "nullable": true } }, "required": [ "name", "type", "occupied", "subscriptionCount", "userCount", "members", "membersTruncated", "history", "cache" ], "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": { "name": "string", "type": "user", "occupied": true, "subscriptionCount": 0, "userCount": 0, "members": [ { "userId": "string", "userInfo": "string", "connections": 0 } ], "membersTruncated": true, "history": { "mode": "string", "epoch": "string", "head": 0, "oldest": 0, "retainedMessages": 0, "retainedBytes": 0 }, "cache": { "present": true, "event": "string", "cachedAt": "string" } }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTClose a connectionDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/connections/terminate
Close one connection of an app by socketId. mode terminate (default) closes with 4009 so the client stops; disconnect closes with 4200 so the client reconnects and resumes at once.
- Requires
realtime:admin. - A connection that is no longer open returns
404 MANAGED_REALTIME_CONNECTION_NOT_FOUND. socketIdlooks like1234567890.1234567890; anything else returns400 MANAGED_REALTIME_INVALID_SOCKET.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
socketId | string | Yes |
mode | terminate | disconnect | No |
Complete request schema
{
"type": "object",
"properties": {
"socketId": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"terminate",
"disconnect"
]
}
},
"required": [
"socketId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "terminated": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "terminate", "disconnect" ] } }, "required": [ "terminated", "mode" ], "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": { "terminated": true, "mode": "terminate" }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTSign out a user everywhereDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/users/terminate
Close every connection and detached session of one signed-in user of an app with close code 4009. Returns the number of connections closed in terminated.
- Requires
realtime:admin. userIdis 1–128 characters froma-z A-Z 0-9 -_=@,.;.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
userId | string | Yes |
Complete request schema
{
"type": "object",
"properties": {
"userId": {
"type": "string"
}
},
"required": [
"userId"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "terminated": { "type": "number" } }, "required": [ "terminated" ], "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": { "terminated": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
GETList live connectionsDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/connections
List live and detached connections on the server with socket ID, app, signed-in user, protocol, client library, IP, origin, subscriptions (first 20) and message counters. Filter by appId, userId, channel or one connectionId.
- Requires
realtime:publish. - Filtering by
userIdorchannelneeds anappId:400 MANAGED_REALTIME_INVALID_FILTER. limitdefaults to 100 (max 1000); page withcursorandnextCursor.- An end-to-end connection ID is accepted, but only its socket ID part is used.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | query | No | string | — |
userId | query | No | string | — |
channel | query | No | string | — |
connectionId | query | No | string | — |
limit | query | No | number | — |
cursor | query | No | 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": { "socketId": { "type": "string" }, "appId": { "type": "string" }, "userId": { "type": "string", "nullable": true }, "protocol": { "type": "string", "enum": [ "hubfly", "pusher" ] }, "client": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "version": { "type": "string", "nullable": true } }, "required": [ "name", "version" ], "additionalProperties": false }, "ip": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true }, "state": { "type": "string", "enum": [ "connected", "detached" ] }, "connectedAt": { "type": "string", "nullable": true }, "subscriptionCount": { "type": "number" }, "subscriptions": { "type": "array", "items": { "type": "string" } }, "messagesIn": { "type": "number" }, "messagesOut": { "type": "number" }, "bytesIn": { "type": "number" }, "bytesOut": { "type": "number" } }, "required": [ "socketId", "appId", "userId", "protocol", "client", "ip", "origin", "state", "connectedAt", "subscriptionCount", "subscriptions", "messagesIn", "messagesOut", "bytesIn", "bytesOut" ], "additionalProperties": false } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "items", "nextCursor" ], "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": [ { "socketId": "string", "appId": "string", "userId": "string", "protocol": "hubfly", "client": { "name": "string", "version": "string" }, "ip": "string", "origin": "string", "state": "connected", "connectedAt": "string", "subscriptionCount": 0, "subscriptions": [ "string" ], "messagesIn": 0, "messagesOut": 0, "bytesIn": 0, "bytesOut": 0 } ], "nextCursor": "string" }, "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