Chat API — Single-Turn RAG Question and Answer Endpoint

The Chat endpoint is the simplest way to query your Ragen knowledge base. Send a single message, get a single answer — Ragen handles retrieval and generation behind the scenes. If you need multi-turn conversation, model selection, or token usage tracking, use Chat Completions instead.

Endpoint

POST /v1/chat

Authentication — include your API key in every request:

Authorization: Bearer YOUR_API_KEY

API keys are scoped to your organization. Create and manage keys in the Ragen dashboard under Organization → API keys.

Prefer POST /v1/chat/completions for new integrations. It supports multi-turn conversations, model override, temperature, and usage tracking via the standard OpenAI wire format.

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 query. Optional — the API key already carries a scope, and this field must agree with it. Find an ID in the dashboard URL when viewing a project (…/projects/<assistant_id>), via GET /v1/assistants, or under Organization → Assistant settings.

string

required

The user’s message. Must be between 1 and 10,000 characters.

string

Additional page or document context passed directly to the model alongside the retrieved chunks. Maximum 20,000 characters. Useful when building embedded chatbots — pass the current page’s content here so the model can answer questions about it even if it isn’t in the knowledge base.

boolean

default:"false"

When true, the response is returned as a Server-Sent Events stream instead of a single JSON object.

string

OpenAI-style reasoning effort: "low", "medium", or "high". Forwarded to the underlying model; only honored by reasoning-capable models (e.g. GPT-o series). When set, streaming responses additionally emit {"reasoning": "..."} events with the model’s intermediate thinking.

boolean

default:"false"

When true, the response also lists the documents the answer was drawn from. See Sources. Off by default, so the response is unchanged unless you ask.

Response

Non-streaming (default)

A JSON object with a single text field:

{
  "text": "Based on your documentation, customers can return items within 30 days of purchase for a full refund."
}

string

The AI-generated answer grounded in your knowledge base.

Streaming (`stream: true`)

Returns a text/event-stream response. Up to three event shapes may appear (the third only when you ask for sources), followed by a [DONE] sentinel:

HTTP/1.1 200 OK
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache, no-transform
Connection: keep-alive

data: {"text":"Based "}
data: {"text":"on "}
data: {"text":"your "}
data: {"text":"documentation, "}
data: {"text":"customers can return items within 30 days..."}
data: [DONE]

Event shape	When emitted
`{"text": "..."}`	A chunk of the final answer
`{"reasoning": "..."}`	A chunk of intermediate reasoning (only when `reasoning_effort` is set and the model supports it)
`{"sources": [...]}`	One event just before `[DONE]`, only when the request set `sources: true`

The stream always ends with data: [DONE]. Display reasoning chunks separately from the answer or ignore them — most users don’t need to show them.

Sources

Set sources: true to get back the documents the answer was drawn from — the files retrieval put in front of the model, most relevant first. Use it to show a reader where an answer came from, or to link to the original documents.

{
  "text": "Customers can return items within 30 days of purchase.",
  "sources": [
    { "fileId": "9f2c…", "fileName": "returns-policy.pdf", "rank": 1 },
    {
      "fileId": "4b7a…",
      "fileName": "Returns",
      "rank": 2,
      "brain": {
        "pageTitle": "Returns",
        "sources": [{ "fileName": "returns-policy.pdf", "span": "§2" }]
      }
    }
  ]
}

string

The file’s ID.

string | null

The file’s name, or null for documents ingested before names were stored.

integer

1 is the most relevant.

object

Present only when the file is a published Ragen Brain page. pageTitle is the page’s title, and sources lists the documents the page was built from, with span locating the passage in each. Only documents the API key is allowed to read are listed: a key that can read a page but not all of its documents gets the page and a shorter list, never the names of documents it cannot open.

When streaming, the list arrives as a single {"sources": [...]} event just before [DONE], so it reflects the finished answer:

data: {"text":"Customers can return items within 30 days."}
data: {"sources":[{"fileId":"9f2c…","fileName":"returns-policy.pdf","rank":1}]}
data: [DONE]

