Tag articles with roles

Roles are how you partition your help center for different audiences. A SaaS product with developer docs, admin docs, and end-user docs lives more cleanly when each audience sees only their content. Roles make that possible.

Roles are visibility tags — they control what shows up when a customer browses the public help center. They don’t bias AI retrieval. AI agents (Capabilities, Sidekick, Web Chat, voice) ignore role tagging when retrieving Knowledge Base content. Within the Knowledge Base content available to a specialist, retrieval is based on relevance, not role. Agent Stack Knowledge Base category and subcategory scope can still limit which articles a specialist can retrieve.

When to use roles

• Your help center has clearly distinct audiences (developers vs. end users, admins vs. agents, sales reps vs. customers).
• You want to keep one Knowledge Base instead of running multiple help centers.
• The audiences would be confused by each other’s content (a developer doesn’t want to wade through “How to update your billing address”; an end user doesn’t want to see an OAuth scope reference).

If your audiences overlap heavily, skip roles. The simpler the navigation, the better.

Create a role

1. Go to Settings → Knowledge → Roles.
2. Click Add role.
3. Fill in:
   Name — what visitors see in the role switcher. “Developer”, “End user”, “Admin”.
   Slug — used in URLs (/role/developer). Auto-generated.
   Description — optional. Shown in the role grid block on the public site.
   Icon — optional. Renders in the role grid.
4. Click Create Role.

The role exists but no articles are tagged with it yet — so it’s effectively empty until you start tagging.

Tag an article with one or more roles

1. Open the article.
2. In the metadata panel, find Roles.
3. Click to add roles. An article can be tagged with multiple roles — useful when an article applies to several audiences.
4. Save.

An article tagged with developer and admin is visible when either role is selected on the public site. An article with no roles is left out of role-filtered views; it shows when no role is selected.

If the article’s category, subcategory, or placement won’t be reachable by any specialist’s Knowledge Base scope, the editor warns you before saving. That warning is about Agent Stack retrieval scope, not role visibility.

How visitors choose a role

Two patterns:

• Role grid / role bar block — Visitors land on a help center that shows a row or grid of role tiles (“I’m a developer”, “I’m an end user”). They click their role and the help center filters to that role’s articles.
• Direct role URL — A visitor lands on /role/developer (linked from your product or docs). The help center is pre-filtered.

Both are configured in the layout builder. Drop a Role Grid or Role Bar block onto the homepage; or link directly to /role/<slug> from your product UI.

What visitors see when filtered

With a role selected, the public help center shows:

• Articles tagged with that role.
• Not articles tagged with no role — untagged articles are left out of role-filtered lists.
• The full category list — categories aren’t narrowed by role.

Articles tagged with only other roles are hidden — they aren’t listed, but they still appear in search, and direct links to them resolve normally (so external links don’t break, but in-site navigation excludes them).

Visitors not filtered to any role see every published article, whether or not it has role tags.

What roles don’t do

• They don’t replace authentication. Anyone can switch to any role on the public site. Roles are about navigation, not access control. If you have content that requires authentication, gate it elsewhere.
• They don’t change AI retrieval. Capabilities, Sidekick, Web Chat, and voice ignore roles when retrieving Knowledge Base content. An article tagged admin can still be cited by AI when it’s the most relevant answer to a customer’s question, as long as that article is inside the specialist’s Agent Stack Knowledge Base category or subcategory scope.
• They don’t override Agent Stack Knowledge Base scope. Category and subcategory scope can still restrict which articles a specialist can retrieve. If an article is placed somewhere no specialist can reach, the editor warns you before saving.
• They don’t apply to the Handbook. The Handbook has its own access-rule system. See What is the Handbook?.

Bulk-tagging articles with roles

Bulk role assignment isn’t available in the bulk-edit UI. For now, you can:

• Tag articles individually as you write them.
• Push articles via the external KB API, which accepts roleIds (role UUIDs or slugs) on article create, update and import, and sets an article’s roles with PUT /api/v1/kb/articles/{id}/roles. A tenant API key with the knowledge:write scope is enough.

If you have a large set of existing articles to tag in one go, the fastest path today is the in-app editor article-by-article.

Common patterns

• Three-role help centers. “End user”, “Admin”, “Developer” — the most common SaaS pattern. End-user articles untagged by default (so they show only when no role is selected); admin and developer articles tagged.
• Internal vs. external. “Customer”, “Reseller”, “Partner” — different audiences with different terminology.
• Hide internal content from a public role-grid. Tag an article with internal-team only; visitors with no role filter still won’t see it because the universal pool excludes role-tagged articles only when a role filter is active.

A reminder

Roles are visibility, not retrieval bias. If you find yourself thinking “let’s tag this with developer so the AI prefers it” — that’s not what roles do. The AI retrieves on relevance, not role overlap. If retrieval feels off for a specific audience, the right fix is better article content, better keywords, or splitting the article — not role tagging.