Update a help article

Patch a help article — edit content, publish it, re-file it under a different parent, or replace its related links.

Updates a help article. The endpoint is patch-style: any subset of the optional body fields may be present, and only those fields are applied. Omitted fields keep their current values.

Endpoint

POST https://api.productbridge.io/api/external/v1/help-articles/update

Arguments

body

api_keystring

Required

Your organization's public API key. See Authentication.

body

article_idstring

Required

UUID of the article to update. Must belong to your organization.

body

category_idstring

Re-file the article under this category, clearing any collection_id parent. Send at most one of category_id / collection_id; omit both to leave the parent unchanged.

body

collection_idstring

Re-file the article directly under this collection, clearing any category_id parent.

body

titlestring

New title. 1–512 characters.

body

contentstring

New body as HTML. Replaces the existing body entirely.

body

slugstring

New URL-safe identifier. A slug already in use is rejected with 400 rather than auto-suffixed. Max 512 characters.

body

excerptstring

New summary for listings and search results. Max 512 characters.

body

status_codestring

Either "draft" or "published". Moving to "published" for the first time stamps published_at.

body

show_on_portalboolean

Whether the article may appear publicly.

body

favouriteboolean

Internal star for your team. Never shown to customers.

body

related_article_idsarray

Replaces the curated related-article list, in the order given. Send [] to clear it; omit the field to leave it untouched. Every id must be an article in your organization.

Apart from related_article_ids (where [] clears the list), this endpoint sets values rather than clearing them. Passing null for a field is treated the same as omitting it.

Publishing and unpublishing

Goal	Send
Publish a draft	`{"status_code": "published"}`
Revert to draft	`{"status_code": "draft"}`
Unlist without unpublishing	`{"show_on_portal": false}`
Relist	`{"show_on_portal": true}`

published_at is stamped the first time an article becomes published and is not reset by later draft/publish cycles, so it keeps meaning "when this was first published".

Returns

{ "success": true }

Example request

Publishing a draft and setting its related articles:

curl -X POST https://api.productbridge.io/api/external/v1/help-articles/update \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "pb_YOUR_PUBLIC_API_KEY",
    "article_id": "aa1c3ef8-b8cd-cd15-01ba-77bb77bb77bb",
    "status_code": "published",
    "related_article_ids": [
      "bb2c3ef8-b8cd-cd15-01ba-88bb88bb88bb",
      "cc3c3ef8-b8cd-cd15-01ba-99bb99bb99bb"
    ]
  }'

const res = await fetch(
  "https://api.productbridge.io/api/external/v1/help-articles/update",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: process.env.PRODUCTBRIDGE_API_KEY,
      article_id: "aa1c3ef8-b8cd-cd15-01ba-77bb77bb77bb",
      status_code: "published",
      related_article_ids: [
        "bb2c3ef8-b8cd-cd15-01ba-88bb88bb88bb",
        "cc3c3ef8-b8cd-cd15-01ba-99bb99bb99bb",
      ],
    }),
  }
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);

import os, httpx

resp = httpx.post(
    "https://api.productbridge.io/api/external/v1/help-articles/update",
    json={
        "api_key": os.environ["PRODUCTBRIDGE_API_KEY"],
        "article_id": "aa1c3ef8-b8cd-cd15-01ba-77bb77bb77bb",
        "status_code": "published",
        "related_article_ids": [
            "bb2c3ef8-b8cd-cd15-01ba-88bb88bb88bb",
            "cc3c3ef8-b8cd-cd15-01ba-99bb99bb99bb",
        ],
    },
)
resp.raise_for_status()

Example response

{
  "success": true
}

Re-filing an article

Sending a parent switches it and clears the other, so an article never has two:

{
  "api_key": "pb_YOUR_PUBLIC_API_KEY",
  "article_id": "aa1c3ef8-b8cd-cd15-01ba-77bb77bb77bb",
  "collection_id": "553c3ef8-b8cd-cd15-01ba-12bb12bb12bb"
}

The article is now filed directly in the collection and its category_id becomes null. Sending both parents in one call is a 422.

Errors

Status	Body	Cause
`400`	`{"detail":"Slug already exists"}`	The explicit `slug` is already used by another article in your organization.
`400`	`{"detail":{"error":"related article ... not found in this organization"}}`	A `related_article_ids` entry doesn't exist or belongs to another organization.
`401`	`{"detail":{"error":"invalid api_key"}}`	Missing / unknown / inactive `api_key`.
`403`	`{"detail":{"error":"The Help Center is not enabled on your current plan..."}}`	Your plan does not include the `knowledgebase` feature.
`404`	`{"detail":{"error":"help article not found"}}`	No such article, or it belongs to another organization.
`404`	`{"detail":{"error":"help category not found"}}`	The target `category_id` doesn't exist, or belongs to another organization.
`422`	Validation error envelope	Both parents sent, `article_id` not a valid UUID, or `status_code` not `"draft"` / `"published"`.

See Errors for the full envelope shape and a recommended client-side handler.

Was this page helpful?