Set up your knowledge base

Create and organize Anam knowledge groups so personas can retrieve relevant information from your documents during conversations.

Overview

Create knowledge folders, called groups in the API, for the reference material your persona needs. Choose the audience and scope first, then create folders and prepare your documents for upload.

Knowledge Base is currently in beta. Please report issues or feedback to support.

Before you begin

What you’ll need:

• An API key, used only from your server — see Authentication
• Documents to upload — see supported file types
• Basic understanding of your content organization

Time to complete: 10-15 minutes

Set the knowledge scope

Choose the reference material appropriate for the persona’s audience before creating folders. A customer support persona may need public help articles and product information; an internal support persona may also need private troubleshooting notes.

Don’t	Do
Upload a whole project folder without checking its contents.	Select the approved reference files explicitly.
Mix internal account notes into a public support folder.	Keep public and internal reference material in separate folders and restrict access in your application.
Put personality or “always upsell” instructions in product documents.	Keep behavior instructions in the persona’s prompt.
Create a separate search tool for every file automatically.	Group related knowledge; separate it when audience, permissions, or workflow require it.

Attach only appropriate folders to the persona’s knowledge tools. Check every tool on the persona: an internal folder attached through a second tool is still accessible to it. Enforce who can use internal personas and tools in your application.

A filename, an “internal only” label, or an Applies to field helps interpretation but does not enforce permissions or configure metadata filters. Do not attach private material to a public persona and rely on its prompt to hide it.

Quick check: Are drafts, superseded revisions, prompts, test transcripts, and review notes excluded? Is every file in every attached folder appropriate for this audience? Keep these preparation guides outside the reference folders unless the persona’s purpose is to teach this process.

Zero Data Retention does not cover files uploaded to a knowledge base. Uploaded documents are stored so they can be searched, even for personas and sessions that have Zero Data Retention enabled. Take that into account when deciding what belongs in a knowledge folder.

Plan your folder structure

Knowledge folders organize your documents by topic, use case, or category. Think of them as searchable collections that can be assigned to different knowledge tools. Start with the topics your persona needs, and add specialized folders as you go.

Your Organization
├── Product Documentation (Folder)
│   ├── user-guide.pdf
│   ├── api-reference.md
│   └── faq.pdf
│
├── Technical Support (Folder)
│   ├── troubleshooting-guide.pdf
│   ├── error-codes.txt
│   └── common-issues.md
│
└── Customer FAQs (Folder)
    ├── billing-faq.md
    ├── account-faq.md
    └── shipping-faq.pdf

Focused folders let you limit a knowledge tool to the topics its audience needs, and let you update one knowledge domain without disturbing the others.

Choose a grouping

Group by	Looks like	Good for
Content type	Product Documentation, API Reference, User Guides, FAQs, Policies	SaaS products, developer platforms
Department	Sales Resources, Support Knowledge Base, HR Policies, Engineering Docs	Internal knowledge bases, employee assistants
User journey	Getting Started, Basic Features, Advanced Features, Troubleshooting	Customer support, onboarding assistants
Product or service	Product A Documentation, Product B Documentation, General Company Info	Multi-product companies

Name folders clearly

Use names that describe the contents, such as Customer Billing FAQs or Product Installation Guides. Avoid vague names such as Documents, Stuff, or Files.

Keep folders focused as you grow

Give each folder a clear purpose. As your content grows, split broad topics into more focused folders when that helps you manage the documents or select what a tool should search. For example, a product documentation folder could become separate installation, configuration, and troubleshooting folders.

When reorganizing, update the folders selected by your knowledge tools and test retrieval to check that the persona can still find the intended information.

Create a folder

UI

Knowledge lives in the Knowledge card on the Prompt tab of the Build page, alongside the persona it belongs to.

1. Open the persona

   Go to the Prompt tab in Anam Lab for the persona you are building, and find the Knowledge card.

2. Open the knowledge library

   Select Manage folders — or Browse existing folders, if your organization already has some.

3. Name the folder

   Select New folder, type a name of 1-100 characters, and select Create.

   Use a name that describes the contents, such as “Customer Billing FAQs”.

4. Link it to the persona

   Tick the folder’s checkbox to let this persona search it, then select Done.

   The folder appears in the library with its file count. A folder linked by more than one persona shows a Shared badge.

