HelpCenter.io

Headline traffic, ratings and authoring activity for the connected HelpCenter.io help center, each compared against the equally-long window before it. Read-only. This is the "how are we doing" and "what changed since last month" call. COST AND RATE LIMIT: this is an expensive query, and the three analytics tools share a limit of 6 requests per minute per API key — far below the other read tools. The underlying figures are recomputed only once a day, so asking again in a few seconds returns identical numbers at full cost. Read once, keep the answer, and do NOT poll or retry in a loop. If you are refused with a rate-limit error, stop rather than backing off and retrying. Leave `from`/`to` unset unless the user asked about a specific period: the default window is the trailing 7 days, is served from a pre-computed cache rather than the warehouse, and is the right answer for a general question. Maximum window is 92 days; wider is refused. Args: - from (string, optional): YYYY-MM-DD start of the window. - to (string, optional): YYYY-MM-DD end, inclusive. Defaults to today. - lang (string, optional): restrict to one enabled language. - response_format ('markdown' | 'json'): default 'markdown'. Returns: { range: { from, to, days }, summary: { traffic: { article_views, visitors, searches, article_views_per_visitor }, ratings: { total }, activity: {...}, totals: { published_articles } } }. Each traffic metric is { count, change_pct } where change_pct compares against the immediately preceding window of the same length. `summary.traffic.searches.count` is the authoritative search volume — helpcenter_get_search_queries deliberately reports no totals of its own. To act on what this shows: use helpcenter_get_search_queries to find what people cannot find, and helpcenter_get_content_performance to find which existing articles are failing. Errors: 429 if the shared analytics rate limit is exceeded — stop, do not retry. 503 if the analytics backend is temporarily unavailable; that is not your request's fault and retrying immediately will not help.

helpcenter_get_analytics_summary

Read one article by id from the connected HelpCenter.io help center. Use this when you already know the id — after a search, or before editing — instead of paging through helpcenter_list_articles to find it again. Read-only. Also the way to check whether an article has unpublished staged edits waiting on it: the response carries has_staged_changes, staged_locales and staged_updated_at. Check that before a live update, or your edit and somebody else's staged work will collide. Args: - article_id (number, required): id of the article. - response_format ('markdown' | 'json'): default 'markdown'. Returns: { status: "success", article: {...} } — the full article, including per-language title/content/slug, categories, external_id, and the staged-changes flags. Errors: 404 if the id is unknown OR belongs to another help center — the endpoint deliberately does not distinguish the two, so a 404 is not proof the article does not exist somewhere else.

helpcenter_get_article

Read one article's comment conversation, threaded — replies nested under the comment they answer, to any depth. Read-only. Use this when the question is about a specific article ("what are people confused about on the SSO page?"); use helpcenter_list_comments when it is about the help center as a whole. PRIVACY — identical to helpcenter_list_comments: - Emails are REDACTED unless include_email is set (write-scoped key only); an absent 'email' does not mean the reader had none. - IP addresses are NEVER returned. - Internal team notes are excluded at EVERY nesting depth, so a thread can be shorter here than the team sees in the dashboard. Args: - article_id (number, required): the article whose conversation to read. - status ('pending' | 'published' | 'unpublished' | 'deleted' | 'all', optional): default 'all'. Filters the WHOLE thread, not just its roots — asking for 'published' will not hand you a pending reply nested under an approved question. - lang (string, optional): language code. Also applies at every depth. - order ('asc' | 'desc', optional): default 'asc', oldest first — how a conversation reads. - include_email (boolean, optional): see PRIVACY above. - response_format ('markdown' | 'json'): default 'markdown'. Returns: { status, article: { id, title }, comments: [ { id, comment, author, status, replies: [...] } ], meta: { threads_count, comments_count } }. threads_count counts top-level comments; comments_count counts every comment in the thread. Errors: 404 if the article id is not in this help center; 403 for include_email on a read-scoped key.

helpcenter_get_article_comments

