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). The REST-write → WebSocket-read loop. Every mutation over REST publishes exactly one change event frame on the gateway for any client subscribed to the same object. Write over REST, render from the socket. Each example below names the frame it emits — subscribe with kind + name before you write, and the frame arrives within milliseconds. All responses use the standard envelope: the resource under data, plus a meta block with the request id and timestamp. Deletes return 204 No Content with an empty body.

Using the SDKs

The Node SDK exposes typed helpers for every Sync operation — client.sync.documents, client.sync.maps, client.sync.lists, client.sync.streams — and each sample group below leads with them. The Python SDK wraps the 8 core resources and reaches Sync through the generic client.request() escape hatch, which keeps auth, retries, and the { data, meta } envelope identical:

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request(
    "POST",
    "/sync/documents",
    json_body={"unique_name": "room_42_viewers", "data": {"online": 0}},
)

Go, Ruby, and PHP samples use plain standard-library HTTP. Full SDK index at SDK quickstart.

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	Emits
`POST`	`/api/v1/sync/documents`	Create a Document (`unique_name`, optional `data`, optional `ttl` in seconds)	`document.updated`
`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	`document.updated`
`DELETE`	`/api/v1/sync/documents/{name}`	Delete a Document	`document.removed`

Create a Document. The name is create-once: a second POST with an existing unique_name returns 409 CONFLICT. ttl (seconds) is optional; omit it and the Document persists until you delete it. The response is 201 Created with the Document at revision 1.

curl -X POST https://api.orbit.devotel.io/api/v1/sync/documents \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "unique_name": "room_42_viewers",
    "data": { "online": 0, "title": "Daily standup" },
    "ttl": 3600
  }'

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const document = await client.sync.documents.create({
  unique_name: "room_42_viewers",
  data: { online: 0, title: "Daily standup" },
  ttl: 3600,
});
console.log(document.revision); // 1

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request(
    "POST",
    "/sync/documents",
    json_body={
        "unique_name": "room_42_viewers",
        "data": {"online": 0, "title": "Daily standup"},
        "ttl": 3600,
    },
)
print(res["data"]["revision"])  # 1

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]interface{}{
		"unique_name": "room_42_viewers",
		"data":        map[string]interface{}{"online": 0, "title": "Daily standup"},
		"ttl":         3600,
	})
	req, _ := http.NewRequest(
		"POST",
		"https://api.orbit.devotel.io/api/v1/sync/documents",
		bytes.NewReader(body),
	)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var out struct {
		Data struct {
			Revision int `json:"revision"`
		} `json:"data"`
	}
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Data.Revision) // 1
}

require "json"
require "net/http"

uri = URI("https://api.orbit.devotel.io/api/v1/sync/documents")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV["ORBIT_API_KEY"]
request["Content-Type"] = "application/json"
request.body = JSON.generate(
  unique_name: "room_42_viewers",
  data: { online: 0, title: "Daily standup" },
  ttl: 3600
)

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.parse(response.body).dig("data", "revision")  # 1

<?php
$key = getenv("ORBIT_API_KEY");

$ch = curl_init("https://api.orbit.devotel.io/api/v1/sync/documents");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . $key,
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "unique_name" => "room_42_viewers",
    "data" => ["online" => 0, "title" => "Daily standup"],
    "ttl" => 3600,
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $response["data"]["revision"] . PHP_EOL;  // 1

{
  "data": {
    "unique_name": "room_42_viewers",
    "data": { "online": 0, "title": "Daily standup" },
    "revision": 1,
    "date_created": "2026-08-27T12:00:00.000Z",
    "date_updated": "2026-08-27T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_9f2a1c",
    "timestamp": "2026-08-27T12:00:00.121Z"
  }
}

Subscribers on { "kind": "document", "name": "room_42_viewers" } receive the create as their first frame:

{ "type": "document.updated", "kind": "document", "unique_name": "room_42_viewers", "revision": 1, "data": { "online": 0, "title": "Daily standup" }, "ts": 1756286400121 }

Replace a Document’s data. A POST to the Document’s own path replaces data wholesale and bumps the revision — revisions are monotonic per Document, so a client that missed a frame can compare revisions and re-hydrate from the REST GET below. A missing name returns 404 NOT_FOUND.

curl -X POST https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "online": 3, "title": "Daily standup" } }'

const updated = await client.sync.documents.update("room_42_viewers", {
  data: { online: 3, title: "Daily standup" },
});
console.log(updated.revision); // 2

res = client.request(
    "POST",
    "/sync/documents/room_42_viewers",
    json_body={"data": {"online": 3, "title": "Daily standup"}},
)
print(res["data"]["revision"])  # 2

body, _ := json.Marshal(map[string]interface{}{
	"data": map[string]interface{}{"online": 3, "title": "Daily standup"},
})
req, _ := http.NewRequest(
	"POST",
	"https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers",
	bytes.NewReader(body),
)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
req.Header.Set("Content-Type", "application/json")

uri = URI("https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV["ORBIT_API_KEY"]
request["Content-Type"] = "application/json"
request.body = JSON.generate(
  data: { online: 3, title: "Daily standup" }
)
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body).dig("data", "revision")  # 2

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("ORBIT_API_KEY"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "data" => ["online" => 3, "title" => "Daily standup"],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $response["data"]["revision"] . PHP_EOL;  // 2

{
  "data": {
    "unique_name": "room_42_viewers",
    "data": { "online": 3, "title": "Daily standup" },
    "revision": 2,
    "date_created": "2026-08-27T12:00:00.000Z",
    "date_updated": "2026-08-27T12:01:14.000Z"
  },
  "meta": {
    "request_id": "req_9f2a2b",
    "timestamp": "2026-08-27T12:01:14.009Z"
  }
}

The socket frame carries the same bumped revision:

{ "type": "document.updated", "kind": "document", "unique_name": "room_42_viewers", "revision": 2, "data": { "online": 3, "title": "Daily standup" }, "ts": 1756286474009 }

Read and delete. A GET re-hydrates the current data and revision (use it when a client reconnects and needs full state, not just deltas). DELETE removes the Document and answers 204 No Content; subscribers receive document.removed with no data payload.

curl https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers \
  -H "X-API-Key: dv_live_sk_your_key_here"

curl -X DELETE https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers \
  -H "X-API-Key: dv_live_sk_your_key_here"

const document = await client.sync.documents.get("room_42_viewers");
console.log(document.revision, document.data);

await client.sync.documents.delete("room_42_viewers"); // 204 No Content

res = client.request("GET", "/sync/documents/room_42_viewers")
print(res["data"]["revision"], res["data"]["data"])

client.request("DELETE", "/sync/documents/room_42_viewers")  # 204 No Content

req, _ := http.NewRequest(
	"GET",
	"https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers",
	nil,
)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

del, _ := http.NewRequest(
	"DELETE",
	"https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers",
	nil,
)
del.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

uri = URI("https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers")
get = Net::HTTP::Get.new(uri)
get["X-API-Key"] = ENV["ORBIT_API_KEY"]

delete = Net::HTTP::Delete.new(uri)
delete["X-API-Key"] = ENV["ORBIT_API_KEY"]

Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  puts http.request(get).body
  http.request(delete) # 204 No Content
end

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: " . getenv("ORBIT_API_KEY")]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$document = json_decode(curl_exec($ch), true);
curl_close($ch);

$del = curl_init("https://api.orbit.devotel.io/api/v1/sync/documents/room_42_viewers");
curl_setopt($del, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($del, CURLOPT_HTTPHEADER, ["X-API-Key: " . getenv("ORBIT_API_KEY")]);
curl_exec($del); // 204 No Content
curl_close($del);

Maps

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

Method	Path	Purpose	Emits
`GET`	`/api/v1/sync/maps/{name}/items`	List every key → value item (ordered by key)	—
`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`)	`map.item.set`
`DELETE`	`/api/v1/sync/maps/{name}/items/{key}`	Remove one item	`map.item.removed`
`DELETE`	`/api/v1/sync/maps/{name}`	Delete the whole Map	`map.removed`

Set an item. PUT is upsert: it creates the key when absent and replaces it when present, bumping the Map’s revision either way. Subscribers on the Map receive map.item.set naming the key.

curl -X PUT https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items/user_123 \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "status": "online", "lastSeenAt": 1756286500000 } }'

const item = await client.sync.maps.set("room_42_presence", "user_123", {
  data: { status: "online", lastSeenAt: 1756286500000 },
});
console.log(item.revision); // 7

res = client.request(
    "PUT",
    "/sync/maps/room_42_presence/items/user_123",
    json_body={"data": {"status": "online", "lastSeenAt": 1756286500000}},
)
print(res["data"]["revision"])  # 7

body, _ := json.Marshal(map[string]interface{}{
	"data": map[string]interface{}{"status": "online", "lastSeenAt": 1756286500000},
})
req, _ := http.NewRequest(
	"PUT",
	"https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items/user_123",
	bytes.NewReader(body),
)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
req.Header.Set("Content-Type", "application/json")

uri = URI("https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items/user_123")
request = Net::HTTP::Put.new(uri)
request["X-API-Key"] = ENV["ORBIT_API_KEY"]
request["Content-Type"] = "application/json"
request.body = JSON.generate(
  data: { status: "online", lastSeenAt: 1756286500000 }
)
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body).dig("data", "revision")  # 7

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items/user_123");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("ORBIT_API_KEY"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "data" => ["status" => "online", "lastSeenAt" => 1756286500000],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $response["data"]["revision"] . PHP_EOL;  // 7

{
  "data": {
    "key": "user_123",
    "data": { "status": "online", "lastSeenAt": 1756286500000 },
    "revision": 7,
    "date_updated": "2026-08-27T12:01:40.000Z"
  },
  "meta": {
    "request_id": "req_9f2b11",
    "timestamp": "2026-08-27T12:01:40.003Z"
  }
}

{ "type": "map.item.set", "kind": "map", "unique_name": "room_42_presence", "key": "user_123", "revision": 7, "data": { "status": "online", "lastSeenAt": 1756286500000 }, "ts": 1756286500003 }

List the items. The list endpoint returns every item in the Map as an array ordered by key — the shape a reconnecting client uses to rebuild its roster in one call.

curl https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items \
  -H "X-API-Key: dv_live_sk_your_key_here"

const items = await client.sync.maps.items("room_42_presence");
for (const item of items) console.log(item.key, item.data);

res = client.request("GET", "/sync/maps/room_42_presence/items")
for item in res["data"]:
    print(item["key"], item["data"])

req, _ := http.NewRequest(
	"GET",
	"https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items",
	nil,
)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

uri = URI("https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV["ORBIT_API_KEY"]
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
JSON.parse(response.body)["data"].each { |item| puts item["key"], item["data"] }

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: " . getenv("ORBIT_API_KEY")]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($response["data"] as $item) {
    echo $item["key"] . PHP_EOL;
}

{
  "data": [
    {
      "key": "user_123",
      "data": { "status": "online", "lastSeenAt": 1756286500000 },
      "revision": 7,
      "date_updated": "2026-08-27T12:01:40.000Z"
    },
    {
      "key": "user_456",
      "data": { "status": "away", "lastSeenAt": 1756286412400 },
      "revision": 6,
      "date_updated": "2026-08-27T12:00:12.400Z"
    }
  ],
  "meta": {
    "request_id": "req_9f2b90",
    "timestamp": "2026-08-27T12:02:01.000Z"
  }
}

Remove an item or the whole Map. A per-item DELETE answers 204 No Content and emits map.item.removed with the key but no data; deleting the Map itself emits map.removed. Presence clients drop the key on the first frame and reset their roster on the second.

curl -X DELETE https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items/user_123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

await client.sync.maps.remove("room_42_presence", "user_123"); // 204 No Content

client.request("DELETE", "/sync/maps/room_42_presence/items/user_123")  # 204 No Content

req, _ := http.NewRequest(
	"DELETE",
	"https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items/user_123",
	nil,
)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

uri = URI("https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items/user_123")
request = Net::HTTP::Delete.new(uri)
request["X-API-Key"] = ENV["ORBIT_API_KEY"]
Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } # 204 No Content

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/sync/maps/room_42_presence/items/user_123");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: " . getenv("ORBIT_API_KEY")]);
curl_exec($ch); // 204 No Content
curl_close($ch);

Lists

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

Method	Path	Purpose	Emits
`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	`list.item.added`
`PUT`	`/api/v1/sync/lists/{name}/items/{index}`	Replace the item at an index	`list.item.updated`
`DELETE`	`/api/v1/sync/lists/{name}/items/{index}`	Remove the item at an index	`list.item.removed`
`DELETE`	`/api/v1/sync/lists/{name}`	Delete the whole List	`list.removed`

