> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Help Center API

> Create, update, publish, and delete help center articles and categories from your own systems. Use when content lives outside OpenCX and must stay in sync.

The Help Center API lets you manage the customer-facing knowledge base you author in OpenCX from your own systems. Anything you can do in the [Help Center](/help-center/overview) editor you can do here: create and edit articles and categories, publish and unpublish them, manage translations, upload media, and push an entire content tree in one call.

Publishing an article's primary language ships it to your public help site **and** the AI's knowledge in the same action. There is no separate "train the AI" step. Other languages publish to the site only; the AI always follows the primary language.

## Scopes

| Scope               | Grants                                                                                    |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `help-center:read`  | List and fetch help centers, articles, categories, versions, media, and the attached spec |
| `help-center:write` | Create, update, publish, unpublish, delete, retranslate, sync, upload                     |

Create an API key with these scopes under **Settings → API keys**. See [Authentication](/api-reference/authentication).

## Key concepts

* **Help center id** — every endpoint is scoped to one help center. Call [List help centers](./list) first to find the id.
* **Categories** — every article belongs to exactly one category. Categories can be nested; `parent_id` is `null` for top-level ones.
* **Draft and published** — creating or updating an article writes a **draft** version. Nothing is visible to customers or the AI until you call [Publish](./articles/publish). Editing a published article creates a new draft; publishing it supersedes the live version and keeps the old one in [version history](./articles/versions).
* **Locales** — each enabled language has its own published state. [Publish](./articles/publish) releases every locale at once; [Publish one locale](./articles/publish_locale) lets you ship the primary language before translations are reviewed. Only the primary language feeds the AI: publishing a translation while the primary language is still a draft makes that translation public without adding the article to the AI's knowledge.
* **Unpublish vs delete** — [Unpublish](./articles/unpublish) takes an article offline while keeping its content and history; unpublishing the primary language also removes it from the AI's knowledge. [Delete](./articles/delete) is permanent.

## Two ways to sync

<Tabs>
  <Tab title="Per-article endpoints">
    Use the article and category endpoints when you push individual changes as they happen, for example from a CMS webhook. You control ids, drafts, and when each article goes live.
  </Tab>

  <Tab title="Full-tree sync">
    Use [Sync content](./sync) when your help center is generated from a repository or export. Send the entire tree of categories and articles in one request; OpenCX diffs it against the current state and applies additions, edits, publishes, and removals in one database transaction. AI knowledge and translation updates run after that commit; if one fails it is reported as an error event in the SSE stream and the structural changes stay. Send `Accept: text/event-stream` to receive progress and error events for large trees.

    <Warning>
      Sync is a full replace, not an upsert. Every category or article missing from the tree you send is permanently deleted, along with its AI knowledge, with no dry run or rollback. Always send the complete intended tree.
    </Warning>
  </Tab>
</Tabs>

<Note>
  Articles are either draft or published. There is no separate internal-only visibility today: an article published in its primary language is on the public site and in the AI's knowledge together. For content the AI should know but customers should not browse, use the [AI Training API](/api-reference/training/index) instead.
</Note>

## Available Endpoints

### Help centers

<CardGroup>
  <Card title="List help centers" icon="list" href="./list">
    Find the help center id
  </Card>

  <Card title="Export content" icon="download" href="./export">
    Dump published categories and articles as a tree
  </Card>

  <Card title="Sync content" icon="arrows-rotate" href="./sync">
    Replace the whole content tree atomically
  </Card>
</CardGroup>

### Articles

<CardGroup>
  <Card title="List" icon="list" href="./articles/list">
    All articles for a language
  </Card>

  <Card title="Get" icon="magnifying-glass" href="./articles/get">
    One article with its versions
  </Card>

  <Card title="Create" icon="plus" href="./articles/create">
    New draft under a category
  </Card>

  <Card title="Update" icon="pen" href="./articles/update">
    New draft version
  </Card>

  <Card title="Publish" icon="rocket" href="./articles/publish">
    Go live in every locale
  </Card>

  <Card title="Publish one locale" icon="language" href="./articles/publish_locale">
    Go live in one language
  </Card>

  <Card title="Unpublish" icon="eye-slash" href="./articles/unpublish">
    Take offline, keep content
  </Card>

  <Card title="Delete" icon="trash" href="./articles/delete">
    Remove permanently
  </Card>

  <Card title="Versions" icon="clock-rotate-left" href="./articles/versions">
    Version history
  </Card>

  <Card title="Retranslate" icon="language" href="./articles/retranslate">
    One language or all
  </Card>
</CardGroup>

### Categories

<CardGroup>
  <Card title="List" icon="list" href="./categories/list">
    All categories for a language
  </Card>

  <Card title="Get" icon="magnifying-glass" href="./categories/get">
    One category with locales
  </Card>

  <Card title="Create" icon="plus" href="./categories/create">
    Top-level or nested
  </Card>

  <Card title="Update" icon="pen" href="./categories/update">
    Rename, re-icon, or move
  </Card>

  <Card title="Delete" icon="trash" href="./categories/delete">
    Empty only, unless forced
  </Card>

  <Card title="Retranslate" icon="language" href="./categories/retranslate">
    One language or all
  </Card>
</CardGroup>

### Media and API playground

<CardGroup>
  <Card title="Upload media" icon="upload" href="./media/upload">
    Images for article markdown
  </Card>

  <Card title="List media" icon="images" href="./media/list">
    Library contents and URLs
  </Card>

  <Card title="Delete media" icon="trash" href="./media/delete">
    Remove a file
  </Card>

  <Card title="Upload spec" icon="file-code" href="./spec/upload">
    Power the public API playground
  </Card>

  <Card title="Get spec" icon="file-code" href="./spec/get">
    Read the attached spec
  </Card>
</CardGroup>

## Best practices

* Create as draft, review, then publish. Drafts never reach customers or the AI.
* Prefer [Sync content](./sync) over hundreds of per-article calls when you regenerate the whole help center.
* Set a stable `slug` on create when you need permanent URLs; otherwise it is derived from the title.
* Upload images through [Upload media](./media/upload) and reference the returned URL in `content_markdown`.
* Unpublish rather than delete when content might come back.