Knowledge Base

Policies, FAQs, manuals, filings, transcripts, approved reference documents. Anything a grounded answer should be able to point at.

Markdown and plain text go in as text. Files — PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, HTML, CSV, JSON, XML — go through the uploader, which returns a presigned URL you PUT the bytes to.

# Markdown or plain text goes straight in
curl -X POST https://apiv2.senso.ai/api/v1/org/kb/raw \
  -H "X-API-Key: $SENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refunds and Returns v4",
    "text": "# Refunds\n\nUnopened items within 30 days...",
    "kb_folder_node_id": "<folder-id>"
  }'

# Files go through the uploader
curl -X POST https://apiv2.senso.ai/api/v1/org/kb/upload \
  -H "X-API-Key: $SENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files": [{"filename": "handbook.pdf", "file_size_bytes": 91234, "content_type": "application/pdf", "content_hash_md5": "…"}]}'

• •Ingesting identical text twice does not create a second copy.
• •A document is not searchable until compilation finishes. Poll roughly every 15 seconds until processing_status reads complete.
• •Omitting the folder id puts it at the root.

A node id is a position in the tree — a document or a folder. Everything that organizes the tree speaks node ids: list, move, rename, tag, delete.

A content id comes back on search results and identifies compiled content you can cite. Passing one where the other is expected is the most common integration mistake.

Every update cuts a new version rather than overwriting history, and any earlier revision reads back by number. This is what keeps an attribution meaningful over time: an answer points at the version that was live when it was given.

# Current version
curl https://apiv2.senso.ai/api/v1/org/kb/nodes/{id}/content \
  -H "X-API-Key: $SENSO_API_KEY"

# An earlier one
curl "https://apiv2.senso.ai/api/v1/org/kb/nodes/{id}/content?version=2" \
  -H "X-API-Key: $SENSO_API_KEY"

Permissions are enforced per folder, so a key can be given one folder and be blind to everything else. Useful for an integration that should see Public Docs but not Internal Policies. Scope is granted on the API Keys page under KB Access — changing it needs a signed-in session, so a key cannot rescope itself.

# Scope the key on the API Keys page, then read back what it can see
curl https://apiv2.senso.ai/api/v1/org/api-keys/{key_id}/kb-permissions \
  -H "X-API-Key: $SENSO_API_KEY"

A node that does not exist and a node you cannot see return the same message, so nobody can probe for what exists. Full model in Permissions.

Both are queued rather than immediate, and a move is what changes who can reach a document — access comes from the folder a node sits in, not from the node. So after moving a document into a folder, the people who can read that folder cannot query it yet, and a deleted document can still turn up in an answer. Poll GET /org/kb/sync-status until syncing is false to know it has settled.

• •400 — validation error on the request body
• •401 — missing or invalid API key
• •403 — the key has no grant covering that node
• •404 — node missing, or no permission for it. Deliberately indistinguishable.
• •409 — a document with identical text already exists