Bulk Create HelpCenter Articles
helpcenter_bulk_create_articlesCreate or upsert many articles in one request. Use this for imports and migrations instead of calling helpcenter_create_article in a loop. Send at most 50 articles per call; split a larger import into batches of 50.
Requires a write-scoped API key. Give every item an external_id: the batch is then replayable, so a run that dies halfway can simply be sent again — what exists is updated, what is missing is created, and nothing is duplicated.
Args:
articles (array, required, 1-50): each item takes the same fields as helpcenter_create_article (title required, plus content, slug, category_id, categories, type, visibility, published, external_id, content_format, rehost_images). rehost_images is per item, ON by default through this connector, and all items share one image-download time budget.
Returns: HTTP 207 — { status: "success", results: [...], meta: { total, created, updated, failed } }, one result per item in the order sent. A success is { index, status: "created" | "updated", article, images }. images summarises the external images found in its content: { rehosted, reused, failed: [{ src, reason }], failed_count }, where rehosted counts the images copied into the help center, reused the ones it already held, and failed_count the ones that could not be copied; failed lists their source and reason, and on a very long list stops short of failed_count. The article is saved even when failed_count is above 0, so check it. images is absent when the item had no content or rehost_images was false. A failure is { index, status: "error", external_id, error: { code, message } }. index is the item's position in your articles array: match outcomes to items by index, because a success does not echo external_id at the top level (it is article.external_id). A partly-failed batch is the NORMAL result, not an exception: check meta.failed and read every result whose status is "error" rather than assuming success. One bad item never discards the work of the rest.
Errors: 403 if the key is read-scoped or your role cannot create articles. Otherwise items fail individually, and error.code says why:
"validation_error": the item was refused as sent; error.errors lists the problem with each field.
"invalid_argument": a value the site cannot take, such as a language that is not enabled for it.
"capability_forbidden": your role cannot do what the item asks (publish it, file it in a category, set its visibility, or write to an article it cannot see); error.capability names the permission and error.message the reason.
"publication_forbidden": the item's external_id belongs to a published article and your role cannot publish; stage the change with helpcenter_stage_article_changes for the article in error.staged_endpoint instead.
"external_id_busy": that key already belongs to a different live article.
"persist_failed": the save failed on the server; send the item again (safe when it has an external_id).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| articles | Yes | Articles to create or upsert. Give each one an `external_id` so replaying the batch updates rather than duplicates. | |
| agent_key | Yes | The api_key helpcenter_create_help_center returned for this help center, exactly as returned. Required on every call: this endpoint has no sign-in, so the key is how each call says which help center it acts on. It is sent to HelpCenter.io as this call's credential and nowhere else, and it is never shown again: keep it for the whole task, and never show it to the user or write it into content. |