Search

Send a question in everyday language. Knovas returns the documents that match its meaning best.

Run a search

curl -X POST https://api.knovas.ch:8443/secured/query \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"Input": "What were the Q3 revenue figures?"}'

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

r = requests.post(f"{BASE}/secured/query", **AUTH, json={"Input": "What were the Q3 revenue figures?"})
r.raise_for_status()
answer = r.json()

for hit in answer["results"]:
    print(hit["pointer"], hit["page_number"], round(hit["final_score"], 2))

Knovas only ever searches your own documents. The number of results is set by Knovas, not in the request.

Read the results

Answer (shortened)

{
  "status": "success",
  "query_session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "result_count": 1,
  "results": [
    {
      "pointer": "reports/2025/q3.pdf",
      "document_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "final_score": 0.91,
      "page_number": 3,
      "sentence_number": 12
    }
  ]
}

Field	Meaning
`results`	The matching documents, best first.
`pointer`	The identifier you gave the document at upload.
`final_score`	How well it matches. Higher is better. Use it for sorting, not as a percentage.
`page_number`, `sentence_number`	Where the best passage is (empty if you did not send numbers).
`document_uuid`	Knovas’ own id for the document. Use it to look up the document’s details.
`query_session_id`	The id of this search. Needed if you send feedback.

Results contain no full document text, only names, scores and locations. Your own software opens the original document using the pointer.

When nothing is found

You still get a normal answer, with "results": []. Some setups only return results that are clearly relevant; then you may get fewer results than usual, or none, and each result carries relevance_tier (strong or borderline).

Several phrasings at once

Send a list of questions to search for all of them together. This finds more, and counts as one request against your speed limit:

curl -X POST https://api.knovas.ch:8443/secured/query \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"Input": ["Q3 revenue", "third quarter earnings", "sales July to September"]}'

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

r = requests.post(f"{BASE}/secured/query", **AUTH, json={
    "Input": ["Q3 revenue", "third quarter earnings", "sales July to September"],
})

Search on behalf of a user

If you use access control, add access_groups with the groups of the person who is searching. Knovas then only returns documents that person may see.

curl -X POST https://api.knovas.ch:8443/secured/query \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"Input": "notice period", "access_groups": ["Legal"]}'

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

r = requests.post(f"{BASE}/secured/query", **AUTH, json={
    "Input": "notice period",
    "access_groups": ["Legal"],   # the groups of the user who is searching
})

Automatic narrowing by name

If you use the knowledge graph, Knovas recognises names of your cases or clients inside a question. “What medication does Michael Xample take?” then searches only Michael’s documents. If that finds nothing, Knovas automatically searches everything instead.

When this happened, the answer contains an auto_scope section. If results look unexpectedly narrow, check it first.

Tips for better results

Search in the language of your documents. German documents are best searched in German.
Use the words a document would use. “Medication dosage” finds more than “what pills”.
Send several phrasings in one request (see above).
Good uploads matter most. Titles and clean text at upload matter more than how the question is phrased. See the upload checklist.

Reduced quality notice

In rare cases Knovas answers with meta.degraded_to_bm25: true. The results are real but were found by exact words only. Try again a little later for full-quality results.

Questions? Write to contact@knovas.ch.

This page describes Knovas 1.3.0. Last updated 24 September 2026.