Per-article views and ratings for the connected HelpCenter.io help center. This is the "which articles should I fix" call. Read-only. COST AND RATE LIMIT: this is an expensive query, and the three analytics tools share a limit of 6 requests per minute per API key — far below the other read tools. The underlying figures are recomputed only once a day, so asking again in a few seconds returns identical numbers at full cost. Read once, keep the answer, and do NOT poll or retry in a loop. If you are refused with a rate-limit error, stop rather than backing off and retrying. Leave `from`/`to` unset unless the user asked about a specific period: the default window is the trailing 7 days, is served from a pre-computed cache rather than the warehouse, and is the right answer for a general question. Maximum window is 92 days; wider is refused. IMPORTANT — an article that got NO views in the window has no row here at all. The pipeline records views, not their absence. So 'sort=views_asc' gives you the least-read of the articles that WERE read, not the ones nobody opened; to find those, call helpcenter_list_articles and subtract the ids this returns. The response carries `excludes_never_viewed: true` as a reminder. Args: - sort ('views_desc' | 'views_asc' | 'rating_asc', optional): default 'views_desc'. Use 'rating_asc' for "what should I fix" — it puts the worst-rated first and breaks ties towards the most-read article, because a badly-rated page nobody visits matters less than one everybody lands on. - category_id (number, optional): restrict to one category belonging to this help center. - limit (number, optional): items per page, 1-100 (default 100). - page (number, optional): page number (default 1). - from / to / lang (optional): see above. - response_format ('markdown' | 'json'): default 'markdown'. Returns: { range, excludes_never_viewed, articles: [{ article_id, title, slug, status, views_in_range, total_views, ratings: { love_pct, thumbs_up_pct, thumbs_down_pct }, updated_at, _links: { view } }], meta }. Ratings are percentage SHARES of the feedback an article received, not counts — one thumbs-down reads as 100%. Weigh them against views_in_range before acting. Having found a weak article, fix it with helpcenter_stage_article_changes (edit privately, then publish) or helpcenter_update_article (visible immediately). Errors: 429 if the shared analytics rate limit is exceeded — stop, do not retry. 422 if category_id belongs to a different help center. 503 if the analytics backend is temporarily unavailable.

helpcenter_get_content_performance

What visitors searched for in the connected HelpCenter.io help center, and what they did not find. Read-only. START HERE when the question is "what content is missing?", "what should I write next?", or "why are customers still contacting support?". The `content_gaps` list is close to a literal backlog of articles that do not exist yet, ranked by how many people wanted them — it is the single most actionable thing this API returns, and the natural input to helpcenter_create_article. COST AND RATE LIMIT: this is an expensive query, and the three analytics tools share a limit of 6 requests per minute per API key — far below the other read tools. The underlying figures are recomputed only once a day, so asking again in a few seconds returns identical numbers at full cost. Read once, keep the answer, and do NOT poll or retry in a loop. If you are refused with a rate-limit error, stop rather than backing off and retrying. Leave `from`/`to` unset unless the user asked about a specific period: the default window is the trailing 7 days, is served from a pre-computed cache rather than the warehouse, and is the right answer for a general question. Maximum window is 92 days; wider is refused. Args: - limit (number, optional): rows per list, 1-50 (default 20). Raising it is free — these read pre-aggregated daily tables, so the same data is scanned either way. Ask for more when building a content plan. - from / to / lang (optional): see above. - response_format ('markdown' | 'json'): default 'markdown'. Returns: { range, content_gaps: [...], frequent_queries: [...], common_terms: [...], meta: { limit, lists_are_top_n } }. Each gap row is { query, searches, unique_visitors, zero_result_searches, no_click_searches, failed_searches, failure_rate, reason, last_searched_at, top_hit, article_clicked }. The two failure modes need DIFFERENT fixes, so read `reason`: - '0 results' — nothing matched. Write the article. - 'no click' — results came back and nobody opened one. The article probably exists but does not look like the answer; fix its title and opening lines rather than writing a new one. - 'mixed' — both happened across different searches of the same query. Two things not to get wrong: - Every list is a TOP-N, not a complete list. `limit` rows of content_gaps means "the N worst gaps", NOT "there were N gaps". Never state or infer a total from it. - There are NO search totals here. Use `traffic.searches` from helpcenter_get_analytics_summary if you need volume. Deriving one from these truncated lists would produce a number that disagrees with the real one. `common_terms` are single words pulled out of queries, so they overlap with the query rows and the two lists do not sum to anything. Terms spot a topic; queries are what you write an article from. Privacy: everything here is aggregated. No visitor identifiers, IP addresses or per-search rows are available through this API at all. Errors: 429 if the shared analytics rate limit is exceeded — stop, do not retry. 503 if the analytics backend is temporarily unavailable.

