API Route

Create and configure the server-side API route used by your react-ai-chat chatbot.

Introduction

react-ai-chat provides createChatRoute() for creating the server endpoint used by your chatbot.

It connects your route to an AI SDK-compatible language model, handles incoming chat messages, optionally retrieves RAG context, and streams the model response back to the client.

Basic setup

For a Next.js App Router application, create:

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

Then add:

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

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

Your chatbot can now send requests to /api/chat.

The ready-made <Chatbot /> component uses /api/chat by default. You can use a different endpoint with the apiEndpoint prop.

See Chatbot UI for client-side configuration.

How the route works

When a request reaches your route, createChatRoute():

Reads the incoming messages.
Limits the conversation history according to maxMessages.
Optionally retrieves relevant RAG context.
Builds the system prompt.
Converts the messages for the AI SDK.
Streams the model response back to the client.

The returned response uses the AI SDK UI message stream format.

Configuration

createChatRoute() accepts a ChatRouteOptions object.

`model`

The AI SDK language model used to generate responses.

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

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

This option is required.

The model can come from any provider supported by the AI SDK.

`systemPrompt`

Use systemPrompt to provide instructions for the model.

export const POST = createChatRoute({
  model: google("your-model"),
  systemPrompt: "You are a helpful assistant for my documentation.",
});

The default prompt is:

You are a helpful AI chatbot. Have natural, conversational interactions with the user. Answer questions clearly and accurately. Use the context provided to you when it is relevant to the user's question.

When RAG context is available, the retrieved content is added to the system prompt.

`maxMessages`

Use maxMessages to limit how many recent messages are sent to the model.

export const POST = createChatRoute({
  model: google("your-model"),
  maxMessages: 10,
});

The default is 6.

The route keeps the latest maxMessages messages:

All messages
    ↓
Keep latest maxMessages
    ↓
Convert to model messages
    ↓
Send to model

Limiting the conversation history can reduce the amount of data sent to the model and help control token usage.

RAG

You can optionally connect an embedding index to the route.

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

export const POST = createChatRoute({
  model: google("your-model"),
  rag: {
    index: embeddings,
    provider: yourEmbeddingProvider,
  },
});

When RAG is enabled, the latest user message is used as the retrieval query.

The default number of retrieved chunks is 3.

Use topK to change the number of retrieved chunks:

export const POST = createChatRoute({
  model: google("your-model"),
  rag: {
    index: embeddings,
    provider: yourEmbeddingProvider,
    topK: 5,
  },
});

The retrieval flow looks like this:

Latest user message
       ↓
Generate query embedding
       ↓
Compare with embedding index
       ↓
Select topK chunks
       ↓
Add relevant context to system prompt
       ↓
Generate response

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

See RAG for the complete setup.

Embedding provider

The embedding provider used for retrieval must match the provider and model configuration used to generate the embedding index.

For example, with Google:

import { GoogleGenAI } from "@google/genai";
import { 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,
});

Then pass the provider to createChatRoute():

export const POST = createChatRoute({
  model: google("your-model"),
  rag: {
    index: embeddings,
    provider,
  },
});

Use the provider configuration that matches the embedding index you generated.

See Providers for the supported embedding providers and configuration details.

Custom system prompts with RAG

When relevant context is found, react-ai-chat adds it to your system prompt.

Conceptually, the final system instructions look like:

Your system prompt

Here is relevant context retrieved from the application's knowledge base.
Use it when relevant to the user's question.

=== RELEVANT CONTEXT ===
Retrieved content
=======================

The retrieved context is supplied to the model as part of the system instructions.

Message handling

The route is designed to work with the message format used by the AI SDK UI message flow.

The ready-made <Chatbot /> component handles this communication automatically.

If you are building your own client, the request body contains a messages array:

{
  "messages": [
    {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "What is React?"
        }
      ]
    }
  ]
}

Only the most recent maxMessages messages are processed.

Streaming

Responses are streamed back to the client using the AI SDK UI message stream.

You do not need to manually create a ReadableStream or implement response chunking.

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

The returned route handler takes care of the streaming response.

Error handling

Errors from the route are represented using the package's chatbot error types.

Model-related failures can be reported as model errors.

Other execution failures are reported as chat route errors.

RAG retrieval errors are handled separately. They are logged and the model can continue without the retrieved context.

For client-side error handling, see Chatbot UI.

Complete example

A complete Next.js API route can look like this:

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

export const POST = createChatRoute({
  model: google("your-model"),
  systemPrompt: "You are a helpful assistant for my documentation website.",
  maxMessages: 8,
});

Then connect the ready-made chatbot to the route:

import { Chatbot } from "react-ai-chat";
import "react-ai-chat/style.css";

export default function Page() {
  return <Chatbot apiEndpoint="/api/chat" />;
}