Realtime API

The Realtime area publishes 28 REST endpoints. Paths are relative to https://api.lessly.com; see Authentication for the required header.

GET/realtime/archive

Read a channel's durably archived history from Postgres (survives the Redis hot window). Offset-paginated: pass the returned next_offset as after_offset for the next page.

MCP tool: realtime_archive_get

Parameters

Name	In	Type	Required	Description
`channel`	query	`string`	•	Channel whose archived history to read
`after_offset`	query	`string`	—	Return entries strictly after this offset (from a previous page)
`limit`	query	`integer`	—	—

Response

Returns object.

Field	Type	Always	Description
`channel`	`string`	•	—
`entries`	`object[]`	•	—
`next_offset`	`string \| null`	•	Pass as after_offset to fetch the next page; null = no more entries

POST/realtime/archive/exports

Start an async NDJSON export of a channel's archived history to the product bucket. Returns an export id; poll realtime_archive_export_status until done.

MCP tool: realtime_archive_export

Parameters

Name	In	Type	Required	Description
`channel`	body	`string`	•	Channel whose archive to export
`from_ts`	body	`integer`	—	Only entries with ts >= from_ts (epoch ms)
`to_ts`	body	`integer`	—	Only entries with ts <= to_ts (epoch ms)

Response

Returns object.

Field	Type	Always	Description
`status`	`string`one of: pending, done, failed	•	—
`export_id`	`string (uuid)`	•	—

GET/realtime/archive/exports/:export_id

Check an archive export: status, and the NDJSON blob reference once done

MCP tool: realtime_archive_export_status

Parameters

Name	In	Type	Required	Description
`export_id`	path	`string (uuid)`	•	Export id returned by realtime_archive_export

Response

Returns object.

Field	Type	Always	Description
`ref`	`object \| null`	•	Blob reference of the NDJSON export once status is "done"
`error`	`string \| null`	•	—
`status`	`string`one of: pending, done, failed	•	—
`export_id`	`string (uuid)`	•	—
`entry_count`	`integer \| null`	•	—

GET/realtime/grants

List realtime channel grants for this product, optionally filtered by subject

MCP tool: realtime_grant_list

Parameters

Name	In	Type	Required	Description
`subject`	query	`string`	—	Filter grants by subject

Response

Returns object.

Field	Type	Always	Description
`grants`	`object[]`	•	—

POST/realtime/grants

Grant a subject (identity id or "*" for all identities) operations on channels matching a pattern; "*" in a pattern matches exactly one segment

MCP tool: realtime_grant_create

Parameters

Name	In	Type	Required	Description
`subject`	body	`string`	•	Identity id the grant applies to, or "*" for every identity in the product
`pattern`	body	`string`	•	Channel pattern, e.g. "chat:" ("" matches exactly one segment)
`ops`	body	`string[]`one of: subscribe, publish, presence, history	•	Operations granted on matching channels

Response

Returns object.

Field	Type	Always	Description
`id`	`string (uuid)`	•	—
`ops`	`string[]`one of: subscribe, publish, presence, history	•	—
`pattern`	`string`	•	—
`subject`	`string`	•	—
`createdAt`	`string`	•	—

DELETE/realtime/grants/:id

Revoke a realtime channel grant by id

MCP tool: realtime_grant_revoke

Parameters

Name	In	Type	Required	Description
`id`	path	`string (uuid)`	•	Grant id to revoke

Response

Returns object.

Field	Type	Always	Description
`revoked`	`boolean`one of: true	•	—

POST/realtime/messages

Publish a JSON message to a realtime channel of the current product

MCP tool: realtime_messages_publish

Parameters

Name	In	Type	Required	Description
`channel`	body	`string`	•	Channel to publish the message to
`data`	body	`string`	•	JSON payload delivered to channel subscribers

Response

Returns object.

Field	Type	Always	Description
`epoch`	`string`	—	Stream epoch of the stored message (present when history is on)
`offset`	`string`	—	Stream offset of the stored message (present when history is on)
`channel`	`string`	•	Channel the message was published to
`published`	`boolean`one of: true	•	Publish acknowledged by the fan-out backend

GET/realtime/messages/history

Read message history of a realtime channel: either a cursor (offset + epoch, replays strictly after the offset; recovered:false on epoch mismatch or aged-out entries) or a window (last_n / last_ms). Conceptually requires the `history` capability; in Phase 1 this surface is Identity-authenticated management access.

MCP tool: realtime_history_get

Parameters

Name	In	Type	Required	Description
`channel`	query	`string`	•	Channel to read history from
`offset`	query	`string`	—	Cursor: resume strictly after this offset (requires epoch)
`epoch`	query	`string`	—	Cursor: stream epoch the offset belongs to
`last_n`	query	`integer`	—	Window: return the last N entries
`last_ms`	query	`integer`	—	Window: return entries newer than now minus this many milliseconds

