---
title: "Retrieve Knowledge Base"
method: POST
path: "/knowledge-bases/{kb_id}/retrieve"
tags: ["Knowledge Bases"]
---

# Retrieve Knowledge Base

`POST /knowledge-bases/{kb_id}/retrieve`

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.

## Path parameters

- `kb_id` string, required

## Request body

- KbRetrieveRequest — Request body for ``POST /knowledge-bases/{kb_id}/retrieve``. ``query`` is the user's text; the BE embeds it against the KB's saved embedding connection and runs a similarity search against the saved vector-store connection. ``top_k`` caps the number of matches returned.
  - `query` string, required
  - `top_k` integer

## Response `200`

Successful Response

- KbRetrieveResponse — Response envelope for KB retrieval — ordered list of matches.
  - `matches` KbRetrieveMatch[], required
    - `chunk_id` string, required
    - `text` string, nullable
    - `score` number, required
    - `metadata` object, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/streamkap/apis/streamkap-rest-api.md) · [All operations](https://skmtc.net/streamkap/apis/streamkap-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/streamkap/streamkap-rest-api/versions/8aea6143d003/schema)