Knowledge graph

Organise your documents by client, case or project, and search inside one of them.

Optional feature

The knowledge graph is switched on per customer. If it is off, these calls answer 404. Ask your Knovas contact to enable it.

The idea

You create a node for each thing you care about, for example “Client Meier” or “Project Alpha”, and file documents under it. A document can belong to several nodes. Nodes can be linked to each other (“Project Alpha belongs to Client Meier”).

Term	Meaning
Node	A thing you organise around: a person, case, client, project or topic.
Node type	A kind of node, such as Client or Mandate, with a list of the details every node of that kind should have.
Assignment	A document filed under a node.
Identifier	A name or description that tells Knovas what belongs to a node, e.g. “Michael Xample”.
Proposal	Knovas’ suggestion to file a new document under a node. You accept or reject it.
Fact	A single value stored on a node, such as an amount or a deadline, with links to where it comes from.

Node types

A node type describes one kind of node, for example Client, Mandate or Project. Each type has a list of attributes: the details a node of that kind should have, such as a deadline or an amount. Node types are optional. A node without a type works exactly the same, it just has no attribute list.

Create a type and its attributes

# 1. Create the node type
curl -X POST https://api.knovas.ch:8443/secured/graph/node-types \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"name": "Mandate", "description": "A legal case we handle for a client"}'

# 2. Add attributes to it (use the id from step 1)
curl -X POST https://api.knovas.ch:8443/secured/graph/node-types/<type id>/schema \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"name": "deadline", "datatype": "date", "required": true}'

curl -X POST https://api.knovas.ch:8443/secured/graph/node-types/<type id>/schema \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"name": "status", "datatype": "enum", "enum_values": ["open", "pending", "closed"]}'

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

# 1. Create the node type
r = requests.post(f"{BASE}/secured/graph/node-types", **AUTH, json={
    "name": "Mandate",
    "description": "A legal case we handle for a client",
})
r.raise_for_status()
# Answer: {"status": "success", "message": "Node type created", "node_type": {"id": "...", ...}}
type_id = r.json()["node_type"]["id"]

# 2. Add attributes to it
attributes = [
    {"name": "deadline", "datatype": "date", "required": True},
    {"name": "amount in dispute", "datatype": "money"},
    {"name": "status", "datatype": "enum", "enum_values": ["open", "pending", "closed"]},
]
for attribute in attributes:
    requests.post(f"{BASE}/secured/graph/node-types/{type_id}/schema", **AUTH,
                  json=attribute).raise_for_status()

Each attribute has a datatype that decides what its values look like:

Datatype	Use it for	Example value
`text`	Free text	`"Zurich commercial court"`
`date`	A date, as exact as you know it (`day`, `month` or `year`)	`{"value": "2026-03-01", "precision": "day"}`
`money`	An amount with its currency	`{"amount": 5000, "currency": "CHF"}`
`enum`	One value from a fixed list (`enum_values`, required for this type)	`"pending"`
`entity_ref`	A link to another node, such as the client a mandate belongs to	`{"node_id": "<node id>"}`

Mark an attribute "required": true if every node of that type should have it. Knovas never blocks a node because a required detail is missing. Instead, the completeness report shows what is still open (see below).

Give a node a type

Send node_type_id when you create a node, or change it later with PATCH /secured/graph/nodes/<node id>. To list all nodes of one type, use GET /secured/graph/nodes?node_type_id=<type id>.

See what is missing

The completeness report lists, for each node, which required attributes have no value yet.

# For one node
curl --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem https://api.knovas.ch:8443/secured/graph/nodes/<node id>/completeness

# For all nodes
curl --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem https://api.knovas.ch:8443/secured/graph/completeness

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/graph/nodes/{node_id}/completeness", **AUTH)
print(r.json())

Change or remove types and attributes

Rename a type with PATCH /secured/graph/node-types/<type id>, and change an attribute (name, description, required, allowed values) with PATCH /secured/graph/node-types/<type id>/schema/<attribute id>.
Removing an attribute (DELETE on the same address) retires it: it no longer appears in the list, but facts already recorded for it are kept. Add ?include_deprecated=true when listing to see retired attributes.
Deleting a type keeps its nodes; they simply have no type afterwards. A type can only be deleted when no facts use its attributes.

