Watch

Watching in Litebase lets you subscribe to key or namespace changes as they happen. This is useful for reactive systems, configuration updates, cache invalidation, live dashboards, and more.

Rather than polling for changes, you can listen for real-time updates — every write, version bump, or new value is delivered as a push.

1. What can you watch?

You can watch:

• A single key: e.g. user.abc123.profile
• A key prefix (namespace): e.g. user.abc123. or project.42.

Whenever a matching key is written, you’ll receive an event with the new version’s metadata and value.

2. Connect to a watch stream

To start watching, connect via Server-Sent Events (SSE):

curl -N "https://api.litebase.io/v1/kv/watch?prefix=user.abc123." \
  -H "Authorization: Bearer $LITEBASE_API_KEY" \
  -H "Accept: text/event-stream"

You can also watch a single key:

curl -N "https://api.litebase.io/v1/kv/watch?key=user.abc123.profile" \
  -H "Authorization: Bearer $LITEBASE_API_KEY" \
  -H "Accept: text/event-stream"

3. Receive change events

Each time a matching key is updated, you’ll receive an event like:

event: update
data: {
  "key": "user.abc123.profile",
  "value": {
    "name": "Jane",
    "email": "[email protected]"
  },
  "time": "2025-04-06T10:00:00Z",
  "tx": "tx_abc123ef",
  "version": 5
}

Parse the data: line as JSON to get the full change payload.

4. Resume from a known point

To avoid missing updates after a disconnect, you can resume from a known transaction using the since parameter:

curl -N "https://api.litebase.io/v1/kv/watch?prefix=user.abc123.&since=tx_abc123ef" \
  -H "Authorization: Bearer $LITEBASE_API_KEY"

This will replay any missed changes and continue watching in real time.

5. Use cases

Watching is ideal for:

• Live UIs that reflect real-time changes
• Distributed agents reacting to new configs
• Async workers waiting on status updates
• Monitoring or audit systems observing key changes
• Cache invalidation based on actual writes

Because all values are versioned and timestamped, you can react with confidence.