WebSocket API

Connect to ws://host:port/stream with Authorization: Bearer {API_KEY} header.

All messages follow JSON-RPC 2.0 format.

Read Methods

kv/get

{"jsonrpc": "2.0", "method": "kv/get", "params": {"namespace": "tenant:acme/user:u1/preferences", "key": "theme"}, "id": 1}

Response:

{"jsonrpc": "2.0", "result": {"namespace": "tenant:acme/user:u1/preferences", "key": "theme", "value": "dark", "version": 7, "updatedBy": "auth0|u1", "updatedAt": 1742300000000}, "id": 1}

kv/list

{"jsonrpc": "2.0", "method": "kv/list", "params": {"namespace": "tenant:acme/user:u1/preferences", "prefix": "theme"}, "id": 2}

kv/mget

Batch read — multiple keys in one round-trip.

{"jsonrpc": "2.0", "method": "kv/mget", "params": {"keys": [
  {"namespace": "tenant:acme/user:u1/preferences", "key": "theme"},
  {"namespace": "tenant:acme/user:u1/preferences", "key": "font"}
]}, "id": 3}

Write Methods

kv/set

{"jsonrpc": "2.0", "method": "kv/set", "params": {"namespace": "tenant:acme/user:u1/preferences", "key": "theme", "value": "dark", "actor": "auth0|u1"}, "id": 4}

Optional cas parameter for compare-and-swap (optimistic concurrency):

{"jsonrpc": "2.0", "method": "kv/set", "params": {"namespace": "...", "key": "theme", "value": "dark", "actor": "u1", "cas": 7}, "id": 5}

If current version is not 7, returns error -32002 CAS Conflict.

kv/delete

{"jsonrpc": "2.0", "method": "kv/delete", "params": {"namespace": "...", "key": "oldKey", "actor": "auth0|u1"}, "id": 6}

kv/batch

Atomic multi-key write.

{"jsonrpc": "2.0", "method": "kv/batch", "params": {"operations": [
  {"op": "set", "namespace": "...", "key": "theme", "value": "dark"},
  {"op": "delete", "namespace": "...", "key": "oldPref"}
], "actor": "auth0|u1"}, "id": 7}

Watch Subscriptions

watch/subscribe

Subscribe to changes in a namespace. Receives watch/change notifications.

{"jsonrpc": "2.0", "method": "watch/subscribe", "params": {"namespace": "tenant:acme"}, "id": 8}

watch/unsubscribe

{"jsonrpc": "2.0", "method": "watch/unsubscribe", "params": {"namespace": "tenant:acme"}, "id": 9}

watch/change (Server Notification)

Sent when a subscribed namespace changes. No id field (notification, not request).

{
  "jsonrpc": "2.0",
  "method": "watch/change",
  "params": {
    "seq": 12345,
    "op": "set",
    "namespace": "tenant:acme/user:u1/preferences",
    "key": "theme",
    "value": "dark",
    "version": 8,
    "actor": "auth0|u1",
    "timestamp": 1742300000000,
    "tenantId": "acme"
  }
}

Error Codes