Staging article changes over the API

Staged changes let you edit an article that is already live and save your work without readers seeing it. The published version stays exactly as it is until you publish the staged copy — so you can fix a paragraph, have it reviewed, and release it when you are ready.

Everything the dashboard can do to a staged copy is available here, so an integration can prepare documentation changes and hold them until a release.

Before you start

• All requests go to https://api.helpcenter.io and carry your token in an apikey header.
• Staging only applies to published articles. An article that has never been published has nothing to hide edits from, so save it normally instead — these endpoints return 409 with reason: NOT_PUBLISHED.
• Translatable fields are per-language. Every staged write names one locale, and an article can carry staged changes in several languages at once.

Read an article

A single-article read, which the v1 API did not previously offer. The response includes has_staged_changes, staged_locales and staged_updated_at, so you can tell at a glance whether an article has unpublished work waiting on it.

Read the staged copy

Returns the staged version for one language, or every staged language when you omit locale. Useful as a probe: it answers 404 when nothing is staged.

Stage a change

Creates the staged copy on first write and updates it afterwards. Send only the fields you are changing — anything you omit keeps its live value.

Pass etag whenever you have one. It is returned by every staged read and write, and it is what stops two integrations overwriting each other: if the staged copy moved since you read it, the write is refused with 409 rather than silently winning.

Publish the staged copy

Applies the staged text to the live article. Omit locale to publish every staged language at once, which is usually what you want for a translated article.

If somebody edited the live article after you staged your changes, this refuses with 409 rather than overwriting their work. Re-read, merge, and try again — or send force: true if you are certain your version should win.

Discard the staged copy

Throws the staged work away. The live article is untouched.

Version history

Every publish keeps the text it replaced, so you can see what an article used to say and put it back. Versions are per language.

A worked example

Fix a paragraph on a live article, check it, then publish it:

API=https://api.helpcenter.io/v1
KEY=your-read-write-token

# 1. Stage the change. Readers still see the old text.
curl -X PATCH "$API/articles/4821/staged" \
  -H "apikey: $KEY" -H 'Content-Type: application/json' \
  -d '{"locale":"en","content":"<p>Boards now support stage gates.</p>"}'

# 2. Read it back to review, and keep the etag.
curl -s "$API/articles/4821/staged?locale=en" -H "apikey: $KEY"

# 3. Publish when you are ready.
curl -X POST "$API/articles/4821/staged/publish" \
  -H "apikey: $KEY" -H 'Content-Type: application/json' \
  -d '{"locale":"en"}'

Errors

These endpoints use the same codes as the rest of the API:

• 401 — the apikey header is missing or unknown.
• 402 — staged changes are not included in this site's plan.
• 403 — a read-scoped token attempted a write.
• 404 — the article belongs to another site, or nothing is staged.
• 409 — the article is not published, or your etag is stale, or the live article moved.
• 422 — validation failed.

To group several staged articles and publish them together, see Publishing a release with change sets.