Categories & streams

Every report lives in a stream, and every stream lives in a category. Those two levels are the whole navigation tree — the sidebar builds itself from them. This page covers managing them by hand and letting agents create them for you.

Reports live inside streams, inside categories, inside a workspace. Sources publish reports; users hold roles on the workspace.

The two levels

• Category — the first level of organization (e.g. Monitoring, Revenue). A category holds streams and nothing else.
• Stream — a feed inside a category (e.g. api-uptime, daily-mrr). Reports land in streams.

You need a category before you can create a stream. Deleting either one cascades (see Deleting below).

Names and slugs

Each category and stream has two identifiers:

• A name — the display label you see in the sidebar. Rename it any time.
• A slug — a lowercase, hyphenated key (api-uptime) derived from the name on first creation, or set by hand.

The slug is permanent. Renaming a category from Monitoring to Infra leaves its slug untouched, because the slug is the address agents post to. A stream slug is unique within its category — two categories can each have an uptime stream.

Pick slugs deliberately

You can rename freely, but you can’t change a slug after creation. Agents route by category-slug + stream-slug, so a slug change would break every source pointing at it.

Creating by hand

In the sidebar (editor role or higher):

• New category — the New category button at the top of the tree. Name it; the slug is generated for you, or expand the field to set your own.
• New stream — hover a category and click +. Same flow.
• Rename — right-click a category or stream → Rename.
• Reorder — drag categories within the workspace, or streams within their category. Order is yours; it persists for everyone.

Creating by agent (autocreate)

You rarely need to pre-build the tree. With autocreate on, a source that posts to a category/stream slug that doesn’t exist yet creates it on the way in, and it appears in the sidebar immediately. Point your agents at meaningful slugs and the structure assembles itself.

When an agent creates a category or stream, its name is derived from the slug (api-uptime → Api uptime). The moment you rename it yourself, PulseDeck marks the name as operator-set and later agent pushes never overwrite it. Your labels are safe.

Pointing an agent at a stream

To wire a source to a specific stream, right-click the stream → Copy agent instructions. That copies a ready-made snippet with the target category and stream slugs for the agent’s destination config. Because the snippet carries a registration token, this action sits at the source-management tier (admin or higher). See Sending reports for the full source-registration flow.

Deleting cascades

Deletion removes everything underneath:

• Delete a stream → the stream and all of its reports are removed. The category stays.
• Delete a category → the category, all of its streams, and all of their reports are removed.

There’s no undo. An empty stream is harmless — it just sits in the sidebar until you delete it — so there’s no need to prune streams that have stopped receiving reports unless you want to.

Who can manage structure

Creating, renaming, reordering, and deleting categories and streams requires the editor role or higher. Viewers see the tree but can’t change it. See Members & roles for the full table.

Next steps

• Sending reports — register a source and post into a stream.
• Dashboards — turn streams and metrics into a live view.
• Webhooks — forward matching reports to Slack, Discord, or your own API.