Knowledge Base RAG API

Query knowledge bases directly from your agent code to retrieve relevant documents and generate responses with citations.

Overview

The Knowledge Base RAG API provides two functions for interacting with knowledge bases:

• retrieveFromKnowledgeBase: Retrieve relevant documents based on a query

• retrieveAndGenerateFromKnowledgeBase: Retrieve documents and generate a response with citations

Both functions support metadata filtering, result count control, and automatic agent/environment isolation.

Default Knowledge Base Selection

The knowledgeBaseId parameter is optional. If omitted, the backend will:

• Exactly 1 KB for the agent → automatically use it

• 0 KBs → throw an error prompting you to create a knowledge base

• >1 KBs → throw an error requiring you to pass knowledgeBaseId explicitly to disambiguate

This simplifies usage for agents with a single knowledge base.

Before you start: Create a knowledge base and upload documents in the platform dashboard. For agents with multiple knowledge bases, copy the knowledgeBaseId to pass explicitly. See Knowledge Bases.

retrieveFromKnowledgeBase

Retrieve relevant documents from a knowledge base.

Function Signature

retrieveFromKnowledgeBase(
  params: {
    knowledgeBaseId?: string;
    environment: string;
    query: string;
    numberOfResults?: number;
    filters?: KnowledgeBaseFilter;
  },
  timeoutMs?: number
): Promise<{
  retrievalResults: KnowledgeBaseRetrievalResult[];
  nextToken?: string;
}>

Parameters

Parameter	Type	Required	Description
params.knowledgeBaseId	string		ID of the knowledge base to query. If omitted, backend auto-selects the KB if exactly one exists; errors if 0 or >1 KBs exist.
params.environment	string	✓	Environment (e.g., 'development', 'production')
params.query	string	✓	Search query string
params.numberOfResults	number		Number of results to return (default: 5)
params.filters	KnowledgeBaseFilter		Metadata filters for the query
timeoutMs	number		Query timeout (default: 30000ms)

Return Value

Returns a Promise with:

• retrievalResults: Array of retrieval results, each containing:

  • content.text: Text content of the document chunk

  • location.s3Location.uri: URI of the source document

  • metadata: Associated metadata as key-value pairs

  • score: Relevance score (0-1)

• nextToken: Optional token for pagination

Examples

With explicit knowledgeBaseId:

import { retrieveFromKnowledgeBase } from '@minded-ai/mindedjs';

const results = await retrieveFromKnowledgeBase({
  knowledgeBaseId: 'kb-abc123',
  environment: 'production',
  query: 'How do I reset my password?',
  numberOfResults: 10,
  filters: {
    equals: { key: 'category', value: 'support' },
  },
});

for (const result of results.retrievalResults) {
  console.log(`Score: ${result.score}`);
  console.log(`Content: ${result.content.text}`);
  console.log(`Source: ${result.location.s3Location.uri}`);
}

retrieveAndGenerateFromKnowledgeBase

Retrieve documents and generate a response using an LLM, with citations referencing source documents.

Function Signature

retrieveAndGenerateFromKnowledgeBase(
  params: {
    knowledgeBaseId?: string;
    environment: string;
    query: string;
    modelArn?: string;
    numberOfResults?: number;
    filters?: KnowledgeBaseFilter;
  },
  timeoutMs?: number
): Promise<{
  output: string | null;
  citations: KnowledgeBaseCitation[];
  sessionId?: string;
}>

Parameters

Parameter	Type	Required	Description
params.knowledgeBaseId	string		ID of the knowledge base to query. If omitted, backend auto-selects the KB if exactly one exists; errors if 0 or >1 KBs exist.
params.environment	string	✓	Environment (e.g., 'development', 'production')
params.query	string	✓	Search query string
params.modelArn	string		Model ARN for generation (uses default if not specified)
params.numberOfResults	number		Number of documents to retrieve (default: 5)
params.filters	KnowledgeBaseFilter		Metadata filters for the query
timeoutMs	number		Query timeout (default: 60000ms)

Return Value

Returns a Promise with:

• output: Generated text response (null if no relevant documents found)

• citations: Array of citations, each containing:

  • generatedResponsePart.textResponsePart.text: The part of the response that cites this source

  • generatedResponsePart.textResponsePart.span: Start/end positions in the response

  • retrievedReferences: Array of source documents referenced

• sessionId: Optional session ID for conversation continuity

Examples

With explicit knowledgeBaseId:

import { retrieveAndGenerateFromKnowledgeBase } from '@minded-ai/mindedjs';

const result = await retrieveAndGenerateFromKnowledgeBase({
  knowledgeBaseId: 'kb-abc123',
  environment: 'production',
  query: 'Summarize the refund policy',
  numberOfResults: 5,
});

if (result.output) {
  console.log('Response:', result.output);

  // Process citations
  for (const citation of result.citations) {
    console.log('Cited text:', citation.generatedResponsePart.textResponsePart.text);

    for (const ref of citation.retrievedReferences) {
      console.log('  Source:', ref.location.s3Location.uri);
      console.log('  Content:', ref.content.text.substring(0, 100) + '...');
    }
  }
} else {
  console.log('No relevant documents found');
}

Filtering

Both functions support metadata filters for precise document retrieval.

Filter Types

interface KnowledgeBaseFilter {
  equals?: { key: string; value: string };
  notEquals?: { key: string; value: string };
  greaterThan?: { key: string; value: string };
  lessThan?: { key: string; value: string };
  andAll?: KnowledgeBaseFilter[];
  orAll?: KnowledgeBaseFilter[];
}

Filter Examples

import { retrieveFromKnowledgeBase } from '@minded-ai/mindedjs';

// With filters and explicit knowledgeBaseId
const results = await retrieveFromKnowledgeBase({
  knowledgeBaseId: 'kb-abc123',
  environment: 'production',
  query: 'pricing information',
  filters: {
    andAll: [{ equals: { key: 'department', value: 'sales' } }, { equals: { key: 'documentType', value: 'pricing' } }],
  },
});

// With filters, auto-selecting KB (if agent has exactly 1 KB)
const results2 = await retrieveFromKnowledgeBase({
  environment: 'production',
  query: 'pricing information',
  filters: {
    equals: { key: 'department', value: 'sales' },
  },
});