Skip to Content

Channel

Messages between programs on the host and rookery.

OperationKindHTTP
channel.publishcallPOST /v1/channel/{topic}
channel.readcallGET /v1/channel
channel.listenstreamGET /v1/channel

channel.publish

Publish a message on a topic.

Host and agent level. Through rookery serve it needs the role operate.

Arguments

NameWhereRequiredDescription
topicpathyesThe topic, with slashes: plugin/what.

Input

FieldTypeDescription
body (optional)any
keep (optional)Keep | null

Result

FieldTypeDescription
bodyany
fromFromWho did something, as rookeryd saw it.
idinteger
keepKeep
timestring
topicstring
Request
{
  "id": 1,
  "op": "channel.publish",
  "args": {
    "topic": "myplugin/progress"
  },
  "data": {
    "body": {
      "columns": 2
    },
    "keep": "none"
  }
}
Reply
{
  "id": 1,
  "result": {
    "body": {
      "columns": 2
    },
    "from": {
      "level": "host",
      "session": "k3v9qz2m8w1x",
      "uid": 1001
    },
    "id": 0,
    "keep": "none",
    "time": "2026-11-12T09:30:00Z",
    "topic": "myplugin/progress"
  }
}

channel.read

Kept messages after since.

Host and agent level. Through rookery serve it needs the role view.

Arguments

NameWhereRequiredDescription
topicquerynoOnly topics starting with this.
sincequerynoMessages after this id; default 0.
limitquerynoMost messages; default 100, at most 1000.

Result

FieldTypeDescription
messagesMessage[]
next (optional)integer | nullPass as since for the rest, when there is more.
Request
{
  "id": 1,
  "op": "channel.read",
  "args": {
    "since": "VALUE"
  }
}
Reply
{
  "id": 1,
  "result": {
    "messages": [
      {
        "body": {
          "columns": 2
        },
        "from": {
          "level": "host",
          "session": "k3v9qz2m8w1x",
          "uid": 1001
        },
        "id": 0,
        "keep": "none",
        "time": "2026-11-12T09:30:00Z",
        "topic": "myplugin/progress"
      }
    ],
    "next": 0
  }
}

channel.listen

Messages on the channel: the kept ones after since, then what arrives.

Host and agent level. A stream, as a subscription on the portal or a WebSocket of its own. It resumes from since. Through rookery serve it needs the role view.

Arguments

NameWhereRequiredDescription
topicquerynoOnly topics starting with this.
sincequerynoKept messages after this id come first. Without it, only each topic's last message does.

Frames from the server

FrameKindDescription
messageJSONOne message. Example: {"body":{"percent":40},"from":{"level":"agent","uid":1001},"id":4812,"keep":"log","time":"2026-11-12T10:00:00Z","topic":"myplugin/progress"}

Frames to the server

FrameKindDescription
publishJSONPublish a message. Example: {"body":{"percent":40},"keep":"none","topic":"myplugin/progress"}
Request
{
  "id": 1,
  "op": "channel.listen",
  "args": {
    "since": "VALUE"
  }
}
Reply
{
  "id": 1,
  "result": {
    "open": true
  }
}

{
  "sub": 1,
  "data": {
    "body": {
      "percent": 40
    },
    "from": {
      "level": "agent",
      "uid": 1001
    },
    "id": 4812,
    "keep": "log",
    "time": "2026-11-12T10:00:00Z",
    "topic": "myplugin/progress"
  }
}

End the subscription with {"sub": 1, "end": true}.

Types

The named types used on this page.

Keep

Keep

From

Who did something, as rookeryd saw it.

FieldTypeDescription
levelLevel
session (optional)string | null
uidinteger

Message

FieldTypeDescription
bodyany
fromFromWho did something, as rookeryd saw it.
idinteger
keepKeep
timestring
topicstring

Level

Level

On this page