Create a node

curl -X POST https://api.knovas.ch:8443/secured/graph/nodes \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"name": "Mandate Meier", "description": "All documents for the Meier mandate", "node_type_id": "<type id>"}'

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/graph/nodes", **AUTH, json={
    "name": "Mandate Meier",
    "description": "All documents for the Meier mandate",
    "node_type_id": type_id,   # optional
})
r.raise_for_status()
# Answer: {"status": "success", "message": "Node created", "node": {"id": "...", ...}}
node_id = r.json()["node"]["id"]

The answer contains the new node and its id. node_type_id is optional.

File documents under a node

While uploading: add graph_assign when you start the upload. The document is filed as soon as it is processed.

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": "meier/2026/contract.pdf",
    "part_count": 4,
    "title": "Service contract Meier",
    "graph_assign": {"node_ids": ["<node id>"]}
  }'

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/init_document_transmission", **AUTH, json={
    "identifier": "meier/2026/contract.pdf",
    "part_count": 4,
    "title": "Service contract Meier",
    "graph_assign": {"node_ids": [node_id]},
})

Later: file an existing document by its identifier.

curl -X POST https://api.knovas.ch:8443/secured/graph/nodes/<node id>/knowledge \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"pointer": "meier/2026/contract.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.post(f"{BASE}/secured/graph/nodes/{node_id}/knowledge", **AUTH, json={
    "pointer": "meier/2026/contract.pdf",
})

Search inside a node

Add scope to a search to look only at the documents of one or more nodes. In an account with hundreds of cases, this is the most effective way to get precise results.

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 for termination", "scope": {"node_ids": ["<node id>"]}}'

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 for termination",
    "scope": {"node_ids": [node_id]},
})

A node only contains the documents filed under it. If a scoped search finds nothing, check that the document was actually filed.

Let Knovas sort new documents

Add identifiers to a node. These are the names and phrases that show a document belongs there:

curl -X POST https://api.knovas.ch:8443/secured/graph/nodes/<node id>/identifiers \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"identifier_text": "Michael Xample"}'

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/graph/nodes/{node_id}/identifiers", **AUTH, json={
    "identifier_text": "Michael Xample",
})

From then on, every new document is checked against your identifiers. Small spelling mistakes are still recognised. When a document matches, Knovas creates a proposal. Sorting never files a document on its own. You decide:

# What is waiting for review
curl --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem "https://api.knovas.ch:8443/secured/graph/proposals?status=proposed"

# File it
curl -X POST --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem https://api.knovas.ch:8443/secured/graph/proposals/<proposal id>/accept

# Never suggest it again
curl -X POST --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem https://api.knovas.ch:8443/secured/graph/proposals/<proposal id>/reject

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

# What is waiting for review
r = requests.get(f"{BASE}/secured/graph/proposals", **AUTH, params={"status": "proposed"})

for proposal in r.json()["proposals"]:
    print(proposal["pointer"], "->", proposal["node_id"])
    if input("File it? [y/n] ") == "y":
        requests.post(f"{BASE}/secured/graph/proposals/{proposal['id']}/accept", **AUTH)
    else:   # never suggest it again
        requests.post(f"{BASE}/secured/graph/proposals/{proposal['id']}/reject", **AUTH)

Accepted proposals teach Knovas: over time it also recognises documents about a person that do not spell the name exactly. The same identifiers also power automatic narrowing in search.

Facts and evidence

You can store single values on a node, such as an amount, a date or a status (usually for one of its type’s attributes), and link each one to the passages in your documents that support or contradict it. Knovas then shows how well-backed each fact is, from confirmed by a person to disputed when a source contradicts it. Contact us for the detailed guide to facts and automatic filters.

Access control in the graph

If you use access control, the graph follows the same rules: send access_groups in the request body (or as ?access_groups=Legal,HR on GET requests), and users only see nodes, facts and documents they are allowed to. You can also restrict a node itself with required_groups when you create it.

Questions? Write to contact@knovas.ch.

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