The Kenoscope API
One engine behind the website and the API. You send a question; you get the answer, the passage behind every claim, and a verdict for each claim.
Quick start
Create a workspace, add a library, upload documents, then create a key under API keys. Keys start with ks_ and are shown once.
export KENOSCOPE_KEY=ks_...
curl https://www.kenoscope.com/v1/ask \
-H "Authorization: Bearer $KENOSCOPE_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "How long is the probation period?"}'
The same call in Python, standard library only:
import json, os, urllib.request
req = urllib.request.Request(
"https://www.kenoscope.com/v1/ask",
data=json.dumps({"question": "How long is the probation period?"}).encode(),
headers={"Authorization": "Bearer " + os.environ["KENOSCOPE_KEY"],
"Content-Type": "application/json"})
answer = json.load(urllib.request.urlopen(req))
for claim in answer["claims"]:
print(claim["verdict"], "|", claim["text"])
Ask
POST /v1/ask
| Field | Type | Meaning |
|---|---|---|
question | string, required | Up to 1,500 characters. |
library | string | A library id or slug. Optional when the organisation has exactly one library. |
stream | boolean | true returns server-sent events instead of one JSON object. |
Response:
{
"question": "How long is the probation period?",
"status": "answered",
"answer": "The probation period is three months.",
"claims": [
{
"text": "The probation period is three months.",
"verdict": "supported",
"reason": "",
"citation": {
"n": 1, "passage_id": 4127, "document": "Onboarding", "section": "Probation",
"quote": "The probation period is three months.", "url": "",
"map_index": 12, "position": [14.2, -3.1, 40.8]
}
}
],
"counts": {"claims": 1, "supported": 1},
"evidence": [ ... the passages search found, best first ... ],
"timings_ms": {"search": 31, "first": 33, "total": 34},
"question_id": 9182
}
status | Meaning |
|---|---|
answered | At least one claim is supported. answer is the supported claims joined. |
no_evidence | The library holds nothing that answers this. claims is empty, message says so, and landing is where the question sits on the map. |
unsupported | Claims were written but none passed the checks. Nothing should be shown as an answer. |
blocked | The text was an instruction to the engine, not a question about the documents. |
Verdicts
A claim is supported only when every one of these holds. The checks are code, not a model.
- Cited. It names a passage that search returned for this question.
- Quoted. Its quote is in that passage word for word (case and formatting aside).
- Numbers. Every number in the claim is in the passage.
- Wording. At least 60% of the claim's content words are in the passage.
- Polarity. The claim and the quote have the same number of negations, so a dropped or added “not” fails.
Otherwise it is unsupported, and reason says which check failed. Unsupported claims are returned so you can show them marked, or drop them. Switch on strict mode in settings and the engine drops them for you.
These checks establish that a sentence rests on the cited words. They cannot tell whether the document itself is right or up to date.
Streaming
With "stream": true the response is text/event-stream. Events arrive in this order:
| Event | Data |
|---|---|
evidence | The passages found, with map positions. Sent before any writing starts. |
delta | {"i": 0, "text": "The "}: words of claim i as they are written. Not yet checked. |
claim | The finished claim i with its citation and verdict. Replace the deltas with this. |
done | Status, counts and timings. |
curl -N https://www.kenoscope.com/v1/ask \
-H "Authorization: Bearer $KENOSCOPE_KEY" -H "Content-Type: application/json" \
-d '{"question": "How long is the probation period?", "stream": true}'
Documents
GET /v1/libraries lists libraries. POST /v1/libraries/{id-or-slug}/documents uploads files (multipart field files, up to 50 per request, 20 MB each; Markdown, text, HTML, PDF, Word). Indexing runs in the background; the response names a job to poll.
curl https://www.kenoscope.com/v1/libraries/handbook/documents \
-H "Authorization: Bearer $KENOSCOPE_KEY" \
-F "files=@leave-policy.md" -F "files=@expenses.pdf"
# {"job": "6f0c...", "status_url": "/v1/jobs/6f0c..."}
curl https://www.kenoscope.com/v1/jobs/6f0c... -H "Authorization: Bearer $KENOSCOPE_KEY"
# {"id": "6f0c...", "status": "done", "detail": "{...}"}
Uploading a file with the same name replaces the earlier version. New documents are placed into the existing map next to their nearest neighbours in meaning; the map is laid out afresh only when a library has grown by more than a third.
Gaps
GET /v1/libraries/{id-or-slug}/gaps returns what the library does not know: clusters of questions that found no evidence, with a label, a count and a map position, plus the 50 most recent unanswered questions.
Usage and limits
GET /v1/usage returns the plan, its limits and what has been used this month. Each key may make 120 requests a minute. Questions count against the plan's monthly allowance whether they come from the website or the API.
Errors
Errors are JSON: {"error": {"code": "...", "message": "..."}}.
| Status | Code | When |
|---|---|---|
| 401 | unauthorized | Missing, wrong or revoked key. |
| 402 | plan_limit | The plan's monthly questions or stored passages are used up. |
| 404 | not_found | No such library or job in this organisation. |
| 422 | library_required, invalid_file | The request needs fixing; the message says how. |
| 429 | rate_limited | More than 120 requests in a minute on one key. |
The public demo
The map on the homepage runs on a sample library: the GitLab Handbook, 53,392 passages from 3,362 pages. Anyone can ask it without an account, up to a daily number of questions per visitor. Questions asked there are stored, without the visitor's address, so that gaps can be charted; visitors' wording is never shown on the public map.
A machine-readable description of the API is at /v1/openapi.json.