# Build on HelpCenter.io

_Category: Getting started_

HelpCenter.io gives your code several ways into a help center: a REST API, webhooks, an MCP server for AI agents, machine-readable pages for AI assistants and crawlers, a widget you drive from JavaScript, embeds, and single sign-on for readers. This page shows what each one is for, how it authenticates and which plans include it, so you pick the right one before you write any code.

## The surfaces

| Surface | What it's for | How it authenticates | Plans |
| --- | --- | --- | --- |
| **REST API**  <br>`https://api.helpcenter.io/v1` | Read and write articles, categories, images, staged changes, change sets, comments, team notes, interface translations, the help center's design, redirects and custom domain, the widget's install snippet and embedding origins, embeddable FAQ sections, analytics and exports from your own code, and import a knowledge base from another platform. | An API key in the `apikey` header, bound to one help center. Or an OAuth 2.1 access token in `Authorization: Bearer`, for apps that act for a HelpCenter.io user. | All plans. Staged changes are part of Catalyst. Change sets are too, in early preview. A custom domain needs a plan that includes one. |
| **Webhooks** | Get a POST request at your URL when articles, categories or the help center change: nine events, such as `article.published` and `category.deleted`. | You register the URL through the REST API, with a Read & write key or an OAuth token that has the `webhooks.manage` scope. Each delivery is signed with your secret in `X-HCio-Signature`. | All plans. |
| **MCP server**  <br>`https://mcp.helpcenter.io` | Let Claude, ChatGPT or your own agent search, write and organize a help center and change its design: articles, categories, staged changes, comments, team notes, analytics and the design, as MCP tools. | OAuth 2.1: the person signs in and picks the help centers to share. Headless agents send an API key as `Authorization: Bearer`. | Growth and Catalyst, including their free trials. |
| **Help centers built by AI agents**  <br>`https://api.helpcenter.io/v1/agent/help-centers` | Let an AI agent build a help center for someone who has no HelpCenter.io account yet, fill it over the REST API, and hand it over with a link they use to claim it. | None to create one. The answer carries a key for that help center, which the agent sends in the `apikey` header. | None to create one. The help center stays unpublished until its owner has claimed it and published it. The agent's redirects and custom domain wait until the owner has claimed it, verified their email address and activated a plan. |
| **Public MCP server**  <br>`https://<your help center>/mcp` | Let your readers' AI assistants search and read your published articles, with the tools `search`, `fetch` and `list_categories`. | None. It is anonymous and read-only. | All plans, on published help centers. |
| **llms.txt, ai.txt and Markdown pages** | Give AI tools and crawlers an index of your articles at `/llms.txt`, the full text of your articles at `/llms-full.txt`, and your help center's pages as Markdown when they send `Accept: text/markdown`. | None. They show what a visitor without an account can read. | All plans, once the help center is published. |
| **Widget and its JavaScript API** | Put your help center in a corner of your website or app, and open it on an article or category from your own buttons and links. | None on a published help center. A help center that isn't published yet shows its widget to its team alone. On a private one, readers sign in with a JWT you sign on your server. | All plans. Signing readers in needs single sign-on (Catalyst). |
| **Embedding** | Show your whole help center inside your app in a frame, and optionally keep it from being browsed as a normal website. | The page must be on your help center's **Embedding origins** list. A JWT signs readers in to a private help center when the help center is on your own site, for example `help.example.com` inside `app.example.com`. | See [pricing](https://helpcenter.io/pricing). |
| **JWT single sign-on** | Sign readers in to a private help center with your own login, so they never see a second password. | A JWT that your server signs with the shared secret from your settings (HS256). | Catalyst. |

## Which one fits your job

