createChatRoute

Introduction

createChatRoute() creates a server-side POST handler for your chatbot.

It processes incoming messages, optionally retrieves relevant context with RAG, applies system instructions, and streams the model response.

Import

import { createChatRoute } from "react-ai-chat/server";

Basic usage

import { google } from "@ai-sdk/google";
import { createChatRoute } from "react-ai-chat/server";

export const POST = createChatRoute({
  model: google("gemini-3.5-flash"),
});

The returned handler can be exported directly from a framework route.

For Next.js App Router:

app/
└── api/
    └── chat/
        └── route.ts

Options

model

model: LanguageModel;

The language model used to generate responses.

createChatRoute({
  model: google("gemini-3.5-flash"),
});

This option is required.

The model is provided by the AI SDK provider you choose.

systemPrompt

systemPrompt?: string

Defines the system instructions sent to the model.

createChatRoute({
  model: google("gemini-3.5-flash"),
  systemPrompt: "You are a helpful assistant for my documentation website.",
});

If omitted, the route uses the package's default chatbot system prompt.

When RAG is enabled and relevant chunks are found, the retrieved context is added to the system prompt.

maxMessages

maxMessages?: number

Controls how many recent messages are sent to the model.

createChatRoute({
  model: google("gemini-3.5-flash"),
  maxMessages: 10,
});

Default: 6

The route keeps the most recent messages up to this limit before sending them to the model.

rag

rag?: RagConfig

Enables retrieval augmented generation.

createChatRoute({
  model: google("gemini-3.5-flash"),
  rag: {
    index: embeddings,
    provider,
    topK: 3,
  },
});

The RAG configuration contains:

topK defaults to 3.

See RAG for the complete setup.

Complete RAG example

For Google embeddings, a complete route can look like this:

import { google } from "@ai-sdk/google";
import { GoogleGenAI } from "@google/genai";
import { createChatRoute, googleEmbedding } from "react-ai-chat/server";
import embeddings from "@/chatbot/embeddings.json";

const client = new GoogleGenAI({
  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
});

const provider = googleEmbedding(client, {
  model: embeddings.model,
});

export const POST = createChatRoute({
  model: google("gemini-3.5-flash"),
  rag: {
    index: embeddings,
    provider,
    topK: 3,
  },
});

The embedding model is read from the generated index:

model: embeddings.model;

This keeps the embedding provider configuration aligned with the index.

The chat model is configured independently:

model: google("gemini-3.5-flash");

Request flow

The route processes a request roughly like this:

Request
  ↓
Read messages
  ↓
Keep latest maxMessages
  ↓
Retrieve RAG context
  ↓
Build system prompt
  ↓
Convert messages
  ↓
Stream model response

Message limits

Suppose the client sends eight messages and the route uses:

maxMessages: 4;

Only the latest four messages are passed to the model.

This helps control the amount of conversation context included in each request.

RAG retrieval

When RAG is configured, the latest user message is used as the retrieval query for generating the query embedding.

The route:

1. Generates an embedding for the query.
2. Compares it against the stored vectors.
3. Selects the most relevant chunks.
4. Adds the retrieved content to the system prompt.
5. Sends the resulting prompt to the language model.

If no relevant context is available, the model can continue without retrieved content.

Streaming

createChatRoute() returns a streaming response compatible with the AI SDK UI message stream.

The route handles stream creation for you, so you can export the returned handler directly from your API route.

export const POST = createChatRoute({
  model: google("gemini-3.5-flash"),
});

Error handling

The route handles errors that occur during model generation and route execution.

Model-related errors are converted into ChatbotError instances with an appropriate error code and message.

RAG retrieval errors are handled separately from model generation.

If retrieval fails, the error is logged and the chat request continues without the retrieved context.

Custom API endpoint

The API route does not need to be named /api/chat.

For example:

app/
└── api/
    └── assistant/
        └── route.ts

The route can remain:

export const POST = createChatRoute({
  model: google("gemini-3.5-flash"),
});

Then point the chatbot to it:

<Chatbot apiEndpoint="/api/assistant" />

Complete basic route

import { google } from "@ai-sdk/google";
import { createChatRoute } from "react-ai-chat/server";

export const POST = createChatRoute({
  model: google("gemini-3.5-flash"),
  systemPrompt: "You are a helpful assistant. Answer clearly and accurately.",
  maxMessages: 8,
});

Related APIs