Append an item. POST appends and answers 201 Created with the item carrying its new 0-based index — the first append in a fresh List gets index 0. Subscribers receive list.item.added with the same index.

curl -X POST https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "from": "user_123", "text": "Anyone else seeing the lag?" } }'

const item = await client.sync.lists.push("room_42_chat", {
  data: { from: "user_123", text: "Anyone else seeing the lag?" },
});
console.log(item.index); // 0

res = client.request(
    "POST",
    "/sync/lists/room_42_chat/items",
    json_body={"data": {"from": "user_123", "text": "Anyone else seeing the lag?"}},
)
print(res["data"]["index"])  # 0

body, _ := json.Marshal(map[string]interface{}{
	"data": map[string]string{"from": "user_123", "text": "Anyone else seeing the lag?"},
})
req, _ := http.NewRequest(
	"POST",
	"https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items",
	bytes.NewReader(body),
)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
req.Header.Set("Content-Type", "application/json")

uri = URI("https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV["ORBIT_API_KEY"]
request["Content-Type"] = "application/json"
request.body = JSON.generate(
  data: { from: "user_123", text: "Anyone else seeing the lag?" }
)
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body).dig("data", "index")  # 0

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("ORBIT_API_KEY"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "data" => ["from" => "user_123", "text" => "Anyone else seeing the lag?"],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $response["data"]["index"] . PHP_EOL;  // 0

{
  "data": {
    "index": 0,
    "data": { "from": "user_123", "text": "Anyone else seeing the lag?" },
    "revision": 1,
    "date_updated": "2026-08-27T12:03:11.000Z"
  },
  "meta": {
    "request_id": "req_9f2c07",
    "timestamp": "2026-08-27T12:03:11.014Z"
  }
}

{ "type": "list.item.added", "kind": "list", "unique_name": "room_42_chat", "index": 0, "revision": 1, "data": { "from": "user_123", "text": "Anyone else seeing the lag?" }, "ts": 1756286591014 }

Replace the item at an index. PUT on an existing index swaps the value in place — indexes are stable and never shift on delete.

curl -X PUT https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items/0 \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "from": "user_123", "text": "Anyone else seeing the lag? (edited — resolved)" } }'

