Inbox
Messages taken in from the hosts' channels.
| Operation | Kind | HTTP |
|---|---|---|
inbox.list | call | GET /v1/inbox |
inbox.follow | stream | GET /v1/inbox |
inbox.done | call | POST /v1/inbox/{host}/{id}/done |
inbox.reopen | call | DELETE /v1/inbox/{host}/{id}/done |
inbox.list
Messages taken in from the hosts' channels.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
host | query | no | Only this host. |
topic | query | no | Only topics starting with this. |
before | query | no | Only messages taken in before this seq. |
done | query | no | Only done ones, or only those that are not. |
limit | query | no | At most this many (default 100, at most 1,000). |
Result
| Field | Type | Description |
|---|---|---|
messages | InboxMessage[] | |
next (optional) | integer | null | Pass as before for older ones, when there are more. |
{
"id": 1,
"op": "inbox.list"
}{
"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",
"done": true,
"host": "studio",
"host_id": "text",
"seq": 0
}
],
"next": 0
}
}inbox.follow
Messages as they are taken in from the hosts.
A stream, as a subscription on the portal or a WebSocket of its own. It does not resume. Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
host | query | no | Only this host. |
topic | query | no | Only topics starting with this. |
Frames from the server
| Frame | Kind | Description |
|---|---|---|
message | JSON | A stored message with its host. Example: {"body":{},"done":false,"from":{"level":"agent","uid":1001},"host":"server","id":4812,"keep":"log","time":"2026-11-12T10:00:00Z","topic":"myplugin/progress"} |
dropped | JSON | This follower was too slow. events counts the server's events it missed, of every kind. Read the inbox again. Example: {"dropped":{"events":12}} |
{
"id": 1,
"op": "inbox.follow"
}{
"id": 1,
"result": {
"open": true
}
}
{
"sub": 1,
"data": {
"body": {},
"done": false,
"from": {
"level": "agent",
"uid": 1001
},
"host": "server",
"id": 4812,
"keep": "log",
"time": "2026-11-12T10:00:00Z",
"topic": "myplugin/progress"
}
}End the subscription with {"sub": 1, "end": true}.
inbox.done
Mark a message as done.
Needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
host | path | yes | The host it came from, by its name or its id |
id | path | yes | The message's id on that host |
Result
| Field | Type | Description |
|---|---|---|
ok | boolean |
Errors
| Status | When |
|---|---|
| 404 | No such message |
{
"id": 1,
"op": "inbox.done",
"args": {
"host": "studio",
"id": 42
}
}{
"id": 1,
"result": {
"ok": true
}
}inbox.reopen
Mark a message as open again.
Needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
host | path | yes | The host it came from, by its name or its id |
id | path | yes | The message's id on that host |
Result
| Field | Type | Description |
|---|---|---|
ok | boolean |
Errors
| Status | When |
|---|---|
| 404 | No such message |
{
"id": 1,
"op": "inbox.reopen",
"args": {
"host": "studio",
"id": 42
}
}{
"id": 1,
"result": {
"ok": true
}
}Types
The named types used on this page.
InboxMessage
A stored message: the host's message with where it came from.
A stored message: the host's message with where it came from.