RAG Query

Role-scoped semantic retrieval over workspace knowledge. The query is embedded, matched against the workspace's vector index, deduplicated, and enriched with source metadata. When RBAC is enabled, results only include knowledge assigned to the calling token's role.

POST /v1/workspaces/{workspaceId}/agent/rag

This is the retrieval primitive for custom agents — the Server SDK's context.api.rag() and the semantic_search tool both call it.

Request Body

FieldTypeRequiredDescription
textstringYesThe query to search for
languageIdstringNoRestrict results to a knowledge language (e.g. en, es)
topKnumberNoNumber of matches to return. Min 1, max 10, default 5

Example Request

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/rag' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "What is the refund policy?",
    "topK": 5,
    "languageId": "en"
  }'

Response (200 OK)

An array of matches, highest score first:

[
  {
    "id": "chunk-id-1",
    "score": 0.89,
    "metadata": {
      "text": "Refunds are processed within 5 business days of approval...",
      "source": "12:Refund Policy:knowledge-uuid",
      "workspaceId": "workspace-uuid",
      "knowledgeId": "knowledge-uuid",
      "language": "en",
      "pdf.info.Title": "Refund Policy",
      "loc.pageNumber": 12,
      "blobType": "text/json"
    },
    "values": []
  }
]
FieldTypeDescription
idstringChunk identifier in the vector index
scorenumberSimilarity score (0–1, higher is more relevant)
metadata.textstringThe matched passage
metadata.sourcestringSource descriptor (may include page number, title, and knowledge ID)
metadata.knowledgeIdUUIDThe knowledge item this chunk belongs to — use it for citations and Get Knowledge lookups
metadata.languagestringLanguage of the passage
valuesarrayAlways empty (embedding vectors are not returned)

Additional metadata fields (e.g. pdf.info.Title, loc.pageNumber) appear depending on the source document type. Source visibility respects knowledge permissions — items whose source is hidden won't expose source details.

Errors

  • 400 - Missing or invalid text, or workspace not found
  • 401 - RBAC is enabled but the token carries no role

Usage Notes

  • Build citations from metadata.knowledgeId and surface them via the sources field when storing the assistant message
  • Results are pre-filtered by role — you do not need to (and cannot) re-check RBAC client-side
  • For keyword/title lookup instead of semantic matching, use Knowledge Search

Related