Channel
Messages between programs on the host and rookery.
| Operation | Kind | HTTP |
|---|---|---|
channel.publish | call | POST /v1/channel/{topic} |
channel.read | call | GET /v1/channel |
channel.listen | stream | GET /v1/channel |
channel.publish
Publish a message on a topic.
Host and agent level. Through rookery serve it needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
topic | path | yes | The topic, with slashes: plugin/what. |
Input
| Field | Type | Description |
|---|---|---|
body (optional) | any | |
keep (optional) | Keep | null |
Result
| Field | Type | Description |
|---|---|---|
body | any | |
from | From | Who did something, as rookeryd saw it. |
id | integer | |
keep | Keep | |
time | string | |
topic | string |
{
"id": 1,
"op": "channel.publish",
"args": {
"topic": "myplugin/progress"
},
"data": {
"body": {
"columns": 2
},
"keep": "none"
}
}{
"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
| Name | Where | Required | Description |
|---|---|---|---|
topic | query | no | Only topics starting with this. |
since | query | no | Messages after this id; default 0. |
limit | query | no | Most messages; default 100, at most 1000. |
Result
| Field | Type | Description |
|---|---|---|
messages | Message[] | |
next (optional) | integer | null | Pass as since for the rest, when there is more. |
{
"id": 1,
"op": "channel.read",
"args": {
"since": "VALUE"
}
}{
"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
| Name | Where | Required | Description |
|---|---|---|---|
topic | query | no | Only topics starting with this. |
since | query | no | Kept messages after this id come first. Without it, only each topic's last message does. |
Frames from the server
| Frame | Kind | Description |
|---|---|---|
message | JSON | One 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
| Frame | Kind | Description |
|---|---|---|
publish | JSON | Publish a message. Example: {"body":{"percent":40},"keep":"none","topic":"myplugin/progress"} |
{
"id": 1,
"op": "channel.listen",
"args": {
"since": "VALUE"
}
}{
"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
From
Who did something, as rookeryd saw it.
| Field | Type | Description |
|---|---|---|
level | Level | |
session (optional) | string | null | |
uid | integer |
Message
| Field | Type | Description |
|---|---|---|
body | any | |
from | From | Who did something, as rookeryd saw it. |
id | integer | |
keep | Keep | |
time | string | |
topic | string |