An answer that a guardrail withheld returns "sources": []. Documents outside your key’s scope never appear, because retrieval itself only reads what the key may read.

Examples

TypeScript SDK
curl
TypeScript (fetch)

Use the official @webamigos/ragen-sdk-ts package for typed responses, streaming iterators, and automatic retries.

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

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

// Non-streaming
const response = await ragen.chat.completions.create({
  assistantId: 'YOUR_ASSISTANT_ID',
  messages: [{ role: 'user', content: 'What is our return policy?' }],
});
console.log(response.choices[0].message.content);

// Streaming
const stream = await ragen.chat.completions.create({
  assistantId: 'YOUR_ASSISTANT_ID',
  messages: [{ role: 'user', content: 'Summarize our product features' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

# Non-streaming
curl -X POST $RAGEN_BASE_URL/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "YOUR_ASSISTANT_ID",
    "content": "What is our return policy?",
    "context": "This is the FAQ page of our e-commerce store."
  }'

# Streaming
curl -X POST $RAGEN_BASE_URL/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "assistant_id": "YOUR_ASSISTANT_ID",
    "content": "What is our return policy?",
    "stream": true
  }'

// Non-streaming
const response = await fetch(`${process.env.RAGEN_BASE_URL}/chat`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAGEN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    assistant_id: 'YOUR_ASSISTANT_ID',
    content: 'What is our return policy?',
  }),
});

const data = await response.json();
console.log(data.text);

// Streaming
const response = await fetch(`${process.env.RAGEN_BASE_URL}/chat`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAGEN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    assistant_id: 'YOUR_ASSISTANT_ID',
    content: 'What is our return policy?',
    stream: true,
  }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const text = decoder.decode(value);
  const lines = text.split('\n').filter((line) => line.startsWith('data: '));

  for (const line of lines) {
    const data = line.slice(6); // Remove "data: " prefix
    if (data === '[DONE]') break;
    const parsed = JSON.parse(data);
    if (parsed.text) process.stdout.write(parsed.text);
  }
}

Error codes

Status	Meaning
`400 Bad Request`	Invalid request body — missing `content`, character limit exceeded, or malformed JSON
`401 Unauthorized`	Missing, malformed, or invalid API key
`403 Forbidden`	API key is valid but has been deactivated
`429 Too Many Requests`	Rate limit exceeded — wait before retrying
`502 Bad Gateway`	Upstream service temporarily unavailable — retry with exponential backoff

Example error body:

{
  "statusCode": 400,
  "message": ["content must be between 1 and 10000 characters"],
  "error": "Bad Request"
}

Rate limits

Scope	Limit
Per IP address	20 requests / minute

When rate-limited, use exponential backoff with jitter. Each streaming and non-streaming request counts equally against this budget.

How the endpoint works

When you call POST /v1/chat, Ragen runs a five-step pipeline:

Authentication

Your API key is validated and the organization is resolved from it.

Assistant resolution

The assistant comes from the API key’s scope. A key bound to one assistant resolves to it; a knowledge-base key resolves to no assistant, and retrieval runs against the documents that belong to none. An assistant_id in the request must agree with that, or the call is refused with 403.

RAG retrieval

Relevant document chunks are retrieved from the assistant’s knowledge base with hybrid search (dense vectors plus BM25).

Reranking (when enabled)

If the deployment has reranking enabled, retrieved chunks are re-scored before being included in the prompt. It is off by default; see RAG pipeline.

Generation and response

The language model generates an answer using the retrieved context and your message. The response is returned as JSON or streamed as SSE.

Getting Started

Endpoints

SDKs & Tools

Chat API — Single-Turn RAG Question and Answer Endpoint

Endpoint

Request parameters

Response

Non-streaming (default)

Streaming (`stream: true`)

Sources

Examples

Error codes

Rate limits

How the endpoint works

​Endpoint

​Request parameters

​Response

​Non-streaming (default)

​Streaming (stream: true)

​Sources

​Examples

​Error codes

​Rate limits

​How the endpoint works

Endpoint

Request parameters

Response

Non-streaming (default)

Streaming (`stream: true`)

Sources

Examples

Error codes

Rate limits

How the endpoint works