Feedback

Optional, but valuable: telling Knovas what your users did with results lets us measure and improve search quality for your documents.

Three kinds of feedback

What	When to send it	Endpoint
What users did	A user opened, clicked, downloaded or dismissed a result	`/secured/analytics/engagement`
How relevant a result was	A user rated a result for a search (1–5)	`/secured/analytics/relevance-feedback`
How important a document is	You want to mark a document as important or reliable, for good	`/secured/document/rating`

Fire and forget

Feedback never affects search, so do not make your users wait for it and do not retry on errors. If a feedback call fails, nothing else breaks.

Report what users did

Use the query_session_id from the search, and send up to 50 events at once. Allowed actions: view, click, download, dismiss. position is where the result appeared on screen (1 = top).

curl -X POST https://api.knovas.ch:8443/secured/analytics/engagement \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{
    "query_session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "events": [{"action": "view", "pointer": "reports/2025/q3.pdf", "position": 1}]
  }'

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

requests.post(f"{BASE}/secured/analytics/engagement", **AUTH, json={
    "query_session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",   # from the search answer
    "events": [{"action": "view", "pointer": "reports/2025/q3.pdf", "position": 1}],
})

Rate a result

Score from 1 (not relevant) to 5 (very relevant). Every rating is kept; nothing is overwritten.

curl -X POST https://api.knovas.ch:8443/secured/analytics/relevance-feedback \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"pointer": "reports/2025/q3.pdf", "relevance_score": 4,
       "query_session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}'

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

requests.post(f"{BASE}/secured/analytics/relevance-feedback", **AUTH, json={
    "pointer": "reports/2025/q3.pdf",
    "relevance_score": 4,
    "query_session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
})

Rate a document

Give a document a lasting importance and/or quality score from 1 to 5. Sending it again updates the score.

curl -X POST https://api.knovas.ch:8443/secured/document/rating \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"pointer": "reports/2025/q3.pdf", "importance_score": 5, "quality_score": 3}'

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

requests.post(f"{BASE}/secured/document/rating", **AUTH, json={
    "pointer": "reports/2025/q3.pdf",
    "importance_score": 5,
    "quality_score": 3,
})

To read a document’s scores and an overview of all its relevance ratings:

curl --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  "https://api.knovas.ch:8443/secured/document/rating?pointer=reports%2F2025%2Fq3.pdf"

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/document/rating", **AUTH, params={"pointer": "reports/2025/q3.pdf"})
print(r.json()["rating"], r.json()["relevance_feedback"])

Privacy

Feedback contains no personal data about your users and no search text. It is linked only to your account and stays in your private space.

Questions? Write to contact@knovas.ch.

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