Watch

The Watch API lets applications receive live notifications when keys change in a namespace. This enables config hot-reloading without restarts.

Two modes are available: long-polling and SSE streaming.

Long-Polling

The client makes a request that blocks until a change occurs or the timeout expires:

curl http://localhost:7200/v1/watch/myapp/prod?timeout=30s \
  -H "Authorization: Bearer YOUR_TOKEN"

If no change occurs within the timeout, the server returns an empty response and the client should reconnect.

SSE Streaming

For real-time push notifications, use Server-Sent Events:

curl -N http://localhost:7200/v1/watch/myapp/prod?stream=true \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: text/event-stream"

SSE Response Format

event: connected
data: {"namespace":"myapp/prod","timestamp":"2025-12-20T10:00:00Z"}

event: change
data: {"action":"set","namespace":"myapp/prod","key":"DB_HOST","entry":{...},"timestamp":"2025-12-20T10:01:00Z"}

event: change
data: {"action":"delete","namespace":"myapp/prod","key":"OLD_KEY","timestamp":"2025-12-20T10:02:00Z"}

Event Types

Event	Description
connected	Stream established
change	A key was set or deleted

Client SDKs

All official SDKs support watch:

• PHP: watch() (long-poll), watchStream() (SSE)
• Dart: watch(), watchStream()

See SDK Overview for examples.

Use Cases

• Reload application config when an admin updates a value
• Invalidate caches on secret rotation
• Coordinate multiple service instances