Retrieve Knowledge Base

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

Requires write:agents, because chunks contain your data (the same gate as /agents/{id}/logs).

A kb_id from another tenant returns 404, like the read endpoint, so the response never reveals whether it exists.

Rate limit: 30 req/min per tenant -> 429.

The Streamkap MCP server’s streamkap_kb_retrieve tool calls this endpoint, so external agents get the same results. Deployed Streamkap agents query the knowledge base’s vector store directly rather than through this endpoint.

POST/knowledge-bases/{kb_id}/retrieve

Authorization

AuthorizationBearer token · headerrequired

Path parameters

kb_idstringrequired

Request body

requiredapplication/json

querystringrequired

min length 1 · max length 4096

top_kinteger

min 1 · max 50 · default: 5

Responses

200

Successful Response

matchesKbRetrieveMatch[]required

Show properties

Array of KbRetrieveMatch

chunk_idstringrequired

textstring | null

Show properties

Any of:

string

string

null

null

scorenumberrequired

metadataobject | null

Show properties

Any of:

object

object

null

null

422

Validation Error

detailValidationError[]

Show properties

Array of ValidationError

locstring | integer[]required

Show properties

Array of string | integer

Any of:

string

string

integer

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Request

curl -X POST 'https://api.streamkap.com/knowledge-bases/string/retrieve' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -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",
    "Accept": "application/json",
    "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",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"query\": \"string\",\n  \"top_k\": 5\n}",
)

Response

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

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