const item = await client.sync.lists.set("room_42_chat", 0, {
  data: { from: "user_123", text: "Anyone else seeing the lag? (edited — resolved)" },
});
console.log(item.revision); // 2

res = client.request(
    "PUT",
    "/sync/lists/room_42_chat/items/0",
    json_body={"data": {"from": "user_123", "text": "Anyone else seeing the lag? (edited — resolved)"}},
)
print(res["data"]["revision"])  # 2

body, _ := json.Marshal(map[string]interface{}{
	"data": map[string]string{
		"from": "user_123",
		"text": "Anyone else seeing the lag? (edited — resolved)",
	},
})
req, _ := http.NewRequest(
	"PUT",
	"https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items/0",
	bytes.NewReader(body),
)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
req.Header.Set("Content-Type", "application/json")

uri = URI("https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items/0")
request = Net::HTTP::Put.new(uri)
request["X-API-Key"] = ENV["ORBIT_API_KEY"]
request["Content-Type"] = "application/json"
request.body = JSON.generate(
  data: { from: "user_123", text: "Anyone else seeing the lag? (edited — resolved)" }
)
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body).dig("data", "revision")  # 2

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items/0");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("ORBIT_API_KEY"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "data" => ["from" => "user_123", "text" => "Anyone else seeing the lag? (edited — resolved)"],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $response["data"]["revision"] . PHP_EOL;  // 2

