How HelpCCMS works

In-app help lives in your code as string literals, so a rewritten tooltip costs a commit and a deploy. HelpCCMS gives each piece of that text a Help key and serves the published version to your app.

Text that is the interface stays in your interface: button labels, field labels, the word on a tab. HelpCCMS holds text about the interface: tooltips, field help, error messages and other contextual help.

The loop

1. Your text goes into a collection. Write it there, or import what you have.
2. Each topic gets a Help key, the name your product asks for.
3. Publishing freezes a copy of what you wrote.
4. Your app requests a key and receives the published text as JSON.
5. You edit and publish again. The next request returns the new version, without a release.

Collection

A collection is what you publish. One product, one collection.

The collection id plus the base URL is what your application knows about HelpCCMS.

Topic

A topic is one answer, and a Help key addresses the whole of it. If a tooltip and a help panel need different amounts of text, write two topics.

A topic carries a title, a short description, and a type: task, concept, reference, troubleshooting or FAQ. The type records what kind of answer this is. It stays in HelpCCMS and is not part of the response.

Help key

The Help key is the address, in your own vocabulary:

settings.api-keys
billing.payment-failed
onboarding.first-run

A Help key is unique within a collection. Two topics on the same key answer 409, and neither is served: the wrong explanation is worse than none.

Keys compare exactly, capitals and dots included, so Billing.Payment-Status and billing.payment-status are two different keys.

A key can also name a role. A role holds the name of a UI element and the tooltip that explains it. The response has the same shape as a topic: title holds the term as it appears in the interface, and the body holds the explanation. Roles publish like topics.

External reference is a second field beside the Help key: free text for a component name, file path or ticket. Several topics can share a value, so you can group everything that belongs to one screen. Delivery answers on the Help key alone.

Publish

Publishing freezes a copy of the topic. That copy is what gets served, and what you type afterwards stays private until you publish again, so drafts never leave the editor.

Publish one topic or the whole collection. Withdrawing works the same way. The published state changes immediately; cached responses may remain visible for up to five minutes.

Deliver

GET https://www.helpccms.com/api/deploy/{collection}/{key}

{
  "key": "settings.api-keys",
  "title": "API keys",
  "short_desc": "One key per script, so you can withdraw one without breaking the rest.",
  "html": "<p>An API key lets a script talk to Acme on your behalf.</p>",
  "text": "An API key lets a script talk to Acme on your behalf.",
  "updated_at": "2026-09-06T16:53:36.910Z"
}

One body, rendered two ways: html for a panel, text for a native tooltip or a log line. short_desc is its own field, so you decide whether to show it.

Published help is public: your app can read it, and so can a search engine or an agent. The address goes in your front-end the way any other endpoint does.

Responses are cached at the edge for five minutes: a publish reaches your users within five minutes, and a key read a million times reaches the origin once per five minutes.

Every failure comes with a code. NOT_PUBLISHED and KEY_NOT_FOUND both arrive as a 404 and tell you whether the topic exists but is unpublished or no topic answers to that key. A duplicate key answers 409 with AMBIGUOUS_KEY.

To see every key a collection answers to:

GET https://www.helpccms.com/api/deploy/{collection}

Import what you already have

Your coding agent can collect the help already in your application.

The import format is JSON and the specification is on the developers page. Give it to your coding agent, import the file it produces, and those texts appear one for one as topics.

With everything in one place, differences in terminology, wording and tone are visible for the first time.

What the developer does once

This is the part people want to know before they start, so here it is plainly.

Put the collection id in your environment. Write one function that takes a key, requests that URL, and returns the response. Call it where you show help.

From then on, you can improve and publish the help without touching your repository.

One decision stays with you: the fallback when a request fails. A cached copy, a string in your code, or nothing at all is a choice about your own product.

← HelpCCMS