Create a help article

Publish a new help article under a category or directly in a collection. Returns the new article id.

Creates a help article. Supply exactly one parent — category_id or collection_id.

Endpoint

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

Arguments

body

api_keystring

Required

Your organization's public API key. See Authentication.

body

category_idstring

File the article in this category. Required unless collection_id is given — supply exactly one of the two.

body

collection_idstring

File the article directly in this collection, with no category. Required unless category_id is given.

body

titlestring

Required

The article's title. 1–512 characters.

body

contentstring

The article body as HTML. See Content format.

body

slugstring

URL-safe identifier, unique within your organization. Derived from title when omitted, with a unique suffix appended on collision. Max 512 characters.

body

excerptstring

Short summary shown in listings and search results. Max 512 characters.

body

status_codestring

Either "draft" or "published". Defaults to "draft".

body

show_on_portalboolean

Whether the article may appear publicly. Defaults to true. Visibility also requires status_code: "published".

body

favouriteboolean

Internal star for your team. Defaults to false. Never shown to customers.

body

related_article_idsarray

Ordered list of article UUIDs to show as "related" beneath this one. Every id must be an article in your organization.

body

author_idstring

UUID of the article's author. Defaults to the user who created the API key, so API-authored articles still attribute to a real person.

body

published_atstring

ISO 8601 publication timestamp. Stamped automatically with the current time when creating with status_code: "published" and no explicit value.

Creating with status_code: "published" and the default show_on_portal: true makes the article live on your public help center immediately. Create as a draft first if you want to review it in the dashboard.

Returns

A JSON object with the new article's id.

{ "id": "aa1c3ef8-b8cd-cd15-01ba-77bb77bb77bb" }

Example request

curl -X POST https://api.productbridge.io/api/external/v1/help-articles/create \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "pb_YOUR_PUBLIC_API_KEY",
    "category_id": "884c3ef8-b8cd-cd15-01ba-44bb44bb44bb",
    "title": "Reset your password",
    "content": "<p>From the sign-in screen, choose <strong>Forgot password</strong> and follow the emailed link.</p>",
    "excerpt": "How to reset your password from the sign-in screen.",
    "status_code": "published"
  }'

const res = await fetch(
  "https://api.productbridge.io/api/external/v1/help-articles/create",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: process.env.PRODUCTBRIDGE_API_KEY,
      category_id: "884c3ef8-b8cd-cd15-01ba-44bb44bb44bb",
      title: "Reset your password",
      content:
        "<p>From the sign-in screen, choose <strong>Forgot password</strong> and follow the emailed link.</p>",
      excerpt: "How to reset your password from the sign-in screen.",
      status_code: "published",
    }),
  }
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { id } = await res.json();

import os, httpx

resp = httpx.post(
    "https://api.productbridge.io/api/external/v1/help-articles/create",
    json={
        "api_key": os.environ["PRODUCTBRIDGE_API_KEY"],
        "category_id": "884c3ef8-b8cd-cd15-01ba-44bb44bb44bb",
        "title": "Reset your password",
        "content": "<p>From the sign-in screen, choose <strong>Forgot password</strong> "
                   "and follow the emailed link.</p>",
        "excerpt": "How to reset your password from the sign-in screen.",
        "status_code": "published",
    },
)
resp.raise_for_status()
new_id = resp.json()["id"]

Example response

{
  "id": "aa1c3ef8-b8cd-cd15-01ba-77bb77bb77bb"
}

Fetch the generated slug and published_at via Retrieve.

Filing directly in a collection

Omit category_id and send collection_id instead. The article's public URL then drops the category segment: /help/{collection_slug}/{article_slug}.

{
  "api_key": "pb_YOUR_PUBLIC_API_KEY",
  "collection_id": "553c3ef8-b8cd-cd15-01ba-12bb12bb12bb",
  "title": "What's new in v3",
  "status_code": "published"
}

Errors

Status	Body	Cause
`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 category not found"}}`	The `category_id` doesn't exist, or belongs to another organization.
`404`	`{"detail":{"error":"help collection not found"}}`	The `collection_id` doesn't exist, or belongs to another organization.
`422`	Validation error envelope	Both parents sent, neither sent, `title` missing or out of bounds (1–512), or `status_code` not `"draft"` / `"published"`.

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

Was this page helpful?