| You want to | Use |
| --- | --- |
| Publish articles from your docs repository or another system | The REST API with an API key. See [Sync articles from a Git repository](https://developers.helpcenter.io/content/sync-articles-from-git). |
| Move an existing knowledge base into HelpCenter.io | The REST API's bulk import, or for a public Zendesk Guide, Intercom, Document360, Help Scout Docs, Front Knowledge Base or HelpDocs help center, HelpCenter.io's importer at `/v1/imports`. See [Import articles in bulk](https://developers.helpcenter.io/content/import-articles-in-bulk). |
| Have an AI agent move someone's knowledge base before they have an account | The REST API, starting with `POST /v1/agent/help-centers`. See [Migrate a knowledge base as an AI agent](https://developers.helpcenter.io/content/migrate-a-knowledge-base-as-an-ai-agent). |
| Keep a copy of every article and category | The REST API's export. See [Back up your help center](https://developers.helpcenter.io/content/back-up-your-help-center). |
| Rebuild a site, clear a cache or post to chat when content changes | Webhooks. See [Receive and verify webhooks](https://developers.helpcenter.io/content/receive-and-verify-webhooks). |
| Build an app that other HelpCenter.io customers connect to | The REST API with OAuth 2.1. See [OAuth 2.1 for apps and AI clients](https://developers.helpcenter.io/content/oauth). |
| Have an AI assistant draft, edit and organize articles | The MCP server. See [Connect an AI assistant to your help center](https://developers.helpcenter.io/content/connect-an-ai-assistant-to-your-help-center). |
| Let your customers' AI assistants answer from your published articles | The public MCP server and `/llms.txt`. See [The public MCP server of a help center](https://developers.helpcenter.io/content/public-mcp-server). |
| Offer help inside your product | The widget. See [Widget installation and options](https://developers.helpcenter.io/content/widget-options). |
| Show the whole help center inside your app | Embedding. See [Embed your help center in your app](https://developers.helpcenter.io/content/embed-your-help-center). |
| Let readers of a private help center use their account with you | JWT single sign-on. See [How JWT single sign-on works](https://developers.helpcenter.io/content/how-jwt-sso-works). |

An API key belongs to one help center. An OAuth token belongs to a person, and reaches only the help centers that person chose to share with your app. If your software works on other people's help centers, use OAuth.

## What the REST API doesn't do

- **No per-visitor analytics.** The analytics endpoints report figures for the help center, its articles and its search queries, never for a single visitor or session.
- **Search is keyword search.** `GET /v1/articles?search=` matches words in titles and content, and returns only published articles that anyone can read, the best 1,000 matches at most, in your default language or the `lang` you send. It doesn't use the AI search your readers may get.
- **Deleting an article moves it to the Trash.** You can restore it from the dashboard. The API has no permanent delete for articles.
- **Most settings stay in the dashboard.** Help center settings such as visibility, publishing, languages, your team, API keys and single sign-on are managed in the dashboard, not over the API. Four things can be changed over the API: the design (see [Design API](https://developers.helpcenter.io/content/design-api)); the custom domain, with `/v1/custom-domain` and the `domain.manage` scope, which an API key holds only when an Owner or Admin ticks **Allow managing the custom domain** for it in Settings, under **API keys**; redirects, with `/v1/redirects` and an API key; and the websites allowed to embed your help center, with `PATCH /v1/widget/embedding-origins` and the `embed.manage` scope. See [Custom domain](https://developers.helpcenter.io/content/custom-domain-api) and [Redirects](https://developers.helpcenter.io/content/redirects-api).

## Where to start

- **Make your first request:** [Quickstart: your first API request](https://developers.helpcenter.io/content/quickstart-your-first-request) takes you from a new key to a published article.
- **Learn the rules every request follows:** [Requests and responses](https://developers.helpcenter.io/content/requests-responses-and-conventions), [Pagination](https://developers.helpcenter.io/content/pagination), [Rate limits](https://developers.helpcenter.io/content/rate-limits) and [Errors](https://developers.helpcenter.io/content/errors).
- **Authenticate:** [API keys](https://developers.helpcenter.io/content/api-keys) for your own help center, [OAuth 2.1 for apps and AI clients](https://developers.helpcenter.io/content/oauth) for other people's.
- **Look up an endpoint:** the REST API reference has a page for each resource, such as [Articles](https://developers.helpcenter.io/content/articles-api).
- **Connect AI agents:** [The HelpCenter.io MCP server](https://developers.helpcenter.io/content/the-mcp-connector-for-ai-agents).
- **Add help to your product:** [Widget installation and options](https://developers.helpcenter.io/content/widget-options).
- **Sign readers in:** [How JWT single sign-on works](https://developers.helpcenter.io/content/how-jwt-sso-works).
- **Follow a recipe:** [Sync articles from a Git repository](https://developers.helpcenter.io/content/sync-articles-from-git), [Back up your help center](https://developers.helpcenter.io/content/back-up-your-help-center) and more in Guides and recipes.

## Related

- [Quickstart: your first API request](https://developers.helpcenter.io/content/quickstart-your-first-request)
- [API keys](https://developers.helpcenter.io/content/api-keys)
- [The HelpCenter.io MCP server](https://developers.helpcenter.io/content/the-mcp-connector-for-ai-agents)
- [Widget installation and options](https://developers.helpcenter.io/content/widget-options)
- [How JWT single sign-on works](https://developers.helpcenter.io/content/how-jwt-sso-works)