> ## Documentation Index
> Fetch the complete documentation index at: https://hanabiaiinc-fish-772-enterprise-versions.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 — you never re-upload a file to make a change.
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 — there is no background processing to wait for. 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 — fix the file and try again.
### 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 — you never update agents one by one. 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 — the content is already in the prompt.
### 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.