---
title: "Open a realtime connection"
method: POST
path: "/realtime/connections"
tags: ["Realtime"]
---

# Open a realtime connection

`POST /realtime/connections`

Opens a temporary pre-authorized public realtime websocket connection URL for RFC 085 ProductEvent delivery. API keys are validated only on this HTTP route; the websocket uses the returned temporary ticket URL and the ando.realtime.v1 subprotocol.

## Request body

- OpenRealtimeConnectionRequest — Public realtime connection-opening request.
  - `resume_from` RealtimeResumeRequest — Bounded realtime resume request.
    - `cursor` string, required — Last acknowledged realtime cursor.
  - `subscriptions` RealtimeConnectionSubscriptionRequest[], required — Realtime subscriptions to authorize for this connection.
    - `delivery` 'messages', required — Realtime delivery filter. "messages" delivers readable conversation-scoped ProductEvents.
    - `events` RealtimeEventType[], required — ProductEvent types requested for this subscription.
    - `target` union, required — Realtime target requested while opening a connection. The initial release supports self or an explicit workspace membership target.
      - 'self' — Authenticated principal shorthand.
      - object — Workspace membership realtime target.
        - `id` string, required — Workspace membership identifier.
        - `type` 'workspace_membership', required — Target type.

## Response `200`

Opened temporary realtime connection.

- OpenRealtimeConnectionResponse — Temporary public realtime websocket connection details.
  - `approximate_connection_time_seconds` number, nullable, required — Approximate maximum connection lifetime in seconds. Resume near a cursor deadline can shorten it.
  - `connection_id` string, required — Realtime connection identifier.
  - `expires_at` string, date-time, required — Timestamp when the returned connection URL expires if unused. Resume near a cursor deadline can shorten the normal URL lifetime.
  - `expires_in_seconds` integer, required — Seconds until the returned connection URL expires if unused, capped by any resume-cursor deadline.
  - `heartbeat_interval_seconds` integer, required — Recommended heartbeat interval for the socket.
  - `protocol` 'ando.realtime.v1', required — Required websocket subprotocol.
  - `resume_supported` boolean, required — Whether bounded resume is supported for this connection.
  - `resume_cursor` string, required — Safe cursor for the connection's initial ledger floor. Persist it before opening the websocket, then replace it only after the server confirms an ordered acknowledgement or sends a planned-disconnect checkpoint.
  - `subscriptions` RealtimeConnectionSubscription[], required — Canonical subscriptions authorized for the socket.
    - `delivery` 'messages', required — Realtime delivery filter. "messages" delivers readable conversation-scoped ProductEvents.
    - `events` RealtimeEventType[], required — ProductEvent types delivered on this subscription.
    - `id` string, required — Realtime subscription identifier.
    - `target` RealtimeObjectTarget, required — Canonical realtime target resolved by the API. The initial release returns workspace membership targets only.
      - `id` string, required — Target identifier.
      - `type` 'workspace_membership', required — Target type.
  - `url` string, required — Temporary pre-authorized websocket URL. Treat the ticket query parameter as secret.

## Other responses

- `400` — Bad request.
- `401` — Missing or invalid API key.
- `403` — Forbidden.
- `404` — Not found.
- `409` — Conflict.
- `429` — Rate limit or quota exceeded.
- `500` — Internal server error.
- `503` — Public realtime connection opening is not available in this deployment.

---

[API](https://skmtc.net/ando/apis/ando-public-api.md) · [All operations](https://skmtc.net/ando/apis/ando-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ando/ando-public-api/revisions/0a94056fba48/schema)