Zendesk API and New Article Editor Incompatibility

Summary: Articles and translations created or updated through the Zendesk REST API are flagged by Zendesk's UI as legacy editor content, even when the source article was authored in the new editor. This is a known incompatibility on Zendesk's side that affects every Swifteq app (Help Center Manager, Help Center Translate, etc.) as well as any other integration, script, or workflow that writes to Zendesk Help Center via the API.

This article explains the root cause, how to reproduce the issue, and how it manifests inside Zendesk.

Background: why this happens

Zendesk has two article editors for Help Center articles:

• Legacy editor — accepts arbitrary HTML with very few restrictions.
• New editor — uses a strict content schema with a defined set of content blocks (paragraphs, headings, lists, callouts, HTML blocks, etc.).

The Zendesk REST API for articles and translations only accepts free-form HTML in the body field. There is no API parameter to indicate that content should be stored as new-editor content, and there is no published schema that API consumers can target. As a result, when any tool writes to an article or a translation through the API, Zendesk parses that HTML through the new editor's strict schema, and the article/translation ends up in a state that Zendesk's UI flags as legacy.

This was confirmed directly by Zendesk's engineering team:

• Short to intermediate term: the current behavior is expected. The API and the new editor are not directly compatible, so any article or translation written via the API will be flagged as legacy-editor content.
• Long term: Zendesk is working on a redesigned Help Center API that aligns with the new editor's content model. There is no ETA at this time.

Zendesk's developer documentation on this topic is available here: https://developer.zendesk.com/documentation/help_center/help-center-api/article-editor-troubleshooting/

How to reproduce the issue

The behavior can be reproduced in two scenarios. Both reproduce the same underlying bug.

Scenario A — Updating a migrated article via the API

1. In Zendesk, migrate an article to the new editor through the Knowledge UI and confirm it shows as migrated.
2. Open that article in a Swifteq app (e.g. Help Center Manager). The app pulls the migrated HTML from the Zendesk API.
3. Make any edit — even a trivial one, such as adding a single space — and save the change.
4. Swifteq pushes the updated article back to Zendesk via the standard Update Article / Update Translation REST endpoint.
5. Reopen the article in Zendesk's Knowledge UI.

Result: The article is no longer marked as migrated. Zendesk shows it as legacy-editor content and requires it to be re-migrated, even though the HTML pushed back to Zendesk came from the migrated version of the article in the first place.

Scenario B — Creating a translation for an article authored in the new editor

1. In Zendesk, create a brand-new article using the new editor.
2. Use Help Center Translate (or any other tool that creates translations through the Zendesk API) to translate the article into one or more target languages.
3. Open one of the new translations in Zendesk.

Result: The translation is flagged by Zendesk as having been created in the legacy editor, even though the source article was authored in the new editor and was never edited via the API.

How the issue manifests in Zendesk

After an API write, the affected article or translation will exhibit one or more of the following:

• The article shows a banner or message at the top stating that it was last edited via the API or with the legacy editor.
• When opening the article for editing, the editor shows a warning message and may open in read-only mode, requiring the user to confirm before editing.
• The article appears in filters or reports as not migrated to the new editor.
• Formatting that was previously valid in the new editor (such as custom HTML callouts, image spacing, or HTML blocks) may be re-interpreted by the new editor's schema, resulting in visible formatting changes.
• HTML blocks present in the original article may be stripped or altered when the article is re-rendered by the new editor.

Note: the underlying article content is written correctly to Zendesk. The issue is in how Zendesk's UI labels and renders that content after an API write.

What this means for our customers

• The behavior is not specific to Swifteq apps. It affects any integration, automation, or script that creates or updates Zendesk Help Center articles or translations through the REST API.
• There is no setting on the Swifteq side that can prevent it — the Zendesk API simply does not expose a way to write content as new-editor content.
• Until Zendesk releases the redesigned Help Center API, customers using API-based workflows should expect to see legacy-editor warnings on articles and translations updated through the API.

What we recommend

• Raise the issue directly with Zendesk Support. The more affected accounts that escalate this internally, the more visibility and urgency the API redesign receives. When opening a ticket, reference that this is a known incompatibility between the Zendesk REST API and the new article editor, confirmed by Zendesk's engineering team.
• Refer to Zendesk's developer documentation for the latest guidance: Article editor troubleshooting.
• Contact Swifteq support if you would like help describing the issue when escalating to Zendesk, or if you need guidance on minimizing the impact on your specific workflow.

Status

Swifteq has been actively engaged with Zendesk Support and engineering on this issue and is monitoring progress on the redesigned Help Center API. We will update this article as soon as Zendesk releases changes that address the incompatibility.