Oshara Docs

Query the knowledge base


GET /api/knowledge-base/query/

Runs a semantic (vector) similarity search across all processed document chunks for the character and returns the top-k most relevant passages.

This endpoint is used by the agent worker automatically when a kb tool is invoked. You can also call it directly from your own backend — for example, to surface document content in a support portal or to build a RAG pipeline outside of a voice session.

Auth: X-API-Key header (the KB_QUERY_API_KEY configured on your backend).

Request


curl "https://api.oshara.ai/api/knowledge-base/query/?q=What+is+your+refund+policy&top_k=5" \
  -H "X-API-Key: your-kb-api-key"

Query parameters

Parameter	Type	Default	Description
`q`	string	—	Required. The search query — a question or topic in natural language.
`top_k`	integer	`5`	Number of passages to return (1–20).

Response


[
  {
    "text": "Our refund policy allows returns within 30 days of purchase for all physical products. To initiate a return, contact support@acme.com with your order number.",
    "metadata": {
      "source": "refund-policy.pdf",
      "page": 2
    }
  },
  {
    "text": "Digital products and software licenses are non-refundable once the license key has been revealed or the download has been initiated.",
    "metadata": {
      "source": "refund-policy.pdf",
      "page": 2
    }
  },
  {
    "text": "Shipping costs are non-refundable unless the return is due to our error.",
    "metadata": {
      "source": "shipping-faq.pdf",
      "page": 1
    }
  }
]

Response fields

Field	Description
`text`	The passage text, ready to feed into an LLM.
`metadata.source`	Filename of the source document.
`metadata.page`	Page number within the document (PDF only).

Results are ordered by cosine similarity score, highest first. There is no score field in the response — re-rank results yourself if needed.

POST variant

A JSON POST is also accepted (used by the agent worker):


curl -X POST https://api.oshara.ai/api/knowledge-base/query/ \
  -H "X-API-Key: your-kb-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query_text": "What is your refund policy?", "top_k": 5}'

Body field	Description
`query_text`	The search query.
`top_k`	Number of results (default 5).

Errors

Status	Meaning
`401 Unauthorized`	Missing or invalid `X-API-Key`.
`404 Not Found`	Character slug not found.
`200 []`	No processed documents exist, or no results above threshold.

Usage in your own pipeline


const results = await fetch(
  "https://api.oshara.ai/api/knowledge-base/query/?q=" +
  encodeURIComponent(userQuestion) + "&top_k=5",
  { headers: { "X-API-Key": process.env.KB_API_KEY } }
).then(r => r.json());
 
const context = results.map(r => r.text).join("\n\n");
// Feed context into your own LLM prompt