links.arjun.tv/docs/end-user/knowledge-base-usage-guide

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.

UI workflow

1. Create knowledge document

  1. Open https://app.{PUBLIC_DOMAIN}.
  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://api.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",
    "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
  }'

Expected outcome: 200 with ranked results[] and retrieval metadata.

MCP query (OAuth connector)

  1. Register connector URL https://{handle}.mcp.10x.in/mcp (or https://api.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?"

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

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