Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt

Use this file to discover all available pages before exploring further.

Feeds are project-level JSON distribution channels. Use them when you want to publish structured data once and have MeshAgent deliver it into room storage in one or more rooms. A feed is not a queue and it does not execute work inside a room. In MeshAgent, the feed is the project-side source of messages, and feed subscriptions define which rooms and storage paths receive those messages.

​
How feeds work

  • Create a feed at the project level with a name, visibility, and optional message schema.
  • Add one or more subscriptions. Each subscription points to one room and one storage path prefix such as feeds/orders/.
  • Publish JSON messages to the feed one at a time or as a batch.
  • MeshAgent fans those messages out to every subscription and writes them into room storage as .jsonl files.
  • Delivery is batched for performance. A message can take up to about a minute to appear in room storage.
The key distinction is that a feed does not deliver directly into room chat or a room queue. It writes structured files into room storage so agents, services, or operators in that room can consume them there.

​
What a subscription does

A feed subscription is the delivery rule for one room.
  • It connects one feed to one room.
  • It writes into one storage path prefix inside that room.
  • One feed can have multiple subscriptions, which lets you publish once and land the same data in multiple rooms.
  • The room and path are fixed after creation. If you want a different destination, recreate the subscription.
Use / if you want the room root. For normal usage, pick a dedicated prefix such as feeds/orders/ or imports/events/ so feed output stays easy to inspect.

​
When to use feeds

Use feeds when you want to:
  • distribute structured JSON events into room storage
  • import external datasets or event streams into a room
  • fan the same data out to multiple rooms without writing your own delivery code
  • keep project-managed ingestion separate from room-local consumption
Typical examples include syncing business events into ops rooms, importing records for an agent to process later, or delivering the same event stream into multiple rooms that each run their own analysis.

​
When not to use feeds

Use the nearby MeshAgent feature that matches the kind of delivery you need:
NeedUse
Land structured JSON files in room storageFeeds
Enqueue work for agents or workers to process immediatelyQueues or Scheduled Tasks
Route inbound email into a roomMailboxes
Accept HTTP traffic or external webhooks into a roomRoutes
Send MeshAgent events out to your own systemsWebhooks
If the consumer expects a queue message, use a queue. If the consumer expects files in room storage, use a feed.

​
Create a feed

You can manage feeds from MeshAgent Studio, the CLI, or the SDKs. In Studio:
  • Open the project’s Feeds page to create and manage feeds for the project.
  • Open Feeds… from a room menu when you want to see visible feeds for that room and manage that room’s subscriptions.
From the CLI, create the feed first: 
meshagent feed create \
  --name orders \
  --description "Order events for room imports" \
  --visibility project \
  --message-schema-file order-event.schema.json
Then attach a room subscription: 
meshagent subscription create \
  --feed-id FEED_ID \
  --room ops-room \
  --path feeds/orders/
Choose visibility carefully when you create the feed:
  • public: anyone who can see the feed can subscribe a room to it
  • project: any project member can read it and attach room subscriptions
  • private: only project developers can read it or manage subscriptions
Visibility is a creation-time choice. In Studio and the public SDK surface, you do not change it later.

​
Validate messages with a schema

A feed can define an optional JSON schema for the messages it accepts.
  • If you leave the schema empty, the feed accepts any valid JSON value.
  • If you add a schema, MeshAgent validates every published message before delivery.
  • If a message does not match, the publish call fails and nothing is delivered for that message.
This is useful when multiple tools or services publish into the same feed and you want a single contract for what is allowed to enter room storage.

​
Publish messages

Publish one JSON message: 
meshagent feed send FEED_ID \
  --message '{"id":123,"status":"paid"}'
Publish a batch from a JSONL file: 
meshagent feed send-batch FEED_ID \
  --jsonl-file orders.jsonl
Each line in the JSONL file is treated as one message. MeshAgent then batches feed delivery into .jsonl files in room storage. Paused feeds reject publishes and subscription changes. This gives you a clean way to stop new data from landing while you review or reconfigure downstream consumers.

​
Use feeds from the SDKs

The SDKs mirror the same lifecycle as Studio and the CLI: create the feed, add subscriptions, then publish messages. 
feed = await client.create_feed(
    project_id=project_id,
    name="orders",
    description="Order events for room imports",
    visibility="project",
)

await client.create_feed_subscription(
    project_id=project_id,
    feed_id=feed.id,
    room="ops-room",
    path="feeds/orders/",
)

await client.publish_feed_message(
    project_id=project_id,
    feed_id=feed.id,
    message={"id": 123, "status": "paid"},
)

​
Permissions

  • Developers create, update, delete, pause, resume, and publish feeds.
  • Feed visibility controls who can read a feed and who can attach room subscriptions to it.
  • Creating or changing a subscription still requires room-level permission on the target room.
  • Project members only see public and project feeds in shared feed listings.