Realtime API

The Realtime area publishes 28 REST endpoints. Paths are relative to https://api.lepsto.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. A non-empty subject restricts results to that subject; omit it to list all subjects.

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
`replayed`	`boolean`	•	true only when the answer was replayed from a previous Idempotency-Key publish
`messageId`	`string`	•	Envelope id of the message — history exposes the same value as entries[].id
`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) from namespace policy and grants, and return the gateway WebSocket URL. A non-empty channels list filters capabilities to matching channels; omit it to skip that filter. Namespaces with a subscription proxy still require concrete requested channels approved by the proxy.

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?