helpcenter_get_search_queries

Read the unpublished staged edits waiting on an article. Staged changes let you edit a PUBLISHED article without readers seeing it, then release it deliberately. Staged content is invisible to everything public: the rendered help center, sitemap, site search, the widget, the AI answer path, and this API's read endpoints. Staged versions are held per article AND per language, so an English hot fix is never held back by an in-progress Portuguese translation. Call this before staging your own edit, to see whether somebody is already mid-change, and to collect the `etag` you will pass back as an optimistic lock. Args: - article_id (number, required). - locale (string, optional): limit to one language; omit for every staged language. - response_format ('markdown' | 'json'): default 'markdown'. Returns: the staged version(s), each with { locale, fields, release_translation, etag, base_signature, updated_at }. `fields` holds only what has actually been staged — an omitted field is not staged, not staged-as-empty. Errors: 404 if the article is unknown, belongs to another help center, or has nothing staged.

helpcenter_get_staged_changes

List the archived previous versions of an article, so a past wording can be restored. Every publish archives the version it replaced. Read-only. Args: - article_id (number, required). - response_format ('markdown' | 'json'): default 'markdown'. Returns: { status: "success", versions: [{ id, locale, title, created_at, ... }] }. Pass a version id to helpcenter_restore_article_version. Only the last 20 snapshots per article per language are kept; older ones are pruned. History starts accruing when staged changes are enabled for the site, so an article published before that legitimately has an empty history — that is not an error. Errors: 404 if the article is unknown or belongs to another help center.

helpcenter_list_article_versions

List the help center's published design versions, newest first, marking the one that is live — with when, by whom and the publish note. Use it to find a version to bring back with helpcenter_restore_template_version. Args: - response_format ('markdown' | 'json'): default 'markdown'.

helpcenter_list_template_versions

List the ready-made themes a help center can start from, or describe one in full. A help center's design is its v2 template: theme tokens (colours for light and dark mode, fonts, radius, density), six page kinds (home, category, article, search, contact, notFound), each built from six regions (header, hero, sidebar, main, footer, utility) holding ordered components, plus a global navigation menu, custom CSS and scripts. You edit a DRAFT — the same draft the dashboard's Template Editor opens, with a live preview — and nothing reaches visitors until helpcenter_publish_template. Only v2 help centers can be edited: a classic (v1) one answers template_migration_required, and migrating is the owner's decision, made in the dashboard. Use it when the customer wants a new look, or a starting point to customize from. Each theme has a key, a summary, what it suits, its palette and fonts; the one the draft started from is marked current. Pass `theme` to see what each page of that theme is built from and which sections applying it would change. Args: - theme (string, optional): a theme key to describe in full. - response_format ('markdown' | 'json'): default 'markdown'. Returns: the gallery, or one theme with changed_sections. Apply one with helpcenter_apply_template_theme.

helpcenter_list_template_themes

