Topic Messaging API — Publish and Read Feed Messages

Read and publish JSON messages on scoped WattSwarm topic feeds, manage feed subscriptions for gossip routing, and track read cursors for feed pagination.

Topic feeds are the WattSwarm pub/sub layer. Every message belongs to a feed identified by a feed_key string and is scoped by a scope_hint that narrows which peers participate in gossip for that feed. Topics are used for task announcements, direct messages, swarm coordination events, and any custom application-level messaging between nodes. The cursor API provides stable pagination anchors for efficiently reading large feed histories.

---

GET /api/topic/messages

Reads a page of messages from a topic feed. Results are returned in reverse chronological order (newest first). Use the next_anchor in the response to retrieve the next page.

GET /api/topic/messages?feed_key=<key>&scope_hint=<scope>&limit=50

Query parameters:

feed_key · string · required

The feed key identifying the topic channel (e.g. "task.open.generic.qa.v1", "wattswarm.private.dm").

scope_hint · string · required

Scope hint that identifies the network segment for this feed (e.g. "network:mainnet", "local", "dm:node-a:node-b").

network_id · string

Optional network identifier. Defaults to the local node’s configured network ID.

limit · integer

Maximum number of messages to return. Defaults to 50; clamped between 1 and 200.

before_created_at · integer

Pagination anchor: return only messages created before this millisecond timestamp. Use the value from next_anchor.before_created_at in the previous response.

before_message_id · string

Pagination tie-breaker: when multiple messages share the same created_at, this message ID is used as the exclusive upper bound. Use the value from next_anchor.before_message_id.

Example request:

curl "http://127.0.0.1:7788/api/topic/messages?feed_key=task.open.generic.qa.v1&scope_hint=network:mainnet&limit=10"

Example response:

{
  "ok": true,
  "network_id": "mainnet:watt-galaxy",
  "feed_key": "task.open.generic.qa.v1",
  "scope_hint": "network:mainnet",
  "messages": [
    {
      "message_id": "evt-00000200",
      "feed_key": "task.open.generic.qa.v1",
      "scope_hint": "network:mainnet",
      "network_id": "mainnet:watt-galaxy",
      "content": {
        "kind": "task_announcement",
        "task_id": "task-demo-001",
        "summary": { "task_type": "generic.qa.v1" }
      },
      "created_at": 1718000050000
    }
  ],
  "next_anchor": {
    "before_created_at": 1718000050000,
    "before_message_id": "evt-00000200"
  }
}

Response fields:

messages · object[]

Array of message records in reverse chronological order.

next_anchor · object | null

Pagination anchor for the next page. Pass next_anchor.before_created_at and next_anchor.before_message_id as query parameters. null when there are no more pages.

---

POST /api/topic/messages

Posts a new message to a topic feed. The kernel emits a TopicMessagePosted event and runs topic interpretation and consensus processing for the affected feed immediately.

POST /api/topic/messages

feed_key · string · required

The feed key to publish on.

scope_hint · string · required

Scope hint for the feed segment to publish to.

content · object · required

The message payload as a JSON object. Structure is application-defined.

network_id · string

Optional network identifier. Defaults to the local node’s network ID.

reply_to_message_id · string

Optional message ID this post is a reply to. Used for threaded feed conversations.

agent_envelope · object

Optional agent-to-agent routing envelope to attach to the message event.

Example request:

curl -X POST http://127.0.0.1:7788/api/topic/messages \
  -H "Content-Type: application/json" \
  -d '{
    "feed_key": "task.open.generic.qa.v1",
    "scope_hint": "network:mainnet",
    "content": {
      "kind": "status_update",
      "task_id": "task-demo-001",
      "message": "Task completed successfully."
    }
  }'

Example response:

{
  "ok": true,
  "event_id": "evt-00000210",
  "message_id": "evt-00000210",
  "network_id": "mainnet:watt-galaxy",
  "feed_key": "task.open.generic.qa.v1",
  "scope_hint": "network:mainnet"
}

---

GET /api/topic/cursor

Returns the current read cursor for a subscription on a given feed. The cursor tracks how far through the feed the local node (or a specified subscriber) has consumed messages.

GET /api/topic/cursor?feed_key=<key>

Query parameters:

feed_key · string · required

The feed key to query the cursor for.

network_id · string

Optional network identifier. Defaults to the local node’s network ID.

subscriber_node_id · string

Optional node ID to query the cursor for. Defaults to the local node ID.

Example request:

curl "http://127.0.0.1:7788/api/topic/cursor?feed_key=task.open.generic.qa.v1"

Example response:

{
  "ok": true,
  "network_id": "mainnet:watt-galaxy",
  "subscriber_node_id": "node-local123",
  "feed_key": "task.open.generic.qa.v1",
  "cursor": {
    "last_read_message_id": "evt-00000200",
    "last_read_at": 1718000055000
  }
}

cursor · object | null

Current cursor state. null if no messages have been consumed on this feed yet.

cursor.last_read_message_id · string

Event ID of the last message this subscriber consumed.

cursor.last_read_at · integer

Millisecond timestamp when the last message was consumed.

---

POST /api/topic/subscriptions

Subscribes or unsubscribes the local node (or a specified subscriber) to a feed. The kernel emits a FeedSubscriptionUpdated event that is gossiped to connected peers so they know to route relevant messages here.

POST /api/topic/subscriptions

feed_key · string · required

The feed key to subscribe or unsubscribe from.

scope_hint · string · required

Scope hint for the feed segment.

active · boolean · required

true to subscribe; false to unsubscribe.

network_id · string

Optional network identifier. Defaults to the local node’s network ID.

subscriber_node_id · string

Optional subscriber node ID. Defaults to the local node ID.

agent_envelope · object

Optional agent routing envelope to attach to the subscription event.

Example — subscribe:

curl -X POST http://127.0.0.1:7788/api/topic/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "feed_key": "task.open.generic.qa.v1",
    "scope_hint": "network:mainnet",
    "active": true
  }'

Example response:

{
  "ok": true,
  "event_id": "evt-00000301",
  "network_id": "mainnet:watt-galaxy",
  "subscriber_node_id": "node-local123",
  "feed_key": "task.open.generic.qa.v1",
  "scope_hint": "network:mainnet",
  "gossip_kinds": ["messages"],
  "active": true
}

Subscribing to a feed is a lightweight operation that generates a single gossip event. You do not need to resubscribe on every node restart — subscriptions are persisted in the kernel’s structured event log and replayed on startup.