> ## Documentation Index
> Fetch the complete documentation index at: https://hanabiaiinc-chore-update-openapi-schema.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Knowledge Base
> Ground your agent in your own documents: add a source once, attach it to any agent in your workspace
The knowledge base is a workspace-wide document library. Add a source once (an uploaded Markdown or plain-text file) and attach it to any number of agents. In conversation, the agent draws on attached sources to answer questions its [instructions](/agents/build/configuration) alone can't cover: product details, policies, FAQs, procedures.
## Add sources
Sources come in two scopes:
* **Workspace sources** live in the shared library. Add them from the workspace-level **Knowledge base** page with **Add file**: choose a `.md` or `.txt` file (UTF-8 text, up to 1 MB) and give the source a name and an optional description. Workspace sources can be attached to any number of agents.
* **Agent-private sources** belong to a single agent. On your agent's **Knowledge base** tab, **New private file** creates a source that is attached to that agent immediately. It doesn't appear in the shared library, can't be attached to other agents, and is not listed by the [knowledge-sources API](#manage-sources-over-the-api).
To attach a shared source to an agent, open the agent's **Knowledge base** tab and click **Import from global knowledge base**.
Every source is plain text and stays editable after upload: open a source to view its content and edit the text in place.
PDF, Office, and scanned documents are not supported. Convert them to Markdown or plain text first.
### Upload validation
Files are validated, parsed, and indexed as part of the upload itself. When the upload succeeds, the source is immediately available to attached agents. If the file is empty, over 1 MB, or not UTF-8 text, the upload is rejected with an error and nothing is created.
### Folders
Group sources into folders with **New folder**, and rename sources from the row menu. Deleting a folder never deletes its sources. Anything inside moves back to **All sources**.
## Share sources across agents
Workspace sources belong to the workspace, not to a single agent (agent-private files offer only **Edit** and **Delete**). In the library, the **Used by** column shows how many agents attach each source, and **Manage access** lists every agent with a toggle:
* **Attach**: Turn an agent on to give it access to the source.
* **Detach**: Turn an agent off. The source stays in the library and remains attached to other agents.
Editing a source propagates to every agent that attaches it. Each attached agent shows the edit as an unpublished draft change.
**Delete** removes a source from *all* agents that reference it, not just the one you're editing. To remove a source from a single agent, detach it with **Manage access** instead.
## How your agent uses knowledge
### Small corpora are inlined
If the total size of an agent's attached sources is **8 KB or less**, the full content is inlined into the agent's instructions. This is the fastest path: the agent has everything up front, with zero per-turn lookup cost.
Inlined knowledge produces no retrieval events. If your corpus is small and you don't see retrieval activity, nothing is wrong.
### Larger corpora are searched per turn
Above 8 KB, the agent searches attached sources on every turn, using the user's latest message as the query, and injects the best-matching passages into that turn's context. The search runs under a fixed time budget: if it can't complete in time, the turn is answered without retrieved context. Retrieval never delays the agent's reply.
### Publishing pins revisions
When you [publish](/agents/deploy/versions-publishing) an agent, the published version pins the then-current revision of every attached source. Sessions read the pinned revisions, so edits you make mid-call never leak into an in-progress conversation. Publish again to roll updated content out.
## Limits
| Limit | Value |
| ------------------- | --------------------------- |
| File upload formats | `.md`, `.txt` |
| File size | 1 MB per file |
| Sources per agent | 100 |
| Inline threshold | 8 KB total attached content |
Attaching more than 100 sources to one agent is rejected with `422`.
## Manage sources over the API
Knowledge sources are exposed at `/v1/agent/knowledge-sources`. Only workspace sources appear on this surface. Agent-private files are a console-only convenience:
| Endpoint | Description |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET /v1/agent/knowledge-sources` | List sources in your workspace |
| `POST /v1/agent/knowledge-sources` | Create a source: multipart upload with the `.md`/`.txt` file in the `source` field |
| `GET /v1/agent/knowledge-sources/{source_id}` | Retrieve a source |
| `PATCH /v1/agent/knowledge-sources/{source_id}` | Rename a source or replace its content. Multipart like create; omitted fields keep their values, and a new `source` file bumps `revision_number` |
| `DELETE /v1/agent/knowledge-sources/{source_id}` | Delete a source |
| `GET /v1/agent/knowledge-sources/{source_id}/agents` | List agents that attach the source |
```bash Create a source theme={null}
curl --request POST https://api.fish.audio/v1/agent/knowledge-sources \
--header "Authorization: Bearer $FISH_API_KEY" \
--form "source=@faq.md;type=text/markdown" \
--form "name=Customer FAQ" \
--form "description=Answers for the support agent"
```
```bash Replace content theme={null}
curl --request PATCH https://api.fish.audio/v1/agent/knowledge-sources/{source_id} \
--header "Authorization: Bearer $FISH_API_KEY" \
--form "source=@faq-v2.md;type=text/markdown"
```
```bash Check dependents theme={null}
curl https://api.fish.audio/v1/agent/knowledge-sources/{source_id}/agents \
--header "Authorization: Bearer $FISH_API_KEY"
```
Only the `source` file part is required on create: `name` falls back to the uploaded file's name.
`DELETE` returns `409` while the source is still attached to any agent, in its draft or its published version. Call the dependents endpoint to see which agents use it, then detach it from each (remove its id from `knowledge_base.knowledge_source_ids` in an agent update) and republish any agent whose published version still references it. Deleting from the console instead removes the source from all agents at once, after a confirmation.
## Going further
Instructions, voice, and everything else your agent is made of.
How publishing snapshots your agent, knowledge revisions included.
Talk to your draft and check knowledge answers before publishing.
Review transcripts of past sessions.