kvn8888/senso-search

Senso Search

Search your organization's Senso knowledge base to ground responses in verified content. The Senso CLI provides three search variants — pick the right one for the task.

Prerequisites

The senso CLI must be installed and authenticated:

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

Verify with senso whoami --output json --quiet.

Always Use These Flags

Every senso command must include --output json --quiet so output is machine-readable and free of banners.

Search Variants

1. Full Search (default) — AI answer + source chunks

Use this when the user asks a question and wants a direct answer grounded in their knowledge base.

senso search "<query>" --output json --quiet

Returns:

• answer — AI-generated answer synthesized from matching chunks
• results[] — array of source chunks, each with:
  • content_id — UUID of the source document
  • title — document title
  • chunk_text — the relevant excerpt
  • score — relevance score (0–1, higher is better)
  • version_id — specific version matched
  • chunk_index — position within the document

When to use: The user wants a ready-made answer. This is the default choice.

2. Context Search — chunks only, no AI answer

Use this when you need raw verified chunks to build your own response, or when feeding context into another LLM.

senso search context "<query>" --output json --quiet

Returns the same results[] array as full search, but without the answer field.

When to use: You want to assemble your own response from verified sources, or the user is building a RAG pipeline.

3. Content Search — document IDs and titles only

Use this to discover which documents are relevant before fetching their full content.

senso search content "<query>" --output json --quiet

Returns deduplicated content IDs and titles — no chunks, no answer.

When to use: The user wants to know which documents exist on a topic, or you need IDs to pass to other commands like senso content get <id>.

Options

All three variants accept the same options:

| Flag | Description | |------|-------------| | --max-results <n> | Number of results to return (1–20, default: 5) | | --content-ids <id1> <id2> ... | Restrict search to specific content item UUIDs | | --require-scoped-ids | Only return results from the specified --content-ids (without this flag, the API may fall back to all content) |

Scoping search to specific documents

If the user says "search only in document X" or you already know the relevant content IDs:

senso search "query" --content-ids abc-123 def-456 --require-scoped-ids --output json --quiet

How to Cite Results

When presenting search results to the user:

1. Lead with the answer (from full search) or your synthesized answer (from context search)
2. Cite sources by title and content ID — e.g., "According to Refund Policy (cnt_abc123)..."
3. If the user wants more detail on a source, fetch it with senso content get <content_id> --output json --quiet

Retrieving Full Content

After identifying relevant documents via search, you can fetch the full content:

senso content get <content_id> --output json --quiet

This returns the complete content item including all versions, metadata, and publish status.

Error Handling

| HTTP Status | Meaning | Action | |-------------|---------|--------| | 401 | Invalid or missing API key | Check SENSO_API_KEY is set correctly | | 402 | Insufficient credits | Tell the user their credit balance is low — check with senso credits --output json --quiet | | 403 | API key lacks search permission | The key may be scoped — ask the user to check key permissions |

Additional Search Command

There is also a full alias that behaves identically to the default search:

senso search full "<query>" --output json --quiet