{
  "data": {
    "index": 0,
    "data": { "from": "user_123", "text": "Anyone else seeing the lag? (edited — resolved)" },
    "revision": 2,
    "date_updated": "2026-08-27T12:04:02.000Z"
  },
  "meta": {
    "request_id": "req_9f2c55",
    "timestamp": "2026-08-27T12:04:02.003Z"
  }
}

Remove. DELETE on an index answers 204 No Content and emits list.item.removed naming the index. Deleting the List itself answers 204 and emits list.removed.

curl -X DELETE https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items/0 \
  -H "X-API-Key: dv_live_sk_your_key_here"

await client.sync.lists.remove("room_42_chat", 0); // 204 No Content

client.request("DELETE", "/sync/lists/room_42_chat/items/0")  # 204 No Content

req, _ := http.NewRequest(
	"DELETE",
	"https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items/0",
	nil,
)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

uri = URI("https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items/0")
request = Net::HTTP::Delete.new(uri)
request["X-API-Key"] = ENV["ORBIT_API_KEY"]
Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) } # 204 No Content

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/sync/lists/room_42_chat/items/0");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: " . getenv("ORBIT_API_KEY")]);
curl_exec($ch); // 204 No Content
curl_close($ch);

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	Emits
`POST`	`/api/v1/sync/streams/{name}/messages`	Publish a JSON message to every connected subscriber	`stream.message`

