Add articles and categories to a change set, many in one call.
A change set is a named release. It groups work that already exists — staged edits on published articles, never-published draft articles, and category visibility changes — and publishes all of it together, now or at a scheduled time. It owns no content: removing an item or deleting the set never deletes the work, which simply stays unreleased.
Use one when several articles have to go live at the same moment — a feature launch, a restructure, a coordinated translation. For one article, helpcenter_publish_staged_changes (or publishing a draft with helpcenter_update_article) is simpler. The flow: stage edits with helpcenter_stage_article_changes, or write drafts with helpcenter_create_article and published: false -> helpcenter_create_change_set -> helpcenter_add_change_set_items -> check readiness with helpcenter_get_change_set -> helpcenter_publish_change_set -> poll helpcenter_get_change_set_status until done.
Change sets are part of the Catalyst plan, behind the same gate as staged changes; on other plans the API answers 402.
What each id adds:
- a PUBLISHED article: every language it has staged edits in, one item each. It must have some — a live article with nothing staged is rejected, because there is nothing to release. To ship only some languages, remove the others' items afterwards.
- a DRAFT (never-published) article: the article itself, which the set will PUBLISH. Only add drafts that are meant to go live.
- a category: a change of its visibility to category_visibility (default 'public') — the usual case is a category built 'unlisted' and revealed by the release.
Adding something already in the set is harmless: it returns the existing item, pointed at the current staged copy.
A PARTLY-REJECTED BATCH IS A NORMAL RESULT (HTTP 207, status 'partial'): read 'rejected' rather than assuming everything landed. One bad id never discards the rest.
Requires a write-scoped API key. The set must be open.
Args:
- change_set_id (number, required).
- article_ids (number[], optional, max 500).
- category_ids (number[], optional, max 500).
- category_visibility ('public' | 'unlisted' | 'private' | 'team_private', optional): default 'public'.
At least one of article_ids and category_ids must have an entry.
Returns: { status: "success" | "partial", added, rejected: [{ article_id | category_id, reason }], change_set: {...} }. 'added' counts items, so an article staged in two languages adds 2. A reason of 'not_found' means the id is not in this help center.
Errors: 403 if the key is read-scoped; 404 if the change set is not in this help center; 409 CHANGE_SET_NOT_OPEN once it is publishing or published; 409 CHANGE_SET_FULL at 500 items.