The journey of an item
- Add a text or a file.
- Read: Hamsa takes the text out of the file.
- Chunk: the text is cut into chunks, the way you choose.
- Review (optional): you read the chunks and fix them.
- Index: each chunk is embedded and stored, so it can be found.
- Search: on calls, agents that use the item search its chunks.
1. Add an item
POST /v1/voice-agents/knowledge-base takes one or more items:
Each item needs an
itemName (up to 100 characters). Every item, text or file, counts towards your plan’s knowledge base storage, which is shared by every project the owner of this project owns, each member’s items included.
How files are read
After reading, the text must have at least 50 characters, or the item fails with
READING_FAILURE.
2. Two ways to process an item
How you send the request decides the path:
To choose a chunking method, or to see and edit chunks, send
chunkingConfig or autoIndex: false.
Statuses
Read an item’s status with
GET /v1/voice-agents/knowledge-base/{id}. Hamsa retries a failed step up to 3 times before marking it failed.
3. Choose a chunking method
SetchunkingConfig.strategy:
When a method can’t be used
The item is chunked withBY_PARAGRAPH instead when:
QA_PAIRSfinds no questions.BY_PAGEfinds only one page (for example, aTEXTitem).LLM_GUIDEDcan’t reach the AI model, or it fails.SEMANTICcan’t measure meaning for a section (only that section is cut by paragraph).
4. Size and structure settings
Chunk sizes are measured in tokens: small pieces of words. The default 400 tokens is about 270 English words or 180 Arabic words. Every language is counted the same way.
A value outside its range is refused with 400 (for example
ChunkingTargetTokensMustBeValid). Settings that contradict each other are refused with 400 too, never adjusted: minTokens and overlapTokens can be at most half of targetTokens (ChunkingMinTokensExceedsHalfTarget, ChunkingOverlapTokensExceedsHalfTarget), maxTokens must be at least targetTokens (ChunkingMaxTokensBelowTarget), minTokens can’t be above maxTokens (ChunkingMinTokensExceedsMaxTokens), and QA_PAIRS takes no overlapTokens, since each question and answer has to stand alone (ChunkingOverlapTokensNotAllowedForQaPairs). When you leave out targetTokens, these are checked against 400. What you send is what runs.
Where to start
Adding context (addContext)
A chunk like “It costs 50 SAR a month” is hard to find: what costs 50 SAR? With addContext, an AI model reads the document (for one over 60,000 characters, its outline and the part around the chunk) and writes a short line for each chunk, in the chunk’s language, such as “From the pricing section, about the Premium plan.”, and puts it at the start of the chunk. That line is searched along with the chunk. It makes chunking take longer, and it is skipped in previews. A chunk whose line can’t be written is saved without one. When no chunk got a line, contextApplied is false in the item’s chunking settings; you can regenerate to try again.
Marks on chunks
Chunks can come back marked so you know what to check:
Exact duplicate chunks are dropped.
With
overlapTokens above 0, each chunk’s metadata says whether it got an overlap: overlapApplied, with overlapTokenCount when it did, or overlapSkipReason when it didn’t (for example first_chunk, table or after_qa_pair).
5. Preview before you commit
Try settings on an item without saving anything (it previews the first 20,000 characters; an item added with standard processing has no stored text to preview):POST /v1/voice-agents/knowledge-base/{id}/chunks/preview.
6. Review and edit chunks
While an item isPENDING_REVIEW, or any time after:
All paths start with
/v1/voice-agents/knowledge-base.
Edits are refused (422) while the item is
PROCESSING. After you edit, the item has changes that aren’t indexed yet: agents keep finding the old chunks until you index again. Changing only spaces doesn’t count as a change.
7. Index
POST /v1/voice-agents/knowledge-base/{id}/index makes the chunks searchable.
- Only new and changed chunks are embedded again; deleted chunks are removed from search.
- If nothing changed since the last index, nothing happens.
- A chunk over 2,048 tokens isn’t indexed: it is marked with an index error, and the rest of the item is indexed. Shorten it and index again.
- The item is
PROCESSEDwhen at least one chunk is stored.
8. Start over or stop
9. How agents search on calls
An agent searches only the items you add to it, and onlyPROCESSED items can be added.
The agent’s Agentic RAG setting decides who starts the search:
Either way, every search:
- Turns the search into an embedding, the same way chunks were embedded. Arabic and English work the same way.
- Keeps the 3 closest chunks that are at least 75% similar, and no more than 5 points below the best one.
- Gives the agent those chunks, each cut to its first 600 characters.
This is how agents run with the smart context manager on, the default for new agents. With it off, Hamsa searches on every caller turn (or when the agent calls the tool), keeps the 5 closest chunks at least 70% similar, gives them whole, and keeps nothing between turns.
10. Errors
Examples
A FAQ, reviewed, then indexed
A FAQ, reviewed, then indexed
- Add it with
"autoIndex": falseand"chunkingConfig": {"strategy": "QA_PAIRS", "targetTokens": 200}. - Wait for
PENDING_REVIEW, then list the chunks and check each question has its answer. - Fix or delete chunks, then call
/index. - When the item is
PROCESSED, add it to your agent.
A manual with custom settings
A manual with custom settings
- Add the file with
"chunkingConfig": {"strategy": "SEMANTIC", "targetTokens": 250, "overlapTokens": 40, "addContext": true}. - It is chunked and indexed in one go; wait for
PROCESSED. - List the chunks marked too short or oversized and fix them, then index again.
Updating an item agents already use
Updating an item agents already use
- Edit the chunks you need to change.
- Call
/index: only the changed chunks are embedded again. - Agents find the new text from then on.
Related
Knowledge base in Hamsa Agents
Add items and review chunks in the dashboard.
API reference
Every knowledge base endpoint.