Help Articles

Help Articles are ProxifAI’s content management system for customer-facing knowledge-base content — the help-center articles your customers (or internal users) read to find answers without filing a ticket. They’re distinct from the two other content surfaces in the platform:

Surface	Audience	Where it lives	Purpose
Documents	Team members	TipTap CRDT editor	Live-collaborative specs, RFCs, runbooks
Knowledge Base (AI)	AI agents	Vector index + Meilisearch	Embedding pipeline that powers chat retrieval
Help Articles	Customers	Public help center	Slug-published support content with feedback signals

Anatomy of an article

Field	Notes
title	Display title; one line
slug	URL-friendly path segment (how-to-add-a-domain); used for public URLs
content	Long-form Markdown body
categoryId	Optional FK to a KBCategory for organization
authorId	The org user who wrote it
status	draft / published / archived
viewCount	Auto-incremented on each public read
helpfulCount, notHelpfulCount	From the per-article feedback widget
publishedAt	Set when status flips to published

Status

Status	Meaning
draft	Editable, not yet visible to customers
published	Live on the help center; publishedAt is stamped on the transition
archived	Hidden from the public help center but kept in the DB for historical reference; reversible to published

Use the dedicated POST /api/v1/kb/articles/{id}/publish endpoint to flip from draft to published — it stamps publishedAt server-side rather than relying on a client-set timestamp.

Categories

KBCategory provides a tree-structured taxonomy:

Field	Notes
name	Display name (e.g. “Billing”, “Account Management”)
slug	URL segment for the category page
description	Optional long-form explainer shown at the top of the category page
parentId	Optional FK to another KBCategory — categories nest arbitrarily deep
sortOrder	Sibling ordering within a parent
articleCount	Computed; how many published articles roll up to this category (including descendants)

Categories don’t enforce any structure — articles can sit at the root or be nested several levels deep. Most help centers use 1-2 levels of nesting (e.g. “Account Management → Two-factor authentication”).

Feedback

Public readers can vote each article up or down via the POST /api/v1/kb/articles/{id}/feedback endpoint. The helpfulCount and notHelpfulCount fields aggregate those votes; sort the article-list response by either to find content that needs revisiting (high notHelpfulCount) or content worth promoting (high helpfulCount).

REST endpoints

All routes live under /api/v1/kb/:

Articles

Method · Path	Purpose
GET /api/v1/kb/articles	List with filters (status, categoryId, authorId, search)
POST /api/v1/kb/articles	Create — minimum is {title, slug}; defaults status=draft
GET /api/v1/kb/articles/by-slug/{slug}	Public lookup by slug — used by the help-center frontend
GET /api/v1/kb/articles/{id}	Read by ID with embedded category, author
PATCH /api/v1/kb/articles/{id}	Update fields
DELETE /api/v1/kb/articles/{id}	Soft-delete
POST /api/v1/kb/articles/{id}/publish	Flip to published, stamp publishedAt
POST /api/v1/kb/articles/{id}/feedback	Add a helpful/not-helpful vote (public-callable)

Categories

Method · Path	Purpose
GET /api/v1/kb/categories	List — embed parent and articleCount
POST /api/v1/kb/categories	Create — {name, slug, parentId?, sortOrder?}
GET /api/v1/kb/categories/{id}	Read
PATCH /api/v1/kb/categories/{id}	Update
DELETE /api/v1/kb/categories/{id}	Delete (children are reparented to null rather than cascading)

Common workflows

Author and publish a new article

# Create as draft
pfai api POST /api/v1/kb/articles \
  -d '{"title": "How to enable SSO", "slug": "enable-sso", "content": "# ...", "categoryId": "cat_abc"}'

# Edit, preview, then publish
pfai api POST /api/v1/kb/articles/{id}/publish

Trigger ticket auto-deflection

Use a trigger rule on the ticket.created event that runs an LLM step against the ticket subject + body, queries GET /api/v1/kb/articles?status=published&search=<terms>, and posts a “you might find these helpful” reply on the ticket before a human agent picks it up.

Surface most-viewed articles in a dashboard

# Top 10 most-viewed published articles
pfai api GET '/api/v1/kb/articles?status=published&sort=-viewCount&limit=10'

Tradeoffs and limits

• No version history. Editing a published article overwrites the content; there’s no rollback to a prior version. Make non-trivial edits in a draft copy if you need a review cycle.
• Markdown-only content. Unlike Documents, help articles don’t have the full TipTap editor — no Excalidraw, no Monaco code blocks, no embedded video. Plain Markdown rendered with Shiki for code blocks.
• No A/B testing. The publish flow is binary; you can’t run two variants and route traffic between them.
• CLI is REST-only. There’s no pfai article Cobra command yet — use pfai api against the routes above (or write a thin bash wrapper).

See also