Quickstart

Go from zero to your first search in about 15 minutes. Each step links to a page with more detail.

Before you start

You need:

The registration key from your Knovas welcome email.
A terminal with curl and jq, or Python 3 with the requests package (pip install requests).
The address of your Knovas server. In these docs we use api.knovas.ch.

curl or Python

Every request example comes in two versions. Pick curl or Python above any example. All examples switch at once, and the docs remember your choice. The Python examples use the requests package (pip install requests).

1. Get your digital ID

Exchange your registration key for a certificate. This is a one-time step. The example is for a person; organisations send their address instead (see Connect your account).

umask 077   # files created below are readable by you only
RESPONSE=$(curl -s -X POST https://api.knovas.ch/create_entity \
  -H "Content-Type: application/json" \
  -d '{"key": "<your registration key>",
       "entity_data": {"first_name": "Jane", "last_name": "Doe"}}')

# Remove old copies first: permissions only apply to newly created files
rm -f client_cert.pem client_key.pem ca_root_cert.pem
echo "$RESPONSE" | jq -r '.certificate_pem' > client_cert.pem
echo "$RESPONSE" | jq -r '.private_key'     > client_key.pem
echo "$RESPONSE" | jq -r '.ca_root_cert'    > ca_root_cert.pem

import os
import requests

r = requests.post("https://api.knovas.ch/create_entity", timeout=60, json={
    "key": "<your registration key>",
    "entity_data": {"first_name": "Jane", "last_name": "Doe"},
})
r.raise_for_status()
answer = r.json()

# Save the three files straight away
for field, filename in [("certificate_pem", "client_cert.pem"),
                        ("private_key", "client_key.pem"),
                        ("ca_root_cert", "ca_root_cert.pem")]:
    # Start from a fresh file that only you can read (0o600). Permissions
    # only apply to new files, so an old copy is removed first.
    if os.path.lexists(filename):
        os.remove(filename)
    fd = os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
    with os.fdopen(fd, "w") as f:
        f.write(answer[field])

Save these three files now

The private key is sent only once. Store the three files somewhere safe, such as a password manager or secrets vault. Never put them in your code repository.

2. Check the connection

All other calls use port 8443 and your three files.

curl --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  https://api.knovas.ch:8443/secured/health

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.get(f"{BASE}/secured/health", **AUTH)
print(r.status_code, r.json())

3. Add a document

Uploading happens in two calls: first you start an upload and say how many parts you will send, then you send each part.

# Start the upload. Save the transmission_key_id from the answer.
curl -X POST https://api.knovas.ch:8443/secured/init_document_transmission \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"identifier": "handbook-2026", "title": "Employee Handbook 2026", "part_count": 1}'

# Send the text (part 0 of 1).
curl -X POST https://api.knovas.ch:8443/secured/transmit_document_part \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"key": "<transmission_key_id>", "part_number": 0,
       "snippet": "# Holidays\n\nEvery employee gets 25 days of paid holiday per year."}'

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,
)

# Start the upload
r = requests.post(f"{BASE}/secured/init_document_transmission", **AUTH, json={
    "identifier": "handbook-2026",
    "title": "Employee Handbook 2026",
    "part_count": 1,
})
r.raise_for_status()
key = r.json()["transmission_key_id"]

# Send the text (part 0 of 1)
r = requests.post(f"{BASE}/secured/transmit_document_part", **AUTH, json={
    "key": key,
    "part_number": 0,
    "snippet": "# Holidays\n\nEvery employee gets 25 days of paid holiday per year.",
})
r.raise_for_status()

4. Search

Wait a few seconds for Knovas to process the text, then ask a question:

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": "How many vacation days do I get?"}'

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": "How many vacation days do I get?"})
r.raise_for_status()
for hit in r.json()["results"]:
    print(hit["pointer"], round(hit["final_score"], 2))

The answer lists the matching documents, best first. pointer is the identifier you chose in step 3.

Next steps

Create your own private key before you go live (recommended).
Prepare your documents for the best search results.
Set up access control if different users should see different documents.

Questions? Write to contact@knovas.ch.

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