Read the private editorial notes the help-center's team has left on an article in the HelpCenter.io editor. This is how you pick up human feedback on a draft: each note is anchored to a specific passage, so it tells you WHICH sentence to change, not just that something is wrong. PRIVATE — these notes are written by the help-center's own team and are never shown to readers. Use them to decide what to change in the article. Do NOT quote or paraphrase a note into any reader-facing text: not into an article body, and never into helpcenter_reply_to_comment. A note may say precisely what the team has decided NOT to say publicly. These are NOT reader comments. Visitor comments on the published article are a different tool (helpcenter_get_article_comments) and the two never return each other's content. Args: - article_id (number, required): the article whose notes to read. - include_resolved (boolean, optional): also return threads already marked done. Off by default — the question this answers is what is still being asked of the draft. - lang (string, optional): language code; notes are per-language like the draft. - response_format ('markdown' | 'json'): default 'markdown'. Returns: { article, notes: [ { id, note, anchor: { mark_id, quote }, author, resolved, replies: [...] } ], meta: { threads_count, open_count, includes_resolved } }. Errors: 403 'insufficient_scope' if the credential lacks the notes.read scope — content access does NOT imply it, and an API key holds it only if it was issued with it, so this is fixed by provisioning a new key, not by retrying. 403 'notes_forbidden' if the account behind the credential can no longer reach team comments in the dashboard. 404 if the article is not in this help center.

helpcenter_list_article_notes

List and browse a HelpCenter.io help center's articles, optionally filtered by category and ordered by views. Use this to browse "what's in category Y" or "the most-viewed articles" rather than to search for specific text (use helpcenter_search_articles for that). Read-only. Paginated. Args: - category_id (number, optional): restrict to one category id. - order_by ('views', optional): only 'views' is supported; omit for default (recently updated). - order_type ('asc' | 'desc', optional): sort direction when order_by is set (default 'desc'). - lang (string, optional): language code for returned text (defaults to the site default). - limit (number, optional): items per page, 1-100 (default 100). - page (number, optional): page number (default 1). - response_format ('markdown' | 'json'): default 'markdown'. Returns: { total, count, page, per_page, total_pages, has_more, items } — items are full article objects (see helpcenter_search_articles). Errors: auth error if the key is missing/invalid; validation error if category_id is not a category of this site.

helpcenter_list_articles

List the categories of the connected HelpCenter.io help center. Read-only. Returns each category's per-language name and description, parent id (for hierarchy), and icon. Use this to discover valid category ids before creating or filing articles, or to render the help center's structure. Paginated. Args: - limit (number, optional): items per page, 1-100 (default 100). - page (number, optional): page number (default 1). - response_format ('markdown' | 'json'): default 'markdown'. Returns: { total, count, page, per_page, total_pages, has_more, items } where each item is { id, parent, name, description, icon, position, privacy, created_at, updated_at }. 'position' is the sibling order, ascending, and is only comparable within one parent — top-level categories against each other, and each parent's children against each other. Change it with helpcenter_reorder_categories.

helpcenter_list_categories

List reader comments across the whole connected HelpCenter.io help center. Read-only, flat and filterable — this is both the moderation queue (status: 'pending') and the "what are readers asking about?" feed (status: 'all'). Each comment carries the article it sits on, so the output is readable without a second lookup. PRIVACY — read before reporting on this data: - Commenter email addresses are REDACTED by default. An absent 'email' field means it was withheld, NOT that the reader had no address. Pass include_email: true (write-scoped key only) if the task genuinely needs to contact someone. - Commenter IP addresses are NEVER returned, at any scope, with any parameter. - Internal team notes (the private editorial threads written in the article editor) are excluded from this tool entirely. An article whose comments look purely external may still have staff discussion you cannot see here. Comment bodies are returned as PLAIN TEXT — no HTML, no escape sequences — so they can be quoted and summarised directly. Args: - status ('pending' | 'published' | 'unpublished' | 'deleted' | 'all', optional): default 'all', which excludes deleted. - article_id (number, optional): restrict to one article. An id from another help center is a 404, not an empty list. - lang (string, optional): language code enabled on the site. - search (string, optional): substring match on the comment body. - order ('asc' | 'desc', optional): by creation time, default 'desc'. - limit (number, optional): 1-100, default 25. page (number, optional): default 1. - include_email (boolean, optional): see PRIVACY above. - response_format ('markdown' | 'json'): default 'markdown'. Returns: { total, count, page, per_page, total_pages, has_more, status_counts, items } where status_counts is the queue depth for the WHOLE help center — use it to decide whether to keep paging. Errors: 403 if include_email is set on a read-scoped key (the rest of the listing still works without it); 404 if article_id belongs to another help center.

