Skip to Content

Events

One stream for channel messages, jobs, key-value changes and changes to hosts and resources.

OperationKindHTTP
events.followstreamGET /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

FrameKindDescription
channelJSONA 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"}
jobJSONA job started or ended. Example: {"job":{"action":"apply","host":"server","id":"j1","started":"2026-11-12T10:00:00Z","subject":"host:server"},"source":"job"}
kvJSONA key changed. Example: {"key":"layout","namespace":"ui","revision":4,"source":"kv","value":{}}
hostJSONA 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"}
resourceJSONA 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"}
droppedJSONThis 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

FrameKindDescription
followJSONWhat to follow. Sent once, first. Example: {"changes":["hosts","resources"],"hosts":["server"],"jobs":true,"kv":["ui"],"topics":["myplugin/"]}
Request
{
  "id": 1,
  "op": "events.follow"
}
Reply
{
  "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}.

On this page