Add Items To HelpCenter Change Set
helpcenter_add_change_set_itemsAdd 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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"change_set_id": "<change_set_id>"
},
"name": "helpcenter_add_change_set_items"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | No | Which help center to act on: an id from helpcenter_list_sites. Needed when this connection reaches more than one help center; omit it when it reaches one. Applies to this call only — pass it on every call of a task, and ask the user which help center they mean if their request does not say. | |
| article_ids | No | Articles to release. A PUBLISHED article is added with every language it has staged changes in (it must have some); a DRAFT article is added to be published by the set. | |
| category_ids | No | Categories whose visibility the set changes when it publishes. | |
| change_set_id | Yes | Id of the change set. | |
| category_visibility | No | The visibility category_ids are given at publish. Default 'public' — the usual case is a category built 'unlisted' and revealed by the release. |