To skip straight to uploading, select Upload documents instead. Anam creates a folder named after the persona, so you only need the library above when you want to choose the name yourself or reuse an existing folder.

API

Create folders programmatically using the API. Repeat the request for each folder in your plan.

cURL

curl -X POST "https://api.anam.ai/v1/knowledge/groups" \
  -H "Authorization: Bearer ${ANAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Product Documentation",
    "description": "Technical guides and product information for customer support"
  }'

The name is required and limited to 100 characters; the description is optional and limited to 500.

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Product Documentation",
  "description": "Technical guides and product information for customer support",
  "documentCount": 0,
  "createdAt": "2024-03-10T10:30:00Z",
  "updatedAt": "2024-03-10T10:30:00Z"
}

Save the folder id - you’ll need it for uploading documents and creating knowledge tools.

View and manage folders

UI

Open the Knowledge library from the Knowledge card on the Prompt tab. Every folder in your organization is listed there, each with its file count and a checkbox showing whether this persona can search it.

Expand a folder to see its documents and their status. A document reads Processing while it is being indexed, shows its file size once it is searchable, or shows an error if indexing failed.

To rename a folder, select the pencil icon on its row, type the new name, and press Enter. Individual documents cannot be renamed in the Lab — use the API for that.

To delete a folder, select the trash icon on its row and confirm. The dialog warns you if other personas are linked to that folder, since deleting it removes their access too. To remove a single document instead, expand the folder and select the trash icon on its row.

Deleting a folder deletes all documents inside it. This action cannot be undone.

API

List all folders in your organization:

curl -X GET "https://api.anam.ai/v1/knowledge/groups" \
  -H "Authorization: Bearer ${ANAM_API_KEY}"

Response: a bare array of knowledge groups.

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product Documentation",
    "description": "Technical guides and product information",
    "documentCount": 0,
    "createdAt": "2024-03-10T10:30:00Z",
    "updatedAt": "2024-03-10T10:30:00Z"
  },
  {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "name": "Technical Support",
    "description": "Troubleshooting guides and error documentation",
    "documentCount": 0,
    "createdAt": "2024-03-10T10:31:00Z",
    "updatedAt": "2024-03-10T10:31:00Z"
  }
]

Rename a folder or change its description with PUT. Omit a field to leave it unchanged.

curl -X PUT "https://api.anam.ai/v1/knowledge/groups/FOLDER_ID" \
  -H "Authorization: Bearer ${ANAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Folder Name",
    "description": "Updated description"
  }'

Delete a folder and everything in it:

curl -X DELETE "https://api.anam.ai/v1/knowledge/groups/FOLDER_ID" \
  -H "Authorization: Bearer ${ANAM_API_KEY}"

This performs a soft delete (sets deleted_at timestamp). Documents are removed from search immediately.

Supported file types

Every file is limited to 50MB.

Format	Typical content
PDF	Product manuals, guides, reports, brochures
TXT	Plain text documentation and notes
MD	Technical documentation, README files, wikis
DOCX	Word documents, reports, guides
CSV	Structured data, product catalogs, FAQs
JSON	Structured data, API responses, configurations
LOG	Log files and system outputs

File types that can carry active content — SVG, HTML, XML, JavaScript, and SWF — are always rejected, whether they are identified by file extension or by content type.

Upload limits

Two separate limits apply to uploads.

File size is capped at 50MB per document for every plan. A larger file is rejected before the upload begins.

Monthly upload allowance is measured in megabytes uploaded per calendar month, and the size of that allowance depends on your plan. Usage resets at the start of each month. If an upload is rejected for exceeding it, the error states how much of the allowance is left.

Other limits worth knowing when you call the API directly:

• A filename can be at most 255 characters.
• A search query can be at most 1000 characters, and a search returns at most 20 results.

Need higher limits? Contact us about Enterprise plans with custom upload limits tailored to your needs.

Next steps

Prepare documents

Write reference material that stays clear when a single passage is retrieved on its own.

Upload documents

Upload your prepared files and check that processing completes.

Connect knowledge tools

Let the persona search the folders you created.

Document template

Start from a structure that keeps scope, sources, and exceptions together.