Response

Returns object.

Field	Type	Always	Description
`epoch`	`string \| null`	•	Current stream epoch, or null when the channel has no history yet
`channel`	`string`	•	Channel the history was read from
`entries`	`object[]`	•	Entries in stream order
`recovered`	`boolean`	•	false when the cursor epoch mismatches or entries aged out — client must resync

GET/realtime/namespaces

List all realtime namespaces registered for this product

MCP tool: realtime_namespace_list

Parameters

No parameters.

Response

Returns object.

Field	Type	Always	Description
`namespaces`	`object[]`	•	—

POST/realtime/namespaces

Register a realtime namespace (the part of a channel name before the first colon) with its policy: visibility, presence, client events, history, encryption, identified-only

MCP tool: realtime_namespace_create

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	•	Namespace name (the part of a channel name before the first colon)
`visibility`	body	`string`one of: public, authorized	—	public: any authenticated identity may subscribe without a grant
`presence`	body	`boolean`	—	Whether presence is enabled on channels in this namespace
`clientEvents`	body	`boolean`	—	Whether clients may publish events directly
`history`	body	`string`one of: none, last-message, window	—	History retention policy for channels in this namespace
`historyWindowSeconds`	body	`integer`	—	Retention window in seconds; required when history is "window"
`encryptionRequired`	body	`boolean`	—	Whether payloads must be end-to-end encrypted
`identifiedOnly`	body	`boolean`	—	Whether only identified (non-anonymous) identities get capabilities
`subscribeProxyUrl`	body	`string (uri) \| null`	—	If set, token mint consults this URL per requested channel (fail-closed); null disables
`archive`	body	`string \| object`one of: off	—	History archive policy: off, or durably retain archived entries for N days (requires history != "none")

Response

Returns object.

Field	Type	Always	Description
`id`	`string (uuid)`	•	—
`name`	`string`	•	—
`archive`	`string \| object`one of: off	•	History archive policy
`history`	`string`one of: none, last-message, window	•	—
`presence`	`boolean`	•	—
`createdAt`	`string`	•	—
`updatedAt`	`string`	•	—
`visibility`	`string`one of: public, authorized	•	—
`clientEvents`	`boolean`	•	—
`identifiedOnly`	`boolean`	•	—
`subscribeProxyUrl`	`string \| null`	•	—
`encryptionRequired`	`boolean`	•	—
`historyWindowSeconds`	`integer \| null`	•	—
`subscribeProxySecret`	`string`	—	Full proxy signing secret — returned ONLY when subscribeProxyUrl is set/changed
`subscribeProxySecretPrefix`	`string \| null`	•	Visible prefix of the proxy signing secret; null when no proxy url is set

DELETE/realtime/namespaces/:name

Delete a realtime namespace by name (grants on it stop resolving)

MCP tool: realtime_namespace_delete

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	•	Namespace name

Response

Returns object.

Field	Type	Always	Description
`deleted`	`boolean`one of: true	•	—

GET/realtime/namespaces/:name

Get a realtime namespace and its policy by name

MCP tool: realtime_namespace_get

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	•	Namespace name

Response

Returns object.

Field	Type	Always	Description
`id`	`string (uuid)`	•	—
`name`	`string`	•	—
`archive`	`string \| object`one of: off	•	History archive policy
`history`	`string`one of: none, last-message, window	•	—
`presence`	`boolean`	•	—
`createdAt`	`string`	•	—
`updatedAt`	`string`	•	—
`visibility`	`string`one of: public, authorized	•	—
`clientEvents`	`boolean`	•	—
`identifiedOnly`	`boolean`	•	—
`subscribeProxyUrl`	`string \| null`	•	—
`encryptionRequired`	`boolean`	•	—
`historyWindowSeconds`	`integer \| null`	•	—
`subscribeProxySecret`	`string`	—	Full proxy signing secret — returned ONLY when subscribeProxyUrl is set/changed
`subscribeProxySecretPrefix`	`string \| null`	•	Visible prefix of the proxy signing secret; null when no proxy url is set

PATCH/realtime/namespaces/:name

Update the policy of a realtime namespace

MCP tool: realtime_namespace_update

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	•	Namespace name to update
`visibility`	body	`string`one of: public, authorized	—	public: any authenticated identity may subscribe without a grant
`presence`	body	`boolean`	—	Whether presence is enabled on channels in this namespace
`clientEvents`	body	`boolean`	—	Whether clients may publish events directly
`history`	body	`string`one of: none, last-message, window	—	History retention policy for channels in this namespace
`historyWindowSeconds`	body	`integer`	—	Retention window in seconds; required when history is "window"
`encryptionRequired`	body	`boolean`	—	Whether payloads must be end-to-end encrypted
`identifiedOnly`	body	`boolean`	—	Whether only identified (non-anonymous) identities get capabilities
`subscribeProxyUrl`	body	`string (uri) \| null`	—	If set, token mint consults this URL per requested channel (fail-closed); null disables
`archive`	body	`string \| object`one of: off	—	History archive policy: off, or durably retain archived entries for N days (requires history != "none")

