There are two ways to work with knowledge in the public API. The recommended self-serve path is source-backed: ingest sources, generate drafts or live knowledge, review if needed, then organize and assign that knowledge. The advanced/manual path is to write and manage articles directly through Manage knowledge.
Reference pages
Initialize knowledge folders
POST /v2/knowledge/public/tree/initialize — generate a downloadable tree template for first-time structure setup.Persist knowledge folders
POST /v2/knowledge/public/tree/persist — import a tree file into the workspace knowledge graph.Generate knowledge
POST /v2/knowledge/public — queue one knowledge-generation job from candidate text.Bulk generate knowledge
POST /v2/knowledge/public/bulk — queue generate-and-save jobs for multiple source IDs.Check knowledge jobs
POST /v2/knowledge/public/jobs/status — poll one or more background jobs by ID.Manage knowledge
Read, create, update, draft, publish, and delete live articles.
Organize knowledge
Read the knowledge tree, manage folders, move articles between folders, and assign them to agents.
Recommended paths
Source-backed self-serve path
Ingest sources
Start from Sources and ingest the raw content you want to turn into knowledge.
Optionally initialize the first tree
If this is the first knowledge setup in the workspace, use Initialize knowledge folders and Persist knowledge folders to scaffold the initial folder structure.
Generate knowledge
Use Bulk generate knowledge for source-backed generation, or Generate knowledge when you already have candidate text.
Poll jobs and review when needed
Use Check knowledge jobs, then review or publish drafts before expecting live agent answers to change.
Organize and assign
Use Organize knowledge to shape the tree and attach the relevant folders to agents.
Direct manual path
Use Manage knowledge when you already know the live articles you want to create or update, and use Organize knowledge when you need to change the tree or agent visibility around them.Endpoint map
Knowledge generation
| Method | Path | Scope | Purpose |
|---|---|---|---|
POST | /v2/knowledge/public/tree/initialize | write | Generate a tree-import template file from an initialization prompt. |
POST | /v2/knowledge/public/tree/persist | write | Upload a tree file and persist it into the workspace knowledge graph. |
POST | /v2/knowledge/public | write | Queue one knowledge-generation job from candidate text. |
POST | /v2/knowledge/public/bulk | write | Queue generate-and-save jobs for multiple source IDs. |
POST | /v2/knowledge/public/jobs/status | read | Check status for one or more background knowledge jobs. |
Manage knowledge
| Method | Path | Scope | Purpose |
|---|---|---|---|
GET | /v2/hc-articles/public | read | List articles. Use type=live or type=draft to filter. |
POST | /v2/hc-articles/ids/public | read | Fetch one or more articles by ID. |
POST | /v2/hc-articles/public | write | Create a live article or draft article. |
PUT | /v2/hc-articles/:id/public | write | Update an existing article. |
POST | /v2/hc-articles/:id/draft/public | write | Create a draft from an existing live article. |
POST | /v2/hc-articles/:id/publish/public | write | Publish a draft article. |
DELETE | /v2/hc-articles/:id/public | write | Delete an article. |
Organize knowledge
| Method | Path | Scope | Purpose |
|---|---|---|---|
GET | /v2/hc-folders/public | read | Return the current knowledge-tree snapshot, optionally filtered by botId. |
POST | /v2/hc-folders/public | write | Create a folder in the knowledge tree. |
PUT | /v2/hc-folders/:id/public | write | Update a folder’s title, description, or active state. |
PUT | /v2/hc-folders/:id/move/public | write | Move a folder under a different parent. |
PUT | /v2/hc-articles/:id/move/public | write | Move an article into a different folder. |
DELETE | /v2/hc-folders/:id/public | write | Delete a folder. |
POST | /v2/hc-bot-folder-junctions/public | write | Assign or unassign folders to agents in bulk. |
The article read surface is now unified under
GET /v2/hc-articles/public. There is no workspace-API-key GET /v2/hc-articles/:id/public route in the current controller. If you need a direct lookup by ID, use POST /v2/hc-articles/ids/public with one or more articleIds.