links.10x.in/docs/end-user/knowledge-base-usage-guide Published:

Knowledge Base Usage Guide

Use this guide for end-to-end setup and operation of handle knowledge retrieval workflows.

Prerequisites

  • A valid handle with creator/operator access.
  • JWT token for handle management endpoints.
  • OAuth connector grant for MCP query workflows.
  • Knowledge content prepared in plain text or markdown-compatible format.

Note

This guide covers manual knowledge documents. For managed connector replicas such as crawled pages, repository docs, or exported upstream records, use Context Store Connectors. Context Store records are searchable through knowledge retrieval, but their lifecycle is source/entity sync status rather than manual document editing.

UI workflow

1. Create knowledge document

  1. Open https://app.10x.in.
  2. Navigate to your handle.
  3. Open the knowledge section in apps/workspace.
  4. Create a document with title, topic, and content.
  5. Confirm indexing status transitions to active/indexed.

2. Rebuild index

  1. Open the same handle knowledge area.
  2. Trigger rebuild.
  3. Confirm queue/processing indication completes.

3. Validate query results

  1. Run a query for a known phrase from your document.
  2. Check that relevant chunks are returned.
  3. Verify retrievalMode, backend, and tookMs fields in the result view (if exposed).

API workflow examples

Set variables:

export API_BASE="https://ai.10x.in"
export HANDLE="acme"
export JWT_TOKEN="<jwt-token>"

Create document

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/knowledge/documents" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "title": "Support handbook",
    "topic": "support",
    "source": "manual",
    "contentType": "text/plain",
    "tags": ["approved"],
    "metadata": { "customerTier": "enterprise" },
    "content": "Escalate account lockouts after two failed recovery attempts."
  }'

Expected outcome: 201 with documentId and indexing status.

List documents

curl -sS "${API_BASE}/v2/handles/${HANDLE}/knowledge/documents" \
  -H "authorization: Bearer ${JWT_TOKEN}"

Expected outcome: 200 with current document list and statuses.

Rebuild index

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/knowledge/rebuild" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'

Expected outcome: 202 with queued count.

Handle query (JWT)

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/knowledge/query" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "query": "How should support handle account lockouts?",
    "topic": "support",
    "limit": 5,
    "filters": {
      "AND": [
        { "key": "tags", "filterType": "array_contains", "value": "approved" },
        { "key": "metadata.customerTier", "value": "enterprise" }
      ]
    }
  }'

Expected outcome: 200 with ranked results[] and retrieval metadata. filters is optional; use it to narrow results by document fields, tags, or flat metadata.* keys.

MCP query (OAuth connector)

  1. Register connector URL https://{handle}.mcp.10x.in/mcp (or https://ai.10x.in/mcp/{handle}/mcp as compatibility fallback).
  2. Complete OAuth for the handle with mcp.connect, skills.read, and knowledge.query.
  3. Use your assistant prompt to run knowledge_query:
  • "Query handle knowledge for support topic: What is the escalation rule for lockouts?"
  • "Query approved enterprise support knowledge only."

Expected outcome: successful MCP tool response with ranked results[] and retrieval metadata.

Context Store query (MCP)

Use context_store_search when the source/entity status is READY or PREVIEW and the agent needs replicated connector context. Use a direct function binding instead when the task writes to the provider or requires real-time freshness.

Required scopes:

  • mcp.connect
  • context_store.search

Example prompts:

  • "Check context_store_status, then search project proj_launch for repository deployment notes."
  • "Search Context Store records for the documents entity in source repo_docs."

Response interpretation

Common response fields:

  • results[]: matched chunks (document, chunk, score, content, topic/title fields when available)
  • count: number of returned results
  • retrievalMode: vector, vector_dedicated, hybrid_fallback, or lexical_fallback
  • backend: retrieval backend label
  • tookMs: retrieval latency measurement
  • usage: usage envelope (for query limits/observability)

Interpretation guidance:

  • vector / vector_dedicated: semantic path succeeded.
  • hybrid_fallback: vector path executed, lexical fallback supplied final chunks.
  • lexical_fallback: semantic path unavailable; lexical-only path returned.

Practical troubleshooting

Empty results

  • Check document content quality and topic alignment.
  • Confirm document indexing status is complete.
  • Retry query with broader terms and no topic filter.

Frequent fallback behavior

  • If retrievalMode often reports fallback, inspect vector service health and queue lag.
  • Validate ingestion completed for recent documents.

Auth/scope errors

  • 401: refresh JWT token or re-run connector OAuth grant.
  • 403: verify handle role (creator/operator) and connector scope permissions for MCP.

Rebuild appears complete but results stale

  • Re-run list/query and confirm timestamps/status.
  • Check for delayed async processing in ingestion pipelines.

Related docs