Response

Returns object.

Field	Type	Always	Description
`id`	`string (uuid)`	•	—
`name`	`string`	•	—
`archive`	`string \| object`one of: off	•	History archive policy
`history`	`string`one of: none, last-message, window	•	—
`presence`	`boolean`	•	—
`createdAt`	`string`	•	—
`updatedAt`	`string`	•	—
`visibility`	`string`one of: public, authorized	•	—
`clientEvents`	`boolean`	•	—
`identifiedOnly`	`boolean`	•	—
`subscribeProxyUrl`	`string \| null`	•	—
`encryptionRequired`	`boolean`	•	—
`historyWindowSeconds`	`integer \| null`	•	—
`subscribeProxySecret`	`string`	—	Full proxy signing secret — returned ONLY when subscribeProxyUrl is set/changed
`subscribeProxySecretPrefix`	`string \| null`	•	Visible prefix of the proxy signing secret; null when no proxy url is set

GET/realtime/presence

Get the current presence roster for a channel. Roster is deduplicated by identity (connections counts live sockets); a per-connection view is deferred — the store is identity-keyed.

MCP tool: realtime_presence_get

Parameters

Name	In	Type	Required	Description
`channel`	query	`string`	•	Channel name, "namespace:rest"

Response

Returns object.

Field	Type	Always	Description
`channel`	`string`	•	Channel name
`members`	`object[]`	•	Current roster, deduplicated by identity

POST/realtime/presence/enter

Enter presence on a realtime channel; upserts the caller (or member_id) into the roster

MCP tool: realtime_presence_enter

Parameters

Name	In	Type	Required	Description
`channel`	body	`string`	•	Channel name, "namespace:rest"
`info`	body	`string`	—	Arbitrary JSON metadata for the member (<=10KB serialized)
`ttl_seconds`	body	`integer`	—	Presence entry TTL in seconds (1-3600)
`member_id`	body	`string`	—	Act for a synthetic member id instead of the caller identity (backend integrations)

Response

Returns object.

Field	Type	Always	Description
`member`	`object`	•	The entered/updated member
`channel`	`string`	•	Channel name

POST/realtime/presence/leave

Leave presence on a realtime channel, removing the caller (or member_id) from the roster

MCP tool: realtime_presence_leave

Parameters

Name	In	Type	Required	Description
`channel`	body	`string`	•	Channel name, "namespace:rest"
`member_id`	body	`string`	—	Act for a synthetic member id instead of the caller identity (backend integrations)

Response

Returns object.

Field	Type	Always	Description
`channel`	`string`	•	Channel name
`removed`	`boolean`	•	Whether the member was removed

GET/realtime/presence/stats

Get the presence member count for a channel

MCP tool: realtime_presence_stats

Parameters

Name	In	Type	Required	Description
`channel`	query	`string`	•	Channel name, "namespace:rest"

Response

Returns object.

Field	Type	Always	Description
`channel`	`string`	•	Channel name
`members`	`integer`	•	Number of distinct identities present

POST/realtime/presence/update

Update a presence member's info and/or refresh its TTL

MCP tool: realtime_presence_update

Parameters

Name	In	Type	Required	Description
`channel`	body	`string`	•	Channel name, "namespace:rest"
`info`	body	`string`	—	Arbitrary JSON metadata for the member (<=10KB serialized)
`ttl_seconds`	body	`integer`	—	Presence entry TTL in seconds (1-3600)
`member_id`	body	`string`	—	Act for a synthetic member id instead of the caller identity (backend integrations)

Response

Returns object.

Field	Type	Always	Description
`member`	`object`	•	The entered/updated member
`channel`	`string`	•	Channel name

GET/realtime/public-access/status

Check whether this product has a public key configured — an onboarding hint for the portal, never an authorization decision

MCP tool: realtime_public_access_status

Parameters

No parameters.

Response

Returns object.

Field	Type	Always	Description
`exists`	`boolean`	•	Whether this product has created a public key yet (an onboarding hint, not a gate)

GET/realtime/status

Get realtime service status: Redis fan-out connectivity, token signing key presence, gateway URL

MCP tool: realtime_status_get

Parameters

No parameters.

Response

Returns object.

Field	Type	Always	Description
`redis`	`string`one of: connected, disconnected, unconfigured	•	Redis fan-out connectivity
`service`	`string`one of: ok	•	API liveness marker
`gatewayUrl`	`string`	•	WebSocket URL of the realtime gateway
`signingKeyConfigured`	`boolean`	•	Whether the token signing key is present

