Help center

All paths use the Public API base URL. Send X-Api-Key on every request. Reads are GET with no body and return 200.

What helpdesk.helpcenter:write allows

The same scope behaves differently depending on where it is used:

• On this Public API and on Chatty MCP, it changes the Help center directly: settings, the store page, store colors and brand assets. Each change is saved straight away and recorded in the audit log with the calling key.
• On the Helpdesk agent API and the Helpdesk MCP tools, it lets an agent propose creating or updating articles and categories (deleting is not proposable) with the Helpdesk tools propose_create_article, propose_update_article, propose_create_category and propose_update_category. A person approves or rejects each proposal in Helpdesk, and can undo it; nothing changes until then. Over REST, the agent sends the same proposals with its X-Api-Key to POST https://app.chatty.net/hd/v1/agent/help-center/proposals and lists its own with GET on the same path.

Like other Helpdesk write scopes, it also grants every Helpdesk read scope. OAuth connections can only read the Help center.

Settings

GET /help-center/settings returns the stored settings merged over the defaults. A store that never changed them gets the defaults.

{
  "data": {
    "settings": {
      "branding": {"title": "Help Center", "colorPreset": "store", "colorTheme": "light", "categoryLayout": "accordion"},
      "customDomain": {"status": "unverified"},
      "storePage": {"enabled": false, "handle": "helpcenter", "shopifyPageId": null},
      "seo": {"metaTitle": "Help Center", "enableIndexing": true, "generateSitemap": true},
      "contactMethods": {"liveChat": {"enabled": true, "label": "Chat with us"}, "email": {"enabled": false}},
      "contactForm": {"enabled": false, "customFields": []},
      "language": {"code": "en", "direction": "ltr"},
      "revision": 0
    }
  }
}

The example is an excerpt. customDomain.status is unverified, checking, active or failed. Stored settings can also include customCss, customDomain.domain and seo.ogImageUrl. The DNS record for domain verification is not part of this response.

Overview

{
  "data": {
    "articles": {"draft": 3, "published": 24, "internal": 2},
    "categories": {"empty": 1, "total": 6},
    "previewArticleSlug": "track-my-order",
    "previewUrl": "https://help.example.com/hc/shop_123?preview=1",
    "storePage": {"enabled": true, "handle": "helpcenter", "hasShopifyStore": true, "shopifyPageId": "gid://shopify/Page/123", "url": "https://shop.myshopify.com/pages/helpcenter"}
  }
}

• articles.published counts published public articles, the ones customers see. internal counts published articles that are not public.
• categories.empty counts categories with no article.
• previewArticleSlug is one published public article, or null. previewUrl can be null.
• storePage.url is null unless the store page is enabled.

Search analytics

periodDays is required and must be 7, 30 or 90. The window ends now and is counted in UTC.

curl 'https://app.chatty.net/v1/help-center/search-analytics?periodDays=30' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

{
  "data": {
    "total": 412,
    "zeroResult": 37,
    "topQueries": [{"query": "refund", "count": 58, "resultsCount": 4, "lastSearchedAt": "2026-10-22T09:12:00.000Z"}],
    "byDay": [{"date": "2026-10-21", "count": 19}],
    "zeroResultQueries": [{"query": "warranty", "count": 9, "lastSearchedAt": "2026-10-22T07:40:00.000Z"}]
  }
}

topQueries and zeroResultQueries hold up to 50 queries each, most searched first. resultsCount is the highest number of results seen for that query. byDay is in date order. Queries with no result are a good list of articles to write next.

Change settings

PATCH /help-center/settings takes the revision you last read and any settings you want to change, in the same shape as the GET response's settings. Omitted fields keep their value.

curl -X PATCH 'https://app.chatty.net/v1/help-center/settings' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"revision":3,"branding":{"title":"Support","primaryColor":"#1A1A1A"},"seo":{"metaTitle":"Support"}}'

{"success":true,"revision":4}

• Revision lock. If someone saved after your read, the revision no longer matches and the route returns 409 STALE_SETTINGS. Read the settings again, reapply your change and retry with the new revision. Each successful save adds 1.
• Accepted top-level fields are branding, contactMethods, contactForm, contactPage, customDomain, language, seo and customCss. Any other field returns 400 VALIDATION_FAILED. The store page has its own route below.
• Colors are hex values such as #1A1A1A. Text fields have length limits, for example seo.metaTitle up to 70 characters. A map in contactPage needs an address.
• customCss (up to 51,200 characters) needs the Plus plan; below Plus it returns 403 CUSTOM_CSS_REQUIRES_PLUS. Sending back the stored value unchanged is allowed on any plan.

Store page

PUT /help-center/store-page takes {"enabled":true,"handle":"help"}. handle is optional, lowercase letters, numbers and hyphens, up to 255 characters; without it, the current handle or helpcenter is used.

• enabled: true creates or updates a page on the Shopify store that shows the Help center, and moves it when the handle changes. The first time, it also reads the store's colors.
• enabled: false removes that page from the store.
• The response is {"success":true}. Read GET /help-center/overview for the page URL.

A handle already used by another page returns 409 STORE_PAGE_HANDLE_TAKEN. A store without a Shopify connection returns 400 STORE_PAGE_SHOPIFY_UNAVAILABLE. A Shopify failure returns 502.

Store colors

POST /help-center/store-colors/sync takes no body. It reads the colors of the store's current theme and saves them in branding.storeColors, which the store color preset uses. It returns {"success":true} and does not change revision, so a settings draft read earlier still saves. A theme whose colors cannot be read is saved with status: "unreadable". A store without a Shopify connection returns 400 STORE_COLORS_SHOPIFY_UNAVAILABLE.

Brand assets

POST /help-center/assets/{kind} uploads one image. kind is logo, whiteLogo or favicon.

Send either multipart with exactly one file, or JSON with mimeType, dataBase64 and an optional name:

curl -X POST 'https://app.chatty.net/v1/help-center/assets/logo' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -F '[email protected]'

{"data":{"url":"https://cdn.example.com/help-center/shop_123/logo/logo.png"}}

Success is 201. The file content must match its type, and SVG files with scripts are refused: 400 INVALID_FILE. Uploading does not change the Help center yet. Save the returned url with PATCH /help-center/settings, for example in branding.logoUrl or branding.faviconUrl. A storage failure returns 502 STORAGE_UPLOAD_FAILED.

Every write attempt that reaches the route handler is recorded in the audit log with the calling key, whether it succeeds or fails. Requests refused earlier, for a missing scope or a bad key, are not recorded. Writes are not idempotent; read the settings before repeating an uncertain request.

Errors

On MCP, manage_help_center reads the same resources with an API key or OAuth, and performs the writes with an API key only. To search published articles, use the API-key tools search_help_center and get_help_center_search_terms. See the MCP tool reference.