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

# Basic Operations Guide

> How to perform common Sources & Topics API workflows.

Use the [Source API reference](/api-reference/knowledge-agent/sources/list-sources) for request/response details, parameters, and examples. Send `X-API-KEY` on every request; add `?organization_name=YourOrg`. Base URL is typically `https://api-prod.voltai.ai/source/api`.

## 1. Create a topic

Use [POST /topics](/api-reference/knowledge-agent/topics/create-topic) to create a root topic, a child (with `parent_topic_uuid`), or a full path in one call (`topic_path`). Store the returned `uuid` for later.

## 2. Find a topic

Topics are identified by **UUID**. Use [GET /topics](/api-reference/knowledge-agent/topics/list-topics) with `search` or `topic_path` to resolve a name or path to a UUID, or [GET /topics/tree](/api-reference/knowledge-agent/topics--tree-&-sources/get-topic-tree) to load the full tree.

## 3. Add a source to a topic

Either [POST /sources](/api-reference/knowledge-agent/sources/create-source) (multipart upload with `topic_uuids`) or [POST /sources/bulk-action](/api-reference/knowledge-agent/sources--bulk-actions/bulk-actions-on-sources) with `action: "add-to-topic"` to attach existing sources to a topic.

## 4. Change topic structure

Use [PATCH /topics/{uuid}](/api-reference/knowledge-agent/topics/partial-update-topic) to rename or move a topic (set `parent_topic_uuid` or `null` for root). Use [DELETE /topics/{uuid}](/api-reference/knowledge-agent/topics/delete-topic) to remove a topic and its subtopics.

## 5. Bulk actions on topics

Use [POST /topics/bulk-action](/api-reference/knowledge-agent/topics--bulk-actions/bulk-actions-on-topics) with `action: "create"`, `"create-topic-paths"`, `"update"`, or `"delete"` to create, update, or delete multiple topics.

## 6. Change a source's topics

Use [PATCH /sources/{name}](/api-reference/knowledge-agent/sources/partial-update-source) with `topic_uuids` to set a source’s topic list. Use [POST /sources/bulk-action](/api-reference/knowledge-agent/sources--bulk-actions/bulk-actions-on-sources) with `action: "remove-from-topic"` to remove sources from a topic.

List endpoints support `page` and `page_size`. Source names must match exactly; URL-encode them in paths when needed.

## 7. Search and retrieve chunks

Use [`POST /retrieve/`](/api-reference/knowledge-agent/retrieve-chunks) for **keyword** or **semantic** search over indexed content without using the chat agent. The API returns ranked chunks with text, page, and bounding boxes. API keys with granular permissions need the **`retrieval`** scope for this endpoint.