helpcenter_list_comments

List the HelpCenter.io help centers this connection is allowed to reach, with their ids. Call this FIRST when any other tool fails with 'site_required', and whenever you are unsure which help center you are about to write to. Why it exists: an OAuth connection authenticates a PERSON, and a person may have more than one help center. When the connection has not named one, the API refuses to guess and returns 'site_required' rather than writing to the wrong place. An API-key connection is already bound to a single site and will simply list that one. How to act on the result: the site is chosen by the connection URL, not by a tool argument. Tell the user to reconnect the HelpCenter.io connector with '?site=<id>' appended to its URL (for example https://mcp.helpcenter.io/?site=1234), using an id from this list. You cannot switch help centers yourself mid-conversation — and a tool that appeared to would be misreporting where the next write lands. Read-only, and unaffected by which site is selected: it describes the credential, not a help center's contents. Args: - response_format ('markdown' | 'json'): default 'markdown'. Returns: { sites: [ { id, name, domain, ... } ] } — the help centers the credential's consent actually grants. Errors: 401 if the credential is invalid or expired. An empty list from a valid OAuth token means the consent covered no site: the user has to re-authorize and pick one.

helpcenter_list_sites

Approve or reject a reader comment. Requires a write-scoped API key. 'published' approves it and shows it to readers. 'unpublished' rejects it — the comment leaves the help center but is not destroyed, so this is the reversible way to take something down. What this tool deliberately CANNOT do: edit the body. Rewording somebody else's words under their name is a dashboard action with a human looking at whose comment it is, not an API one. Side effect worth knowing: approving a REPLY emails the person being replied to, exactly as approving it in the dashboard does. That send is idempotent per reply, so re-approving something already published mails nobody twice. Args: - comment_id (number, required): from helpcenter_list_comments or helpcenter_get_article_comments. - status ('published' | 'unpublished', required). Returns: { status: "success", message, comment: {...} } with the updated comment. Errors: 403 if the key is read-scoped; 404 if the comment is not in this help center, is an internal team note (which this API never exposes or touches), or has been DELETED — a deleted comment is off the help center whatever its status says, so it must be restored from the dashboard before it can be moderated; 422 for any status other than the two above.

helpcenter_moderate_comment

Apply staged changes to the live article, making them visible to readers. Staged changes let you edit a PUBLISHED article without readers seeing it, then release it deliberately. Staged content is invisible to everything public: the rendered help center, sitemap, site search, the widget, the AI answer path, and this API's read endpoints. Staged versions are held per article AND per language, so an English hot fix is never held back by an in-progress Portuguese translation. Publishing archives the outgoing live values (so it is reversible via helpcenter_list_article_versions), applies the staged fields, creates a slug redirect if the slug changed, re-indexes for search, refreshes AI embeddings, and deletes the staged copy. Args: - article_id (number, required). - locale (string, optional): publish only this language; omit to release every staged language at once. - force (boolean, optional): see below. Do not set it reflexively. Returns: { status: "success", published_locales: [...], article: {...} }. Errors: 409 BASE_CHANGED means somebody edited the LIVE article after your edits were staged, and publishing would lose their change. The check is per field and idempotent-aware, so it only fires when something would actually be lost. Three ways out: re-read the article and re-stage on top of the newer live version; discard your staged copy; or repeat with force: true to overwrite their edit deliberately. Also 422 ARTICLE_UNPUBLISHED if the article has since been taken down (staged work is kept — republish the article and it becomes publishable again), and 422 if sibling languages disagree on a shared field.

helpcenter_publish_staged_changes

Put the draft live: every visitor sees the new design from now on. Records a version (restorable later) and starts a fresh draft from it — exactly the Template Editor's Publish button. A help center's design is its v2 template: theme tokens (colours for light and dark mode, fonts, radius, density), six page kinds (home, category, article, search, contact, notFound), each built from six regions (header, hero, sidebar, main, footer, utility) holding ordered components, plus a global navigation menu, custom CSS and scripts. You edit a DRAFT — the same draft the dashboard's Template Editor opens, with a live preview — and nothing reaches visitors until helpcenter_publish_template. Only v2 help centers can be edited: a classic (v1) one answers template_migration_required, and migrating is the owner's decision, made in the dashboard. This is the ONE template call that changes the live help center. Publish only when the customer has asked you to — ideally after they reviewed the draft in the Template Editor (the customizer link from helpcenter_get_template). Pass the etag they reviewed, so a draft that changed after their review is refused rather than published unseen. Args: - message (string, optional): a note for the version history, e.g. 'Brand refresh'. - etag (string, optional): the reviewed draft's etag. Returns: the published version and the new draft status. Errors: 409 nothing_to_publish when the draft matches the live design; 412 stale_draft when the draft changed after the etag.

helpcenter_publish_template

Set the reading order of the articles inside one category. Requires a write-scoped API key. Args: - category_id (number, required): the category whose articles are being ordered. - articles (array, required): the articles in the order you want them, as [{ id }] or [{ id, position }]. Omit 'position' on an entry and it takes its place in the list. CHECK 'order_visible' IN THE RESPONSE. A help center only displays this order when its category pages are set to sort articles by "Custom"; under any other sort the order is stored but never shown, and the call still succeeds. The response reports order_visible (boolean), article_sort (the sort actually in effect) and, when it is not custom, a 'hint' naming the setting to change. This tool deliberately does not change that setting for you — on a Template Editor v2 site that would mean publishing the site's template, shipping whatever unfinished design edits the customer had open. Articles you do not list are left where they are. Ids that are not in the category are returned in skipped_article_ids rather than silently written. Returns: { status: "success", updated_count, skipped_article_ids, order_visible, article_sort, article_sort_source, hint }. Errors: 403 if the key is read-scoped; 404 if the category is not in this help center.

helpcenter_reorder_category_articles

Set the order of categories in the HelpCenter.io help center bound to your API key, in one call. Requires a write-scoped API key. Prefer this over repeated helpcenter_update_category calls: an information architecture is decided all at once, and one call leaves no visibly half-sorted tree in between. Args: - categories (array, required): the categories in the order you want them, as [{ id }] or [{ id, position }]. Omit 'position' on an entry and it takes its place in the list. Order is per SIBLING GROUP — top-level categories sort against each other, and each parent's children against each other — so one payload may freely mix levels. It does not change any category's parent; use helpcenter_update_category's parent_id for that. Returns: { status: "success", updated_count, categories: [...] } in the new order. Errors: 403 if the key is read-scoped; 422 if any id is not a category of this help center.

helpcenter_reorder_categories

Answer a private editorial note on an article — "rewrote the second paragraph and staged it for review". Stays internal: the reply joins the team's thread in the editor and is never shown to readers. Attributed to the account the credential authenticates as; there is no author field. PRIVATE — these notes are written by the help-center's own team and are never shown to readers. Use them to decide what to change in the article. Do NOT quote or paraphrase a note into any reader-facing text: not into an article body, and never into helpcenter_reply_to_comment. A note may say precisely what the team has decided NOT to say publicly. The natural pairing is with the staged-changes tools: revise the article with helpcenter_stage_article_changes (which readers cannot see), then say so here, then resolve. That way a human still decides what goes live. NOT IDEMPOTENT: calling this twice posts two replies. Read the thread back with helpcenter_list_article_notes before retrying. Args: - article_id (number, required), note_id (number, required): from helpcenter_list_article_notes. - note (string, required): the reply body, 1-5000 characters, plain text. Returns: { status: "success", note: {...} } with the thread including your reply. Errors: 403 'insufficient_scope' without the notes.write scope (separate from content.write, and from notes.read); 403 'notes_forbidden' if dashboard access to team comments has been lost; 404 if the note is not on this article — including when the id belongs to a READER comment, which this surface never touches.

helpcenter_reply_to_article_note

Post a comment on an article — as a reply to an existing comment, or as a new top-level one. Requires a write-scoped API key. The reply is attributed to the user the API key was issued to; there is no author field to set, which is what makes it impossible to post under a reader's name. It publishes immediately and is visible on the article to readers, and the person being replied to is emailed. NOT IDEMPOTENT: calling this twice posts two comments. There is no external_id equivalent here, so re-running a failed batch will duplicate. Read the thread back with helpcenter_get_article_comments before retrying. The body is PLAIN TEXT. HTML is not interpreted — it renders as the characters it is made of — so send prose, not markup. Args: - article_id (number, required): the article to comment on. - comment (string, required): the body, 1-5000 characters, plain text. - parent_id (number, optional): the comment being replied to. Must be a comment on THIS article. Omit for a new top-level comment. - lang (string, optional): defaults to the parent comment's language, or the site's default. Returns: { status: "success", message, comment: {...} } with the created comment. Errors: 403 if the key is read-scoped; 404 if the article is not in this help center, or parent_id is not a comment on it (including when parent_id names an internal team note); 422 if the body is missing or over 5000 characters.

helpcenter_reply_to_comment

Mark an editorial note thread as dealt with. The highlight disappears from the article in the editor and the note stops asking for attention. A resolved thread stays readable via helpcenter_list_article_notes with include_resolved: true, and resolving twice is not an error. Resolving changes the thread state and removes it from the active review queue. Resolve a note when you have ACTUALLY addressed it — made the change, or replied explaining why not. Resolving one you have only read hides a human's feedback from them. Args: - article_id (number, required), note_id (number, required). Returns: { status: "success", message, id }. Errors: 403 'insufficient_scope' without the notes.write scope; 403 'notes_forbidden' if dashboard access to team comments has been lost; 404 if the note is not on this article.

helpcenter_resolve_article_note

Roll a live article back to a previously published version. Takes a version id from helpcenter_list_article_versions. The restore is itself archived, so it can be rolled forward again — this is reversible, but it DOES change what readers see immediately. Args: - article_id (number, required). - version_id (number, required): from helpcenter_list_article_versions. Returns: { status: "success", article: {...} } with the restored live article. Errors: 403 if the key is read-scoped; 404 if the article or version is unknown or belongs to another help center.

helpcenter_restore_article_version

Load an earlier published design into the DRAFT, replacing the draft's current content — to undo a change, or bring back a previous look. It does NOT go live until you publish it (unlike the Template Editor's one-click revert), so the customer can review it first. Unpublished draft edits are replaced. Args: - version_id (number): from helpcenter_list_template_versions. - etag (string, optional): refuse if the draft changed since you read it. Returns: the draft status. Errors: 404 version_not_found.

