Realtime updates

Erdo’s organization WebSocket tells an external app when its canonical data has changed. Events are small invalidation signals rather than copies of datasets or messages: when one arrives, re-read the affected view through /v1 so current permissions, dataset filters, and response contracts still apply.

Keep the API key on your server

The browser never needs your Erdo API key. Add a same-origin route to your app’s server that calls the ticket endpoint with the browser application’s exact origin:

curl -X POST https://api.erdo.ai/v1/realtime/tickets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: acme" \
  -H "Content-Type: application/json" \
  -d '{"origin":"https://app.example.com"}'

{
  "ticket": "one-time-ticket",
  "organization_id": "organization-uuid",
  "expires_in_seconds": 300
}

The active organization comes from normal API authentication, including an optional X-Organization-ID header. A caller cannot request a ticket for a different channel or organization. The ticket expires after five minutes, is consumed by the first successful connection, and accepts only the exact origin supplied above. Return the ticket—not the API key—from your server route to your browser. Convert the API base URL to WebSocket protocol and include the authorized organization in the connection query:

const bootstrap = await fetch("/api/erdo-realtime", { method: "POST" }).then(
  (response) => response.json(),
)

const url = new URL("https://api.erdo.ai/websocket/connect")
url.protocol = "wss:"
url.searchParams.set("ticket", bootstrap.ticket)
url.searchParams.set("resource_type", "organization")
url.searchParams.set("resource_id", bootstrap.organization_id)

const socket = new WebSocket(url)
socket.addEventListener("open", () => {
  socket.send(JSON.stringify({
    type: "subscribe",
    channel: {
      type: "organization",
      resource_id: bootstrap.organization_id,
    },
  }))
})

Wait for the subscribed control message before showing a live status. A ticket is one-time, so request a fresh ticket before every reconnect. Use exponential backoff and keep a visibility-aware periodic refresh as recovery for missed events. While the socket is open and the tab is visible, send {"type":"ping"} every 30 seconds; Erdo answers with type: "pong" and keeps the connection alive.

Handle events

Broadcast messages have a top-level type, channel, and timestamp. payload is a JSON-encoded string whose fields depend on the event type:

socket.addEventListener("message", (message) => {
  const event = JSON.parse(message.data)

  if (event.type === "subscribed") return

  switch (event.type) {
    case "record_captured":
    case "thread_activity":
    case "attention_created":
    case "attention_updated":
    case "approval_created":
    case "approval_decided":
    case "entity_autolink_result":
      refreshVisibleData()
      break
    default:
      // Forward compatibility: ignore event types this client does not know.
      break
  }
})

record_captured is emitted only after a successful record-capture pipeline run. It names the pipeline, execution, and written dataset references but never includes the submitted record. Page views and widget telemetry do not emit this event, so normal traffic cannot create an app-wide refresh loop. thread_activity likewise contains conversation identity and activity type, not message content. The WebSocket is a prompt to re-read, not a durable event log. Debounce bursts of events, refresh only while the tab is visible, reconnect with a new ticket after a disconnect, and retain a slower periodic refresh so the UI converges even if a producer has no realtime event yet.

Platform API

API Reference

Build apps

Python SDK

TypeScript SDK

Realtime updates

Realtime updates

Keep the API key on your server

Handle events

​Realtime updates

​Keep the API key on your server

​Connect and subscribe

​Handle events

Realtime updates

Keep the API key on your server

Connect and subscribe

Handle events