POST/realtime/tokens

Mint a short-lived capability token (JWT) carrying the capabilities the identity has via namespace policy and grants (optionally filtered to the given channels), plus the gateway WebSocket URL to connect to

MCP tool: realtime_tokens_create

Parameters

Name	In	Type	Required	Description
`channels`	body	`string[]`	—	Concrete channels to filter the resolved capabilities to; omit to receive all capabilities the identity has

Response

Returns object.

Field	Type	Always	Description
`token`	`string`	•	Signed EdDSA capability JWT (60s TTL)
`gatewayUrl`	`string`	•	WebSocket URL of the realtime gateway to connect to

GET/realtime/webhooks

List all client webhooks registered for this product (secret metadata only)

MCP tool: realtime_webhook_list

Parameters

No parameters.

Response

Returns object.

Field	Type	Always	Description
`webhooks`	`object[]`	•	—

POST/realtime/webhooks

Register a client webhook: lifecycle notifications (channel occupied/vacated, presence member added/removed) are POSTed to the URL signed with HMAC-SHA256. Returns the full signing secret ONCE.

MCP tool: realtime_webhook_create

Parameters

Name	In	Type	Required	Description
`url`	body	`string (uri)`	•	Endpoint that receives signed lifecycle POSTs (https in production)
`events`	body	`string[]`one of: channel.occupied, channel.vacated, presence.member-added, presence.member-removed	•	Lifecycle event types this webhook receives
`description`	body	`string`	—	Free-form note

Response

Returns object.

Field	Type	Always	Description
`secret`	`string`	•	Full signing secret — returned only once, at creation. Store it now.
`webhook`	`object`	•	—

DELETE/realtime/webhooks/:webhookId

Delete a client webhook (its secrets and delivery log go with it)

MCP tool: realtime_webhook_delete

Parameters

Name	In	Type	Required	Description
`webhookId`	path	`string (uuid)`	•	Webhook id

Response

Returns object.

Field	Type	Always	Description
`deleted`	`boolean`one of: true	•	—

GET/realtime/webhooks/:webhookId

Get a client webhook by id (secret metadata only, never the secret)

MCP tool: realtime_webhook_get

Parameters

Name	In	Type	Required	Description
`webhookId`	path	`string (uuid)`	•	Webhook id

Response

Returns object.

Field	Type	Always	Description
`id`	`string (uuid)`	•	—
`url`	`string`	•	—
`active`	`boolean`	•	—
`events`	`string[]`	•	—
`secrets`	`object[]`	•	Secret metadata only — never the secret itself
`createdAt`	`string`	•	—
`updatedAt`	`string`	•	—
`description`	`string \| null`	•	—

PATCH/realtime/webhooks/:webhookId

Update a client webhook: url, event filter, description, active flag

MCP tool: realtime_webhook_update

Parameters

Name	In	Type	Required	Description
`url`	body	`string (uri)`	—	Endpoint that receives signed lifecycle POSTs (https in production)
`events`	body	`string[]`one of: channel.occupied, channel.vacated, presence.member-added, presence.member-removed	—	Lifecycle event types this webhook receives
`description`	body	`string \| null`	—	Free-form note
`active`	body	`boolean`	—	Inactive webhooks receive no deliveries
`webhookId`	path	`string (uuid)`	•	Webhook id to update

Response

Returns object.

Field	Type	Always	Description
`id`	`string (uuid)`	•	—
`url`	`string`	•	—
`active`	`boolean`	•	—
`events`	`string[]`	•	—
`secrets`	`object[]`	•	Secret metadata only — never the secret itself
`createdAt`	`string`	•	—
`updatedAt`	`string`	•	—
`description`	`string \| null`	•	—

GET/realtime/webhooks/:webhookId/deliveries

List recent delivery attempts of a webhook (status, attempts, response code)

MCP tool: realtime_webhook_deliveries_list

Parameters

Name	In	Type	Required	Description
`webhookId`	path	`string (uuid)`	•	Webhook id
`limit`	query	`integer`	—	Max deliveries to return (newest first)

Response

Returns object.

Field	Type	Always	Description
`deliveries`	`object[]`	•	—

POST/realtime/webhooks/:webhookId/secret/rotate

Rotate the webhook signing secret with an overlap window: the new secret signs immediately (returned ONCE), the previous one keeps verifying until its grace expiry

MCP tool: realtime_webhook_secret_rotate

Parameters

Name	In	Type	Required	Description
`webhookId`	path	`string (uuid)`	•	Webhook id

Response

Returns object.

Field	Type	Always	Description
`prefix`	`string`	•	Visible prefix of the new secret (X-Realtime-Key)
`secret`	`string`	•	New full signing secret — returned only once. Store it now.
`previousExpiresAt`	`string \| null`	•	When the rotated-out secret stops verifying (grace window)

Was this page helpful?