helpcenter_restore_template_version

Full-text search a HelpCenter.io help center's articles by query string, returning ranked matches. This performs keyword search (Meilisearch-backed) over published article titles and content for the connected help center. Use it to answer "find the article about X" intents. It is read-only and does not modify anything. For browsing by category rather than searching, use helpcenter_list_articles. Args: - query (string, required): search text matched against titles and content. - lang (string, optional): language code to search within (defaults to the site default). - category_id (number, optional): restrict to one category id. - limit (number, optional): items per page, 1-100 (default 100). - page (number, optional): page number (default 1). - response_format ('markdown' | 'json'): default 'markdown'. Returns: a payload with { total, count, page, per_page, total_pages, has_more, items }, where each item is a full article (id, per-language title/slug/content, category_id, categories, type, published, visibility, views, ratings, timestamps). Errors: returns an auth error if the key is missing/invalid; a validation error if category_id is not a category of this site.

helpcenter_search_articles

Save an edit to a published article WITHOUT readers seeing it. Nothing goes live until you call helpcenter_publish_staged_changes. Staged changes let you edit a PUBLISHED article without readers seeing it, then release it deliberately. Staged content is invisible to everything public: the rendered help center, sitemap, site search, the widget, the AI answer path, and this API's read endpoints. Staged versions are held per article AND per language, so an English hot fix is never held back by an in-progress Portuguese translation. Prefer this over helpcenter_update_article whenever the article is already published and the change should not appear the instant you write it — a rewrite in progress, a coordinated multi-language update, anything wanting review. This is a PATCH over the staged copy: fields you omit keep whatever was staged before, they are not cleared. Unlike the live article endpoints, the text fields here are plain strings, because a staged version IS one language — named by the required `locale`. Args: - article_id (number, required): must be a PUBLISHED article. - locale (string, required): the language this version is for. - title, content, slug (strings, optional): a title-only change does NOT rename the URL; send slug to rename. The redirect from the old address is created at publish, never here — so a staged rename cannot redirect live traffic while still private. - category_id, categories, visibility (optional): these belong to the ARTICLE, not a language. Sibling staged languages published together must agree on them, or publish refuses with 422 naming the field and the two locales. - release_translation (boolean, optional): mark this language released when the change is published. - etag (string, optional): pass the one from your last read; a mismatch returns 409 STALE_ETAG with the current value, meaning somebody else moved the staged copy — re-read, re-apply, retry. Returns: { status: "success", staged: { locale, fields, etag, base_signature, updated_at, _links } }. Errors: 422 NOT_PUBLISHED if the article has never been live (use helpcenter_update_article — its own content IS the draft); 403 STAGING_UNAVAILABLE if the help center's plan does not include staged changes (fixable only by changing the subscription, not the request); 409 STALE_ETAG on a lock mismatch.

