Sync API

Sync is a general-purpose, real-time shared-state primitive for building presence indicators, collaborative widgets, live counters, or any app state multiple clients need to see change in real time — without standing up your own pub/sub infrastructure. It mirrors the Documents / Maps / Lists / Streams model of Twilio Sync: Documents, Maps, and Lists are durable (they persist until you delete them), Streams are ephemeral pub/sub with no persistence. Base path: /api/v1/sync WebSocket gateway: /api/v1/ws/sync — connect here to receive change events (document.updated, map.item.set, list.item.added, stream.message, etc.) as they happen. Authentication: API key (X-API-Key) or session JWT. Reads are open to any authenticated member; writes require an operator role (owner, admin, developer, or agent).

Documents

A Document is a single JSON object addressed by a unique name, with a monotonic revision that bumps on every update.

Method	Path	Purpose
`POST`	`/api/v1/sync/documents`	Create a Document (`unique_name`, optional `data`, optional `ttl` in seconds)
`GET`	`/api/v1/sync/documents/{name}`	Get a Document’s current `data` + revision
`POST`	`/api/v1/sync/documents/{name}`	Replace a Document’s `data`, bumping the revision
`DELETE`	`/api/v1/sync/documents/{name}`	Delete a Document

Maps

A Map is an unordered, key-addressed collection of JSON values.

Method	Path	Purpose
`GET`	`/api/v1/sync/maps/{name}/items`	List every key → value item
`GET`	`/api/v1/sync/maps/{name}/items/{key}`	Get one item
`PUT`	`/api/v1/sync/maps/{name}/items/{key}`	Create or replace an item (optional `ttl`)
`DELETE`	`/api/v1/sync/maps/{name}/items/{key}`	Remove one item
`DELETE`	`/api/v1/sync/maps/{name}`	Delete the whole Map

Lists

A List is an ordered, append-indexed collection of JSON values.

Method	Path	Purpose
`GET`	`/api/v1/sync/lists/{name}/items`	List every item, in order
`POST`	`/api/v1/sync/lists/{name}/items`	Append an item, returns its new index
`PUT`	`/api/v1/sync/lists/{name}/items/{index}`	Replace the item at an index
`DELETE`	`/api/v1/sync/lists/{name}/items/{index}`	Remove the item at an index
`DELETE`	`/api/v1/sync/lists/{name}`	Delete the whole List

Streams

A Stream is ephemeral pub/sub — nothing is stored. Only clients connected to the WebSocket gateway at publish time receive the message.

Method	Path	Purpose
`POST`	`/api/v1/sync/streams/{name}/messages`	Publish a JSON message to every connected subscriber

WebSocket consumer

The gateway exposes a small JSON protocol over the socket. Send subscribe / unsubscribe frames naming a kind (document, map, list, or stream) and a unique name; the server answers subscribed / unsubscribed to acknowledge, then relays change events.

// node: npm install ws — browser: use the built-in WebSocket
import WebSocket from "ws";

const API_KEY = "dv_live_sk_your_key_here"; // node only — see auth note below
const socket = new WebSocket(
  "wss://api.orbit.devotel.io/api/v1/ws/sync",
  { headers: { "X-API-Key": API_KEY } },
);

socket.addEventListener("open", () => {
  socket.send(
    JSON.stringify({
      type: "subscribe",
      kind: "document",
      name: "room_42_viewers",
    }),
  );
});

socket.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case "hello":
      console.log("connected", msg.tenantId);
      break;
    case "subscribed":
      console.log("watching", msg.kind, msg.name);
      break;
    case "document.updated":
      console.log(`revision ${msg.revision}:`, msg.data);
      break;
    case "map.item.set":
      console.log(`map key ${msg.key}:`, msg.data);
      break;
    case "list.item.added":
      console.log(`list index ${msg.index}:`, msg.data);
    case "stream.message":
      console.log("stream message:", msg.data);
      break;
    default:
      console.log("unhandled change event:", msg);
  }
});

socket.addEventListener("close", () => {
  // Reconnect with backoff — the server closes idle sockets and on shutdown.
});

Auth from a browser. The browser WebSocket constructor cannot set headers, so encode the credential as a subprotocol token: new WebSocket(url, ["orbit-sync-v1", "Bearer.<jwt>"]) for a session JWT, or new WebSocket(url, ["ApiKey.<key>"]) for an API key. The server scans the Sec-WebSocket-Protocol list for the Bearer. / ApiKey. token and promotes it to the normal auth header shape during the upgrade handshake. Never embed a secret API key in front-end code shipped to end users — mint keys on your backend.

const socket = new WebSocket("wss://api.orbit.devotel.io/api/v1/ws/sync", [
  "orbit-sync-v1",
  `ApiKey.${API_KEY}`, // or `Bearer.${sessionJwt}`
]);

Frame shape. Every relayed change event carries type (the discriminator), kind, unique_name, revision (absent for stream.message), key (map events), index (list events), data (absent on removal events), and a ts publish timestamp. To unsubscribe, send { "type": "unsubscribe", "kind": "...", "name": "..." }. Client ping frames get a pong answer; malformed frames get an error frame with a reason.

Ops debugging with wscat

wscat -c "wss://api.orbit.devotel.io/api/v1/ws/sync" \
  -H "X-API-Key: dv_live_sk_your_key_here"
> { "type": "subscribe", "kind": "map", "name": "room_42_presence" }
< { "type": "subscribed", "kind": "map", "name": "room_42_presence" }
< { "type": "map.item.set", "kind": "map", "unique_name": "room_42_presence", "key": "user_123", "revision": 7, "data": { "status": "online" }, "ts": 1756147200000 }

Recipe — a collaborative presence indicator

A classic presence pattern: each client announces itself in a Map keyed by user id, and every client renders from those change events. REST writes, WebSocket reads.

// 1. Announce yourself (API key minted by your backend — keep it server-side).
async function announce(userId, status) {
  await fetch(
    `https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items/${userId}`,
    {
      method: "PUT",
      headers: {
        "X-API-Key": "dv_live_sk_your_key_here",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        data: { status, lastSeenAt: Date.now() }, // ttl (seconds) optional
      }),
    },
  );
}

// 2. Every client listens for join/leave/refresh events.
const presence = new Map();
socket.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "map.item.set") {
    presence.set(msg.key, msg.data);
  }
  if (msg.type === "map.item.removed" || msg.type === "map.removed") {
    presence.delete(msg.key ?? undefined);
    if (msg.type === "map.removed") presence.clear();
  }
  renderPresence(presence); // your UI update
});

Subscribe once to kind: "map", name: "room_42_presence", then each announce() call fans out to every connected viewer. To compute a live viewer counter instead of a per-user roster, have your backend publish to a Stream (POST /sync/streams/room_42_viewers/messages) and render stream.message events — no Map cleanup needed.

API Reference

All Endpoints

Sync API: real-time Documents, Maps, Lists, and Streams

Sync API

Documents

Maps

Lists

Streams

WebSocket consumer

Ops debugging with wscat

Recipe — a collaborative presence indicator

See also

​Sync API

​Documents

​Maps

​Lists

​Streams

​WebSocket consumer

​Ops debugging with wscat

​Recipe — a collaborative presence indicator

​See also

Sync API

Documents

Maps

Lists

Streams

WebSocket consumer

Ops debugging with wscat

Recipe — a collaborative presence indicator

See also