Realtime API · Dashboard
Events & history
Publish events to channels, send direct messages to connections or users, and read or purge channel history.
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
- Publish to one or more channels. Event
datais sent as text; encode JSON yourself. - Send to specific connections or to every connection of a user for direct messages.
- Read history for channels whose app has history enabled. Purge removes stored messages.
- From your own servers, the Pusher-compatible server API is usually the better fit: see the protocol reference.
Publish an event
curl -X POST "https://api.hubfly.space/api/v1/projects/$PROJECT_ID/managed/instances/$INSTANCE_ID/realtime/apps/$APP_ID/events/publish" \
-H "Authorization: Bearer $HUBFLY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"channels":["orders"],"event":"order.created","data":"{\"id\":42}"}'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.
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/events/publish | Publish an event |
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/events/send | Send to connections or a user |
| GET | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/history | Read channel history |
| POST | /api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/history/purge | Purge channel history |
POSTPublish an eventDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/events/publish
Publish one event to 1–100 channels of an app, as a server-side Pusher publish would. The app's limits, end-to-end policy, history and webhooks apply; the response has the messageId, history positions per channel and the payload size in bytes.
- Requires
realtime:publish. datais a string (JSON-encode objects). Over the app's message size limit returns413 MANAGED_REALTIME_PAYLOAD_TOO_LARGE.- Event names are 1–200 characters and cannot start with
pusher:,pusher_internal:orhubfly:. messageIdmakes the publish idempotent: repeating it within 5 minutes delivers nothing again.- Shares a per-user budget of 120 requests a minute (
429 RATE_LIMITED); an app that requires end-to-end encryption refuses plaintext with403 MANAGED_REALTIME_E2E_REQUIRED.
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 |
|---|---|---|
event | string | Yes |
data | string | Yes |
channels | string[] | Yes |
excludeSocketId | string | No |
messageId | string | No |
Complete request schema
{
"type": "object",
"properties": {
"event": {
"type": "string"
},
"data": {
"type": "string"
},
"channels": {
"type": "array",
"items": {
"type": "string"
}
},
"excludeSocketId": {
"type": "string"
},
"messageId": {
"type": "string"
}
},
"required": [
"event",
"data",
"channels"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "messageId": { "type": "string" }, "channels": { "type": "object", "additionalProperties": { "type": "object", "properties": { "epoch": { "type": "string", "nullable": true }, "offset": { "type": "number", "nullable": true } }, "required": [ "epoch", "offset" ], "additionalProperties": false } }, "bytes": { "type": "number" } }, "required": [ "messageId", "channels", "bytes" ], "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": { "messageId": "string", "channels": null, "bytes": 0 }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTSend to connections or a userDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/events/send
Send one event directly to 1–100 connections (socketIds) or to every connection of one signed-in user (userId). Each target gets a status of delivered, buffered, queued or offline, summarized in counts.
- Requires
realtime:publish. - Give exactly one of
socketIdsoruserId, else400 MANAGED_REALTIME_INVALID_TARGET. - End-to-end connection IDs (
<socket_id>~<key>) are refused for plaintext events (400 MANAGED_REALTIME_E2E_CONNECTION_ID); send encrypted direct messages from your own server. - Same
data, size,messageIdand rate-limit rules as publishing.
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 |
|---|---|---|
event | string | Yes |
data | string | Yes |
socketIds | string[] | No |
userId | string | No |
messageId | string | No |
Complete request schema
{
"type": "object",
"properties": {
"event": {
"type": "string"
},
"data": {
"type": "string"
},
"socketIds": {
"type": "array",
"items": {
"type": "string"
}
},
"userId": {
"type": "string"
},
"messageId": {
"type": "string"
}
},
"required": [
"event",
"data"
],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "messageId": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "socketId": { "type": "string", "nullable": true }, "userId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "queued", "delivered", "buffered", "offline" ] }, "connections": { "type": "number", "nullable": true } }, "required": [ "socketId", "userId", "status", "connections" ], "additionalProperties": false } }, "counts": { "type": "object", "properties": { "delivered": { "type": "number" }, "buffered": { "type": "number" }, "queued": { "type": "number" }, "offline": { "type": "number" } }, "required": [ "delivered", "buffered", "queued", "offline" ], "additionalProperties": false }, "bytes": { "type": "number" }, "notice": { "type": "string", "nullable": true } }, "required": [ "messageId", "results", "counts", "bytes", "notice" ], "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": { "messageId": "string", "results": [ { "socketId": "string", "userId": "string", "status": "queued", "connections": 0 } ], "counts": { "delivered": 0, "buffered": 0, "queued": 0, "offline": 0 }, "bytes": 0, "notice": "string" }, "meta": { "requestId": "string", "timestamp": "string" } }
GETRead channel historyDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/history
Return a channel's retained messages, either the newest limit or those after offset since, with epoch, head and oldest positions. gap is true when since is older than what is retained or the epoch changed.
- Requires
realtime:publish. - The response contains message payloads and is sent with
cache-control: no-store; each read is recorded in the audit log (without payloads). limitdefaults to 100 (max 1000);sinceis an integer offset of 0 or more.
Request parameters
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
projectId | path | Yes | string | — |
instanceId | path | Yes | string | — |
appId | path | Yes | string | — |
channel | query | Yes | string | — |
since | query | No | number | — |
epoch | query | No | string | — |
limit | query | No | number | — |
Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "channel": { "type": "string" }, "mode": { "type": "string" }, "epoch": { "type": "string", "nullable": true }, "head": { "type": "number", "nullable": true }, "oldest": { "type": "number", "nullable": true }, "messages": { "type": "array", "items": { "type": "object", "properties": { "offset": { "type": "number" }, "event": { "type": "string" }, "data": { "type": "string" }, "messageId": { "type": "string", "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "userId": { "type": "string", "nullable": true }, "size": { "type": "number" } }, "required": [ "offset", "event", "data", "messageId", "publishedAt", "userId", "size" ], "additionalProperties": false } }, "truncated": { "type": "boolean" }, "gap": { "type": "boolean" } }, "required": [ "channel", "mode", "epoch", "head", "oldest", "messages", "truncated", "gap" ], "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": { "channel": "string", "mode": "string", "epoch": "string", "head": 0, "oldest": 0, "messages": [ { "offset": 0, "event": "string", "data": "string", "messageId": "string", "publishedAt": "string", "userId": "string", "size": 0 } ], "truncated": true, "gap": true }, "meta": { "requestId": "string", "timestamp": "string" } }
POSTPurge channel historyDetails +/api/v1/projects/:projectId/managed/instances/:instanceId/realtime/apps/:appId/history/purge
Delete the retained messages of one channel, or of every channel of the app when channel is omitted. Returns the number of messages deleted in purgedMessages.
- Requires
realtime:admin. - 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 | — |
JSON request body
| Field | Type / allowed values | Required |
|---|---|---|
channel | string | No |
Complete request schema
{
"type": "object",
"properties": {
"channel": {
"type": "string"
}
},
"required": [],
"additionalProperties": false
}Responses
200— Successful responseResponse schema
{ "type": "object", "properties": { "ok": { "const": true, "type": "boolean" }, "data": { "type": "object", "properties": { "purgedMessages": { "type": "number" } }, "required": [ "purgedMessages" ], "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": { "purgedMessages": 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