Query a RAG collection using natural language to retrieve relevant document chunks.
Performs semantic search over the collection's indexed documents and returns the most
relevant chunks ranked by similarity. Optionally synthesizes an AI-generated answer
using the retrieved context.
Parameters:
- query: Natural language question or search phrase
- top_k: Number of chunks to retrieve (default 5, max 20)
- threshold: Minimum similarity score 0-1 (only return chunks above this score)
- synthesize: If true, uses an LLM to generate a natural language answer from the
retrieved chunks (default false — returns raw chunks only)
- model: LLM model to use for synthesis (only relevant when synthesize is true,
default: anthropic/claude-haiku-4.5)
- filter: Metadata filter to narrow results (e.g. { category: "faq" })
Example — raw retrieval:
Input: {
app_id: "app_abc123",
collection: "knowledge-base",
query: "How do I reset my password?",
top_k: 3
}
Output: {
chunks: [
{
text: "To reset your password, go to Settings > Security > Reset Password...",
score: 0.92,
document_id: "doc_abc",
metadata: { category: "faq", source: "help-center" }
},
...
]
}
Example — with synthesis:
Input: {
app_id: "app_abc123",
collection: "knowledge-base",
query: "How do I reset my password?",
top_k: 5,
synthesize: true
}
Output: {
answer: "To reset your password, navigate to Settings > Security and click...",
chunks: [ ... ],
model: "gpt-4o-mini"
}
Example — with metadata filter:
Input: {
app_id: "app_abc123",
collection: "knowledge-base",
query: "pricing plans",
filter: { category: "billing", version: "2.0" }
}
Use this to:
- Search documentation or knowledge bases using natural language
- Build AI-powered Q&A features for end users
- Find relevant context for AI assistants
- Power search bars with semantic understanding
Common errors:
- RESOURCE_NOT_FOUND: App or collection doesn't exist
- COLLECTION_EMPTY: No documents have been ingested yet
Idempotency: Safe to call anytime (read-only operation).