helpcenter_stage_article_changes

Update an existing article by id in the connected HelpCenter.io help center. Partial update: only the fields you pass are changed. Requires a write-scoped API key. Per-language fields (title, content, slug) are objects keyed by language code and merge per language. Args: - article_id (number, required): id of the article to update. - title, content, slug (objects, optional): per-language fields to set. - category_id (number, optional): primary category id. - categories (number[], optional): replace the set of additional categories. - type ('article' | 'faq', optional). - visibility ('public' | 'private' | 'link_only', optional). - published (boolean, optional): true publishes, false reverts to draft. - external_id (string, optional): adopt this article under a stable key you own, so later upserts by that key hit this article. - content_format ('html' | 'markdown', optional): defaults to 'html'. Set 'markdown' when sending markdown, or the raw markup is stored as the body. IMPORTANT — this writes LIVE. On a published article the change is visible to readers immediately. To prepare an edit privately and release it deliberately, use helpcenter_stage_article_changes and helpcenter_publish_staged_changes instead. Returns: { status: "success", article: {...} } with the updated article. Errors: 403 if the key is read-scoped; 404 if the article id is not in this help center; 400 for unsupported language codes or invalid category ids.

helpcenter_update_article

Update an existing category by id in the connected HelpCenter.io help center. Partial update — only fields you pass change. Requires a write-scoped API key. Name and description are per-language objects keyed by language code. Args: - category_id (number, required): id of the category to update. - name (object, optional): per-language category name. - description (object, optional): per-language description. - parent_id (number, optional): id of the parent category for nesting (must belong to this site). Use 0 to make the category top-level. - icon (string, optional): icon identifier, max 190 chars. - position (number, optional): sibling order, ascending. To move several categories at once use helpcenter_reorder_categories instead. Returns: { status: "success", category: {...} } with the updated category. Errors: 403 if the key is read-scoped; 404 if the category id is not in this help center; 422 for unsupported language codes, an invalid parent_id, or a parent that would make the tree a loop (a category cannot be its own parent or a descendant's child).

helpcenter_update_category