Retrieve Knowledge Base

Embed query and return the top-k matching chunks from the KB.

Auth: write:agents. Chunks are customer data, same threat model as /agents/{id}/logs.

Tenant scoping: a kb_id from another tenant returns 404 just like the read endpoint — no existence leak.

Rate limit: BUCKET_KB_RETRIEVAL at 30 req/min/tenant — same budget as the other outbound-call endpoints (MCP discovery, validate-llm, models-live).

Dual-surface model: this endpoint is one of three KB retrieval paths. The Java agent runtime queries Pinecone directly at deploy time via its own mirror (off the hot path through this BE); the streamkap-tools MCP server exposes streamkap_kb_retrieve and proxies through this endpoint for third-party agents.

curl -X POST 'https://api.streamkap.com/knowledge-bases/string/retrieve' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "string",
  "top_k": 5
}'

const response = await fetch("https://api.streamkap.com/knowledge-bases/string/retrieve", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"query\": \"string\",\n  \"top_k\": 5\n}"
});

import requests

response = requests.post(
    "https://api.streamkap.com/knowledge-bases/string/retrieve",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"query\": \"string\",\n  \"top_k\": 5\n}",
)

{
  "matches": [
    {
      "chunk_id": "string",
      "text": "string",
      "score": 0,
      "metadata": {}
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}