Publish a message. The response is 201 Created with a sid you can correlate with the relayed frame, plus the data you sent and the publish ts. Because Streams hold no state, there is nothing to GET — a late subscriber simply starts from the next message.

curl -X POST https://api.orbit.devotel.io/api/v1/sync/streams/room_42_viewers/messages \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "online": 128 } }'

const message = await client.sync.streams.publish("room_42_viewers", {
  data: { online: 128 },
});
console.log(message.sid); // correlate with the socket frame's _sid

res = client.request(
    "POST",
    "/sync/streams/room_42_viewers/messages",
    json_body={"data": {"online": 128}},
)
print(res["data"]["sid"])  # correlate with the socket frame's _sid

body, _ := json.Marshal(map[string]interface{}{
	"data": map[string]int{"online": 128},
})
req, _ := http.NewRequest(
	"POST",
	"https://api.orbit.devotel.io/api/v1/sync/streams/room_42_viewers/messages",
	bytes.NewReader(body),
)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
req.Header.Set("Content-Type", "application/json")

uri = URI("https://api.orbit.devotel.io/api/v1/sync/streams/room_42_viewers/messages")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV["ORBIT_API_KEY"]
request["Content-Type"] = "application/json"
request.body = JSON.generate(data: { online: 128 })
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body).dig("data", "sid")

<?php
$ch = curl_init("https://api.orbit.devotel.io/api/v1/sync/streams/room_42_viewers/messages");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("ORBIT_API_KEY"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "data" => ["online" => 128],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $response["data"]["sid"] . PHP_EOL;

{
  "data": {
    "sid": "TZm9k3xqiv1a2b3c4d5e",
    "data": { "online": 128 },
    "ts": 1756286642301
  },
  "meta": {
    "request_id": "req_9f2d42",
    "timestamp": "2026-08-27T12:04:02.301Z"
  }
}

Subscribers on { "kind": "stream", "name": "room_42_viewers" } receive the frame shown in the WebSocket consumer below:

{ "type": "stream.message", "kind": "stream", "unique_name": "room_42_viewers", "data": { "online": 128, "_sid": "TZm9k3xqiv1a2b3c4d5e" }, "ts": 1756286642301 }

Note the relayed data carries your payload plus the _sid echo — match on _sid to correlate a REST publish with its socket frame.

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.js

// 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.

Node.js

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.

Node SDK

import { Orbit } from "@devotel-orbit/node";

const client = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

// 1. Announce yourself (API key minted by your backend — keep it server-side).
async function announce(userId: string, status: string) {
  await client.sync.maps.set("room_42_presence", userId, {
    data: { status, lastSeenAt: Date.now() }, // ttl (seconds) optional
  });
}

// 2. Every client listens for join/leave/refresh events.
const presence = new Map<string, { status: string; lastSeenAt: number }>();
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

Using the SDKs

Documents

Maps

Lists

Streams

WebSocket consumer

Ops debugging with wscat

Recipe — a collaborative presence indicator

See also

​Sync API

​Using the SDKs

​Documents

​Maps

​Lists

​Streams

​WebSocket consumer

​Ops debugging with wscat

​Recipe — a collaborative presence indicator

​See also

Sync API

Using the SDKs

Documents

Maps

Lists

Streams

WebSocket consumer

Ops debugging with wscat

Recipe — a collaborative presence indicator

See also