Help articles

An article is the content unit customers read on your help center — a how-to, an FAQ answer, a troubleshooting guide. Articles carry an HTML body, a draft/published status, and per-visitor helpfulness and view counts.

One parent, never two

Every article is filed under exactly one parent:

• a category, via category_id — the usual case, and
• a collection, via collection_id — for a standalone topic that doesn't need a category.

Sending both, or neither, is a 422. The rule is enforced in the database itself, so an article can never end up in an ambiguous state.

Because nothing is denormalized, moving a category between collections can never leave an article's breadcrumbs stale — the collection is always resolved through whichever parent is set.

Public visibility

An article is visible on your public help center and in-app widget only when both conditions hold:

A published article with show_on_portal: false is effectively unlisted — useful for content you link to directly but don't want browsable.

The help article object

Returned by List. Retrieve returns these fields plus content, author_id, collection, category, and related_articles.

Example help article object

{
  "id": "aa1c3ef8-b8cd-cd15-01ba-77bb77bb77bb",
  "collection_id": null,
  "category_id": "884c3ef8-b8cd-cd15-01ba-44bb44bb44bb",
  "title": "Reset your password",
  "slug": "reset-your-password",
  "excerpt": "How to reset your password from the sign-in screen.",
  "status_code": "published",
  "show_on_portal": true,
  "favourite": false,
  "seq_number": "1000.0000",
  "helpful_count": 42,
  "not_helpful_count": 3,
  "view_count": 512,
  "published_at": "2026-08-02T11:00:00Z",
  "created_at": "2026-08-01T10:20:00",
  "updated_at": "2026-08-05T14:02:00"
}

Engagement metrics

helpful_count, not_helpful_count, and view_count are derived from the underlying vote and view records rather than stored as counters, and all three count distinct people:

• A visitor can vote helpful, switch to not-helpful, or retract — but never stack votes.
• A visitor re-reading an article never increments view_count twice.

These are read-only through the API. Votes and views are visitor actions recorded by the portal and widget; there is no endpoint to write them.

Related articles

Each article can carry a curated, ordered list of related articles, shown beneath it on the portal. Set the whole list at once with related_article_ids on create or update:

• The order you send is the order displayed.
• Every id must be an article in your organization, or the call fails with 400.
• On update, the field replaces the entire set. Send [] to clear it; omit it to leave it alone.
• Links to drafts and unlisted articles are kept but simply not surfaced publicly.

Content format

content is HTML — the same format the dashboard's rich-text editor produces. Send well-formed markup (<p>, <h2>, <ul>, <a>, <img>, <code>, and so on). There is no Markdown conversion; if you author in Markdown, render it to HTML before sending.

What you can do