Senso KB Organize

Browse and manage the Senso knowledge base folder tree. The KB is structured like a file system — folders organize content, and documents (uploaded files or raw text) hold knowledge.

Prerequisites

npm install -g @senso-ai/cli
export SENSO_API_KEY=<your-key>

Always Use These Flags

Every senso command must include --output json --quiet.

Key Concepts

• Both folders and documents are called nodes
• Every node has a kb_node_id, a type (folder or content), and a parent_id
• The root folder has parent_id: null
• Deleting is a soft delete — items are marked as deleted, not permanently removed
• After structural changes (move, delete), the vector index needs to sync — always check sync-status

Browsing the KB

Get the Root Node

senso kb root --output json --quiet

Returns the root folder node with its kb_node_id. Use this ID to list top-level children.

List Top-Level Files and Folders

senso kb my-files --output json --quiet

# With pagination
senso kb my-files --limit 50 --offset 0 --output json --quiet

List Children of a Folder

senso kb children <folder_kb_node_id> --output json --quiet

# With pagination
senso kb children <id> --limit 50 --offset 0 --output json --quiet

Get a Specific Node

senso kb get <kb_node_id> --output json --quiet

Returns the full node detail including type, name, parent, and metadata.

Search Nodes by Name

senso kb find --query "policy" --output json --quiet

# With pagination
senso kb find --query "policy" --limit 20 --offset 0 --output json --quiet

Get Breadcrumb Path (Ancestors)

senso kb ancestors <kb_node_id> --output json --quiet

Returns the ancestor chain from root to the node — useful for showing the user where something lives in the tree.

Content Details

Get Content Detail for a Document Node

senso kb get-content <kb_node_id> --output json --quiet

# Get a specific version
senso kb get-content <kb_node_id> --version <version_number> --output json --quiet

Get a Download URL

senso kb download-url <kb_node_id> --output json --quiet

# For a specific version
senso kb download-url <kb_node_id> --version <version_number> --output json --quiet

Returns a time-limited presigned S3 URL for downloading the original file.

Creating Folders

# Create at root level
senso kb create-folder --name "HR Documents" --output json --quiet

# Create inside an existing folder
senso kb create-folder --name "Policies" --parent-id <parent_kb_node_id> --output json --quiet

Renaming Nodes

Rename any node (folder or document):

senso kb rename <kb_node_id> --name "New Name" --output json --quiet

Moving Nodes

Move a node to a different parent folder:

senso kb move <kb_node_id> --parent-id <new_parent_kb_node_id> --output json --quiet

After moving: Check sync status — the vector index needs to update.

Deleting Nodes

senso kb delete <kb_node_id> --output json --quiet

This is a soft delete. Deleting a folder deletes all its contents recursively.

After deleting: Check sync status.

Checking Sync Status

After any structural change (move, delete, upload), check that the vector index is up to date:

senso kb sync-status --output json --quiet

Search results may be stale until sync completes. Wait for sync before relying on search for recently moved or deleted content.

Creating Raw Text Content

Create a document directly from text or markdown:

senso kb create-raw --data '{
  "title": "Company Vacation Policy",
  "text": "# Vacation Policy\n\nAll employees receive 20 days of paid vacation per year...",
  "kb_folder_node_id": "<parent-folder-uuid>"
}' --output json --quiet

The kb_folder_node_id is optional — omit to create at root level.

Updating Raw Text Content

Full replacement (creates a new version):

senso kb update-raw <kb_node_id> --data '{
  "title": "Updated Policy Title",
  "text": "# Updated Content\n\nNew text here..."
}' --output json --quiet

Partial update (only changes specified fields):

senso kb patch-raw <kb_node_id> --data '{
  "title": "Just Update the Title"
}' --output json --quiet

Uploading Files into a Folder

senso kb upload report.pdf slides.pptx --folder-id <kb_node_id> --output json --quiet

Maximum 10 files per call. Without --folder-id, files go to the root.

Replacing a File on an Existing Node

senso kb update-file <kb_node_id> updated-report.pdf --output json --quiet

This replaces the file and triggers background re-processing.

Typical Organization Workflow

When the user asks to "organize the KB":

1. Survey: List top-level items with senso kb my-files to understand current state
2. Plan: Discuss folder structure with the user
3. Create folders: Build the structure with senso kb create-folder
4. Move items: Relocate documents with senso kb move
5. Rename: Clean up names with senso kb rename
6. Verify sync: Check senso kb sync-status after all changes
7. Confirm: List the final structure by walking the tree

Listing Content Items

To list content with more detail (processing status, publish status):

senso content list --output json --quiet

# With pagination
senso content list --limit 20 --offset 0 --output json --quiet

Error Handling

HTTP Status	Meaning	Action
401	Invalid or missing API key	Check SENSO_API_KEY
404	Node not found	Verify the kb_node_id with senso kb find or senso kb my-files
409	Conflict — operation in progress	Another operation is running on this node. Wait and retry.
422	Unprocessable	Check that the target parent is a folder (type: folder), not a content node