Search API — Query the Ragen AI Knowledge Base Directly

The Search endpoint returns the RAG context block — the ranked document chunks and source file IDs that Ragen would feed to the language model — without invoking the language model at all. Use it when you want to build your own generation pipeline, plug retrieved passages into a different model, or inspect what Ragen is actually finding before troubleshooting answer quality.

Run a search query before investigating a bad answer. If the right documents appear in context, the problem is in generation. If they don’t, the problem is in your knowledge base — the document may not be uploaded, still processing, or not yet indexed.

Endpoint

POST /v1/search

Authentication:

Authorization: Bearer YOUR_API_KEY

Request parameters

The API key decides which assistant, and this field has to agree with it. A key created for one assistant answers for that one whether or not you send assistant_id; a key scoped to the knowledge base answers from the documents that belong to no assistant, and rejects a request naming any assistant with 403. Omitting the field is the normal case. See Authentication.

string

The assistant (project) ID to search against. Optional — the API key already carries a scope, and this field must agree with it. A knowledge-base key searches the documents that belong to no assistant. Use GET /v1/assistants to find available IDs, or check Organization → Assistant settings in the dashboard.

string

required

The search query. Between 1 and 2,000 characters. Write it as a natural language question or phrase — the same way you’d phrase it to the chat endpoint.

integer

Maximum number of document chunks to return. Between 1 and 20. Defaults to the organization’s configured retrieval count.

Response

{
  "context": "**Refund Policy**\n\nCustomers may return items within 30 days of purchase...\n\n**Shipping FAQ**\n\nStandard shipping takes 3–5 business days...",
  "file_ids": ["file-abc123", "file-def456"]
}

string

The context block containing the most relevant document chunks concatenated together. This is exactly what Ragen’s chat endpoints pass to the language model as retrieved context.

string[]

The IDs of the source files that contributed chunks to the context block. Use these with GET /v1/files/{id} to trace results back to specific documents.

Use cases

Build your own generation

Feed the context string into your own prompt template and language model call, giving you full control over how the answer is generated.

Inspect retrieval quality

Check which document chunks Ragen retrieves for a given query before investigating answer quality — isolates retrieval bugs from generation bugs.

Downstream processing

Extract relevant passages for summarization, translation, classification, or any other pipeline that needs grounded content without a chat-style response.

MCP integration

The ragen_search_knowledge_base MCP tool calls this endpoint, letting external AI assistants ground themselves in your Ragen knowledge base without going through Ragen’s chat model.

Examples

TypeScript SDK
curl

import { Ragen } from '@webamigos/ragen-sdk-ts';

const ragen = new Ragen({ apiKey: process.env.RAGEN_API_KEY });

const result = await ragen.search({
  assistant_id: 'YOUR_ASSISTANT_ID',
  query: 'What is our refund policy?',
  max_results: 5,
});

console.log('Context:', result.context);
console.log('Source files:', result.file_ids);

// Use the context in your own prompt
const myPrompt = `Answer the question using only the context below.\n\nContext:\n${result.context}\n\nQuestion: What is our refund policy?`;

curl -X POST $RAGEN_BASE_URL/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "YOUR_ASSISTANT_ID",
    "query": "What is our refund policy?",
    "max_results": 5
  }'

Error codes

Status	Meaning
`400 Bad Request`	Missing required field, query too long, or `max_results` out of range
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	The key is deactivated, or the request disagrees with the key’s scope — an `assistant_id` the key is not bound to, or any `assistant_id` at all on a knowledge-base key
`404 Not Found`	The specified assistant doesn’t exist in your organization
`429 Too Many Requests`	Rate limit exceeded — wait before retrying

Example error body:

{
  "message": "Assistant not found"
}

Rate limits

Scope	Limit
`POST /v1/search`	20 requests / minute per IP

Getting Started

Endpoints

SDKs & Tools

Search API — Query the Ragen AI Knowledge Base Directly

Endpoint

Request parameters

Response

Use cases

Build your own generation

Inspect retrieval quality

Downstream processing

MCP integration

Examples

Error codes

Rate limits

​Endpoint

​Request parameters

​Response

​Use cases

Build your own generation

Inspect retrieval quality

Downstream processing

MCP integration

​Examples

​Error codes

​Rate limits

Endpoint

Request parameters

Response

Use cases

Examples

Error codes

Rate limits