The Realtime API is implemented via Server-Sent Events (SSE). Generally, it consists of 2 operations:

  1. establish SSE connection
  2. submit client subscriptions

SSE events are sent for create, update and delete record operations.

You could subscribe to a single record or to an entire collection.

When you subscribe to a single record, the collection's ViewRule will be used to determine whether the subscriber has access to receive the event message.

When you subscribe to an entire collection, the collection's ListRule will be used to determine whether the subscriber has access to receive the event message.

GET
/api/realtime

Establishes a new SSE connection and immediately sends a PB_CONNECT SSE event with the created client ID.

NB! The user/superuser authorization happens during the first Set subscriptions call.

If the connected client doesn't receive any new messages for 5 minutes, the server will send a disconnect signal (this is to prevent forgotten/leaked connections). The connection will be automatically reestablished if the client is still active (e.g. the browser tab is still open).

POST
/api/realtime

Sets new active client's subscriptions (and auto unsubscribes from the previous ones).

If Authorization header is set, will authorize the client SSE connection with the associated user or superuser.

Body Parameters
Param Type Description
Required clientId
String ID of the SSE client connection.
Optional subscriptions
{"Array"}

The new client subscriptions to set in the format:
COLLECTION_ID_OR_NAME or COLLECTION_ID_OR_NAME/RECORD_ID.

You can also attach optional query and header parameters as serialized json to a single topic using the options query parameter, e.g.:

Leave empty to unsubscribe from everything.
Body parameters could be sent as JSON or multipart/form-data.
Responses
{#each responses as response (response.code)} {/each}
{#each responses as response (response.code)}
{/each}

All of this is seamlessly handled by the SDKs using just the subscribe and unsubscribe methods: