Hubfly spaceDocs
Console

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

  1. List channels by prefix and page through them with cursor.
  2. Find connections by user, channel or connection ID.
  3. Disconnect a single connection or every connection of a user, for example after revoking access.

List channels

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

Open interactive API explorer
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.
  • limit defaults to 100 (max 1000); prefix is at most 200 channel-name characters.
  • The server must be running: 409 MANAGED_INSTANCE_NOT_RUNNING.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
prefixqueryNostring—
limitqueryNonumber—
cursorqueryNostring—
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": {
                  "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.
  • membersLimit defaults to 100 (max 1000).
  • The server must be running: 409 MANAGED_INSTANCE_NOT_RUNNING.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
channelqueryYesstring—
membersLimitqueryNonumber—
Responses
  • 200 — Successful response
    Response 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.
  • socketId looks like 1234567890.1234567890; anything else returns 400 MANAGED_REALTIME_INVALID_SOCKET.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
socketIdstringYes
modeterminate | disconnectNo
Complete request schema
{
  "type": "object",
  "properties": {
    "socketId": {
      "type": "string"
    },
    "mode": {
      "type": "string",
      "enum": [
        "terminate",
        "disconnect"
      ]
    }
  },
  "required": [
    "socketId"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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.
  • userId is 1–128 characters from a-z A-Z 0-9 -_=@,.;.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
userIdstringYes
Complete request schema
{
  "type": "object",
  "properties": {
    "userId": {
      "type": "string"
    }
  },
  "required": [
    "userId"
  ],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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 userId or channel needs an appId: 400 MANAGED_REALTIME_INVALID_FILTER.
  • limit defaults to 100 (max 1000); page with cursor and nextCursor.
  • An end-to-end connection ID is accepted, but only its socket ID part is used.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdqueryNostring—
userIdqueryNostring—
channelqueryNostring—
connectionIdqueryNostring—
limitqueryNonumber—
cursorqueryNostring—
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": {
                  "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

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