Hubfly spaceDocs
Console

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

  1. Publish to one or more channels. Event data is sent as text; encode JSON yourself.
  2. Send to specific connections or to every connection of a user for direct messages.
  3. Read history for channels whose app has history enabled. Purge removes stored messages.
  4. From your own servers, the Pusher-compatible server API is usually the better fit: see the protocol reference.

Publish an event

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

Open interactive API explorer
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.
  • data is a string (JSON-encode objects). Over the app's message size limit returns 413 MANAGED_REALTIME_PAYLOAD_TOO_LARGE.
  • Event names are 1–200 characters and cannot start with pusher:, pusher_internal: or hubfly:.
  • messageId makes 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 with 403 MANAGED_REALTIME_E2E_REQUIRED.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
eventstringYes
datastringYes
channelsstring[]Yes
excludeSocketIdstringNo
messageIdstringNo
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 response
    Response 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 socketIds or userId, else 400 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, messageId and rate-limit rules as publishing.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
eventstringYes
datastringYes
socketIdsstring[]No
userIdstringNo
messageIdstringNo
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 response
    Response 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).
  • limit defaults to 100 (max 1000); since is an integer offset of 0 or more.
Request parameters
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—
channelqueryYesstring—
sincequeryNonumber—
epochqueryNostring—
limitqueryNonumber—
Responses
  • 200 — Successful response
    Response 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
NameLocationRequiredTypeDescription
projectIdpathYesstring—
instanceIdpathYesstring—
appIdpathYesstring—

JSON request body

FieldType / allowed valuesRequired
channelstringNo
Complete request schema
{
  "type": "object",
  "properties": {
    "channel": {
      "type": "string"
    }
  },
  "required": [],
  "additionalProperties": false
}
Responses
  • 200 — Successful response
    Response 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

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