> ## Documentation Index > Fetch the complete documentation index at: https://docs.streamkap.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi/openapi.json post /knowledge-bases/{kb_id}/retrieve openapi: 3.1.0 info: title: Streamkap REST API description: >- The Streamkap REST API allows you to programmatically manage your CDC pipelines, sources, destinations, transforms, and more. Authenticate using a bearer token obtained from the [Access Token](/api-reference/auth/access-token) endpoint with your API client credentials. contact: name: Streamkap Support url: https://streamkap.com/ email: support@streamkap.com license: name: Proprietary version: 2.0.0 servers: - url: https://api.streamkap.com description: Production security: [] tags: - name: Agents description: Create, deploy, and manage Flink-based AI agents. - name: Agents Observability description: >- Read-only views over the MCP audit log: agent rollup, sessions, spans, histograms, external-agent verify. - name: Alerts description: Manage alert subscribers, preferences, and notification credentials. - name: Authentication description: Obtain and refresh access tokens, manage client credentials and roles. - name: Billing description: Retrieve usage metrics, summaries, and export billing data. - name: Consumer Groups description: List, inspect, and reset Kafka consumer group offsets. - name: Dashboard description: Retrieve organisation-level statistics and overview data. - name: Destinations description: Create, configure, and manage data destinations and their lifecycle. - name: Kafka Access description: Manage Kafka users and their access permissions. - name: Logs description: Query and summarise system logs. - name: Pipelines description: Create, configure, and manage CDC pipelines and their lifecycle. - name: Project Keys description: Manage project keys that bundle API credentials and optional Kafka access. - name: Schema Registry description: Browse schema subjects, versions, and retrieve schema definitions. - name: Services description: View and switch service metadata. - name: Sources description: >- Create, configure, and manage data sources, snapshots, and their lifecycle. - name: Tags description: Create, update, and manage resource tags for organisation. - name: Topics description: Browse topic details, statistics, configurations, metrics, and messages. - name: Transforms description: >- Create, deploy, and manage data transforms, unit tests, and implementation details. paths: /knowledge-bases/{kb_id}/retrieve: post: tags: - Knowledge Bases summary: Retrieve Knowledge Base description: |- 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. operationId: retrieveKnowledgeBase parameters: - name: kb_id in: path required: true schema: type: string title: Kb Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KbRetrieveRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/KbRetrieveResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - FronteggHTTPAuthentication: [] components: schemas: KbRetrieveRequest: properties: query: type: string maxLength: 4096 minLength: 1 title: Query top_k: type: integer maximum: 50 minimum: 1 title: Top K default: 5 additionalProperties: false type: object required: - query title: KbRetrieveRequest description: |- 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. KbRetrieveResponse: properties: matches: items: $ref: '#/components/schemas/KbRetrieveMatch' type: array title: Matches additionalProperties: false type: object required: - matches title: KbRetrieveResponse description: Response envelope for KB retrieval — ordered list of matches. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError KbRetrieveMatch: properties: chunk_id: type: string title: Chunk Id text: anyOf: - type: string - type: 'null' title: Text score: type: number title: Score metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata additionalProperties: false type: object required: - chunk_id - score title: KbRetrieveMatch description: |- One match in a KB retrieval response. ``chunk_id`` is the vector-store record's id. ``text`` is pulled from the chunk's metadata when the KB indexer stored it under the conventional ``"text"`` key — the full metadata dict is also surfaced so callers can render arbitrary extra fields. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: FronteggHTTPAuthentication: type: http scheme: bearer ````