Search Articles

Articles are the content of a Kustomer knowledge base. Admins write them in the knowledge base editor. Customers read published public articles in the help center and in the chat widget, and agents look up articles, including internal ones, from the agent desktop. An article is a container. The title, htmlBody, slug and SEO fields live on its versions, with a separate series of versions for each language. The article itself holds what all languages share: categories, knowledgeBases (where featured pins it to that knowledge base's home page), tags, scope, hash (the short ID used in its URL) and source, the language it was first written in.

POST /v1/kb/articles creates the article and an empty draft in the source language, which defaults to the org's default language. You fill in the draft and publish it. To change the article later, you create a new draft. There is no DELETE for articles: send deleted: true to PUT /v1/kb/articles/{id} to soft-delete one.

Versions, languages and publishing

Each language has at most one draft and at most one published version. The version status shows which role a version plays:

To add a translation, create a version in the new language. Creating a version when a draft already exists replaces that draft. To publish, send publishedAt to PUT …/versions/{lang}/draft. You can include final edits in the same request. The previous live version becomes unpublished. Add markOthersOutOfDate: true to flag every other language as outdated, which tells translators to update them. On the article, latestLangs summarizes each language's live status and its outdated flag, and draftLangs lists the languages that have a draft.

Public and internal articles

scope is public (the default) or internal. Internal articles are only for signed-in Kustomer users. Set accessTeams or accessUsers on a draft to limit an internal article to those teams or users, and the limit takes effect when you publish. Admins can always see every article.

The /p/v3 endpoints are the customer view. They need no API key and only return published, public versions in the requested lang. They work out the org from the host, so call your org host, https://<org>.api.kustomerapp.com (see Regions and base URLs). That host serves the org's default knowledge base; pass knowledgeBaseId to read a different one. Each result is a published version: its id is the version ID, and the parent article is in attributes.article.

Scheduling

A schedule publishes a language's draft at a future time. Send lang, publishAt (at least one minute in the future) and tz (an IANA time zone such as America/New_York). The article must already have a draft in that language. Each language can have only one schedule, and {type} is always publish. Publishing by hand or deleting the draft cancels the schedule.

Which endpoint to use

Reads need a knowledge base read role such as org.user.kb.read. Writes need org.admin.kb.write or the matching org.permission.kb.* permission. If two writes to the same article overlap, one can fail with 409 Conflict; read the article again and retry. List endpoints page with page and pageSize.