Sawalni API
APIsDocumentationOpen portal ↗
Omneity Labs API collection ↗Integration quickstart →API keys and playgrounds →
Apps

Khizana · Knowledge Search

Khizana turns a small collection of business documents into tenant-isolated hybrid search. The same index can power a programmatic API, a drop-in website widget, a branded standalone search page, and Batbot retrieval.

Create a Khizana

Open Khizana, create a collection, and copy the generated swl_kb_… search key. The raw key is shown only once.

Upload PDF, DOCX, TXT, or Markdown documents, or choose Write here to create a text source directly in the portal. You can select or drop a batch and track each file through upload, security processing, chunking, and indexing. You can safely select a batch again after an interruption: content hashes identify and skip files that are already ready. Inline sources are normalized, saved as text-source records, checked for instruction-like prompt injection, and indexed without retaining an uploaded original. Each Khizana accepts up to 100 MB total across at most 100 sources. Each uploaded file can be up to 5 MB. A source becomes searchable only after its status is ready. Delete a source from the source list to remove both its record and all of its indexed search points.

Chunking controls

Choose a preset before adding a source:

PresetChunk / overlapBest for
Precise700 / 100 charactersFAQs, policies, and short answers
Balanced1200 / 160 charactersGeneral documentation; default
Broad context1800 / 240 charactersNarrative and long-form explanations

Advanced controls accept a chunk size from 400–2400 characters and overlap from 0–400 characters. Overlap must remain below half the chunk size. The selected profile is stored on the Khizana and snapshotted on each new source; changing it does not silently reindex existing sources.

How retrieval works

Every query combines:

  • madmon-beta semantic embeddings;
  • sawtone-v4 cross-script and phonetic representations;
  • sparse keyword matching;
  • reciprocal-rank fusion across all three result lists.

Every vector operation is filtered by both owner and Khizana id. Results include the source name, source id, chunk number, excerpt, and fused score.

Usage and billing

Khizana uses the dedicated API credential created for its owner. Indexing sends each chunk through madmon-beta and sawtone-v4, so both model calls are recorded by the normal Sawalni credit ledger. Each API, widget, standalone-page, Batbot, or portal test search likewise sends its query through both models and is billed to the Khizana owner.

Sparse keyword fusion and Qdrant index storage are currently included and do not create an additional charge. Chunking happens locally before model calls; smaller chunks can improve precision but usually create more billable embedding input and request batches. Usage appears in the existing Dashboard and Billing views under the Khizana-owned API credential.

Programmatic Search API

POST /api/public/knowledge/{KHIZANA_ID}/search

bash
curl -X POST 'https://api.sawalni.com/api/public/knowledge/KHIZANA_ID/search' \ -H 'Authorization: Bearer swl_kb_REPLACE_ME' \ -H 'Content-Type: application/json' \ -d '{"query":"What is the return policy?","limit":5}'
json
{ "query": "What is the return policy?", "results": [ { "sourceId": "…", "sourceName": "returns.pdf", "chunk": 3, "text": "Returns are accepted within 14 days…", "score": 0.83 } ] }

limit is optional and is clamped to 1–10. Keep the search key on a trusted server.

Optional browser origin

Khizana can grant CORS to one exact origin such as https://shop.example.ma. The value must contain only the HTTP/HTTPS scheme, hostname, and optional port. Paths, credentials, wildcards, opaque null origins, and subdomain expansion are rejected.

CORS is a browser policy, not authentication. The Bearer key remains required and server-side callers can continue without an Origin header.

Drop-in Search Widget

Add each embedding site under Allowed websites, save the Khizana, then paste:

html
<script async src="https://api.sawalni.com/khizana.js?kb=KHIZANA_ID"></script>

The loader checks the embedding page's domain and returns a private, non-cacheable script containing a short-lived signed search session. The search API key is never sent to the browser. The iframe follows the host page's language and RTL/LTR direction.

Standalone Search Page

Standalone pages are enabled by default:

text
https://api.sawalni.com/k/KHIZANA_ID

Disable the page from Publish & customize when the collection should be API- or Batbot-only. Unpublishing disables the widget and standalone page without revoking the server-side search key.

Theme and branding

The portal lets you customize:

  • accent color and PNG/JPEG logo;
  • search-page heading and placeholder;
  • widget button label;
  • standalone-page availability;
  • embedding domains and API browser origin.

The standalone page and widget share the same theme and citation-first result layout.

Attach Khizana to Batbot

Choose an existing Khizana in Batbot, or create one inline and optionally upload its first document. Use Open advanced Khizana editor for branding, publishing, API, widget, and source configuration.

Batbot treats retrieved passages as untrusted evidence. Evidence cannot override the creator's instructions and factual answers cite the retrieved source numbers.

Document security

  • ClamAV scanning fails closed in production.
  • Extraction runs without Internet access as an unprivileged process in a read-only container.
  • Active PDFs, embedded files, encrypted PDFs, macros, OLE objects, ActiveX, external DOCX relationships, unsafe archive paths, and suspicious decompression are rejected.
  • Originals are discarded after inspection; only normalized chunks and source metadata enter the index.
  • Prompt-injection-like source content can be quarantined before indexing.

Common responses

HTTP codeMeaning
400Missing query or invalid configuration
401Missing or invalid Khizana search key/session
403Browser origin or embedding domain not allowed
404Khizana or public surface unavailable
413The 5 MB collection limit was exceeded
422Document failed security inspection or parsing
429Public search rate limit exceeded
503A required scanner or retrieval service is unavailable