> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge

> Generate knowledge from sources, manage live articles, organize the tree, and assign knowledge to agents.

Knowledge is the live side of Fini. [Sources](/en/api-reference/sources) feed into it, agents retrieve from it, and these routes let you generate, manage, organize, and assign that knowledge.

<Info>
  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](/en/api-reference/manage-knowledge).
</Info>

## Reference pages

<CardGroup cols={3}>
  <Card title="Initialize knowledge folders" icon="folder" href="/en/api-reference/initialize-knowledge-folders">
    `POST /v2/knowledge/public/tree/initialize` — generate a downloadable tree template for first-time structure setup.
  </Card>

  <Card title="Persist knowledge folders" icon="upload" href="/en/api-reference/persist-knowledge-folders">
    `POST /v2/knowledge/public/tree/persist` — import a tree file into the workspace knowledge graph.
  </Card>

  <Card title="Generate knowledge" icon="wand-magic-sparkles" href="/en/api-reference/generate-knowledge">
    `POST /v2/knowledge/public` — queue one knowledge-generation job from candidate text.
  </Card>

  <Card title="Bulk generate knowledge" icon="layer-group" href="/en/api-reference/bulk-generate-knowledge">
    `POST /v2/knowledge/public/bulk` — queue generate-and-save jobs for multiple source IDs.
  </Card>

  <Card title="Check knowledge jobs" icon="clock" href="/en/api-reference/check-knowledge-jobs">
    `POST /v2/knowledge/public/jobs/status` — poll one or more background jobs by ID.
  </Card>

  <Card title="Manage knowledge" icon="book-open" href="/en/api-reference/manage-knowledge">
    Read, create, update, draft, publish, and delete live articles.
  </Card>

  <Card title="Organize knowledge" icon="folder" href="/en/api-reference/organize-knowledge">
    Read the knowledge tree, manage folders, move articles between folders, and assign them to agents.
  </Card>
</CardGroup>

## Recommended paths

### Source-backed self-serve path

<Steps>
  <Step title="Ingest sources">
    Start from [Sources](/en/api-reference/sources) and ingest the raw content you want to turn into knowledge.
  </Step>

  <Step title="Optionally initialize the first tree">
    If this is the first knowledge setup in the workspace, use [Initialize knowledge folders](/en/api-reference/initialize-knowledge-folders) and [Persist knowledge folders](/en/api-reference/persist-knowledge-folders) to scaffold the initial folder structure.
  </Step>

  <Step title="Generate knowledge">
    Use [Bulk generate knowledge](/en/api-reference/bulk-generate-knowledge) for source-backed generation, or [Generate knowledge](/en/api-reference/generate-knowledge) when you already have candidate text.
  </Step>

  <Step title="Poll jobs and review when needed">
    Use [Check knowledge jobs](/en/api-reference/check-knowledge-jobs), then review or publish drafts before expecting live agent answers to change.
  </Step>

  <Step title="Organize and assign">
    Use [Organize knowledge](/en/api-reference/organize-knowledge) to shape the tree and attach the relevant folders to agents.
  </Step>
</Steps>

### Direct manual path

Use [Manage knowledge](/en/api-reference/manage-knowledge) when you already know the live articles you want to create or update, and use [Organize knowledge](/en/api-reference/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.                               |

<Note>
  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`.
</Note>