Events
One stream for channel messages, jobs, key-value changes and changes to hosts and resources.
| Operation | Kind | HTTP |
|---|---|---|
events.follow | stream | GET /v1/events |
events.follow
Channel messages of chosen hosts, jobs, key-value changes and changes to hosts and resources together. The first frame sent names what to follow; each frame received says where it came from.
A stream, as a subscription on the portal or a WebSocket of its own. It does not resume. Needs the role view.
Frames from the server
| Frame | Kind | Description |
|---|---|---|
channel | JSON | A message from a host's channel. Example: {"host":"server","message":{"body":{},"from":{"level":"host","uid":0},"id":1,"keep":"log","time":"2026-11-12T10:00:00Z","topic":"a/b"},"source":"channel"} |
job | JSON | A job started or ended. Example: {"job":{"action":"apply","host":"server","id":"j1","started":"2026-11-12T10:00:00Z","subject":"host:server"},"source":"job"} |
kv | JSON | A key changed. Example: {"key":"layout","namespace":"ui","revision":4,"source":"kv","value":{}} |
host | JSON | A saved host was added, removed, renamed (with the name it had from) or its profile changed. Read the host itself with hosts.get. Example: {"change":"renamed","from":"desk","host":"studio","source":"host"} |
resource | JSON | A resource was created, removed or its record changed. Read it with resources.get. Example: {"change":"created","kind":"deployment","provisioner":"docker","resource":"r-k3v9qz2m","source":"resource"} |
dropped | JSON | This follower was too slow. events counts the server's events it missed, of every kind. Read what it follows again. Example: {"dropped":{"events":12}} |
Frames to the server
| Frame | Kind | Description |
|---|---|---|
follow | JSON | What to follow. Sent once, first. Example: {"changes":["hosts","resources"],"hosts":["server"],"jobs":true,"kv":["ui"],"topics":["myplugin/"]} |
{
"id": 1,
"op": "events.follow"
}{
"id": 1,
"result": {
"open": true
}
}
{
"sub": 1,
"data": {
"host": "server",
"message": {
"body": {},
"from": {
"level": "host",
"uid": 0
},
"id": 1,
"keep": "log",
"time": "2026-11-12T10:00:00Z",
"topic": "a/b"
},
"source": "channel"
}
}End the subscription with {"sub": 1, "end": true}.