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.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

• Knowledge Base for Handles
• Context Store Connectors
• Apps and MCP Tools
• API Tokens and Automations
• API Auth and Error Model