# Where Are the API Routes Defined in Lobe Chat? Next.js App Router Deep Dive

> Discover where Lobe Chat defines API routes using the Next.js App Router, located in src/app/(backend)/api/. Learn how route.ts files manage HTTP methods.

- Repository: [LobeHub/lobe-chat](https://github.com/lobehub/lobe-chat)
- Tags: deep-dive
- Published: 2026-03-03

---

**Lobe Chat defines all API routes within the Next.js 13+ App Router at `src/app/(backend)/api/`, where each [`route.ts`](https://github.com/lobehub/lobe-chat/blob/main/route.ts) file exports HTTP method handlers like `GET` and `POST` to handle server-side requests.**

Lobe Chat is a modern, open-source AI chat application built on Next.js 13+. Understanding exactly where API routes are defined in Lobe Chat is essential for developers extending its backend capabilities or debugging server-side logic. The codebase leverages the Next.js App Router architecture, organizing all server endpoints under a single, predictable directory hierarchy that maps directly to URL paths.

## Root Location of API Routes in Lobe Chat

All backend API endpoints reside under **`src/app/(backend)/api/`**. This directory uses Next.js **route groups**—the parentheses in `(backend)` indicate a logical grouping that organizes files without affecting the URL path structure.

The folder hierarchy directly determines the endpoint URL. For example, a file located at `src/app/(backend)/api/agent/stream/route.ts` automatically becomes accessible at the `/api/agent/stream` endpoint. Each route is implemented as a standalone TypeScript file named [`route.ts`](https://github.com/lobehub/lobe-chat/blob/main/route.ts) (or `.tsx`), following the Next.js 13+ convention for colocated server logic and API handlers.

## Route File Structure and HTTP Handlers

Within each [`route.ts`](https://github.com/lobehub/lobe-chat/blob/main/route.ts) file, Lobe Chat exports named constants corresponding to HTTP methods. The framework automatically routes incoming requests to the appropriate exported handler based on the HTTP verb.

For instance, the agent streaming endpoint at `src/app/(backend)/api/agent/stream/route.ts` exports a `POST` handler to manage Server-Sent Events (SSE) for real-time LLM responses:

```typescript
// src/app/(backend)/api/agent/stream/route.ts
export const POST = async (req: Request): Promise<Response> => {
  // Parse the incoming payload, start an LLM stream, and pipe SSE events back
  // …
};

```

Handlers receive a standard Web API `Request` (or Next.js `NextRequest`) and must return a `Response` (or `NextResponse`). Route files can export multiple handlers—such as `GET`, `POST`, `PUT`, or `DELETE`—to support different operations on the same path. Some routes also export configuration variables like `export const dynamic = 'force-static'` when requiring specific caching behaviors or runtime constraints.

## Dynamic and Catch-All Route Patterns

Lobe Chat utilizes Next.js bracket syntax for parameterized and catch-all routes. Dynamic segments like `[provider]` or `[...all]` allow a single route file to handle multiple URL patterns flexibly.

Consider the video webhook endpoint at `src/app/(backend)/api/webhooks/video/[provider]/route.ts`. The `provider` parameter captures varying provider names (e.g., "youtube", "vimeo") within the same file:

```typescript
// src/app/(backend)/api/webhooks/video/[provider]/route.ts
export const POST = async (
  req: Request,
  { params }: { params: Promise<{ provider: string }> }
) => {
  const { provider } = await params;   // e.g., "youtube"
  // Process the webhook payload for the specific video provider
  // …
};

```

Similarly, the authentication endpoint at `src/app/(backend)/api/auth/[...all]/route.ts` uses the spread operator `[...all]` to catch all sub-paths under `/api/auth/`, delegating various auth actions—such as login, token refresh, and OAuth callbacks—to a single, centralized handler.

## Key API Endpoints and Their Functions

The `src/app/(backend)/api/` directory contains several critical route groups that power the application's backend functionality:

- **`src/app/(backend)/api/auth/[...all]/route.ts`** – Central authentication hub handling login flows, token validation, and OAuth callbacks through catch-all routing.
- **`src/app/(backend)/api/agent/stream/route.ts`** – Implements Server-Sent Events (SSE) for streaming LLM responses to the frontend in real time.
- **`src/app/(backend)/api/agent/run/route.ts`** – Executes one-off LLM runs via POST requests containing prompt configurations and conversation context.
- **`src/app/(backend)/api/webhooks/video/[provider]/route.ts`** – Receives asynchronous callbacks from video providers using dynamic routing to distinguish between platforms like YouTube or Vimeo.
- **`src/app/(backend)/api/webhooks/memory-extraction/route.ts`** – Processes external memory extraction service callbacks to enrich user context and session memory.
- **`src/app/(backend)/api/workflows/agent-eval-run/run-agent-trajectory/route.ts`** – Runs full evaluation trajectories for agent performance testing and benchmarking workflows.
- **`src/app/(backend)/api/version/route.ts`** – Simple health-check endpoint returning the current application version via a lightweight `GET` handler.

## Summary

- **Lobe Chat places all API routes under `src/app/(backend)/api/`**, utilizing the Next.js 13+ App Router convention for file-system based routing.
- **Each endpoint is a [`route.ts`](https://github.com/lobehub/lobe-chat/blob/main/route.ts) file** exporting specific HTTP method handlers (`GET`, `POST`, etc.) that accept `Request` objects and return `Response` objects.
- **Dynamic routing** is implemented using bracket syntax (`[param]`, `[...slug]`), enabling parameterized paths and catch-all routes for flexible endpoint design without complex configuration.
- **Key functional areas**—including authentication, agent streaming, webhooks, and workflow execution—are organized in dedicated subdirectories under the API root, making the codebase navigable and maintainable.

## Frequently Asked Questions

### What file naming convention does Lobe Chat use for API routes?

Lobe Chat follows the Next.js App Router convention where every API endpoint is defined in a file named **[`route.ts`](https://github.com/lobehub/lobe-chat/blob/main/route.ts)** (or `.tsx`) located within the corresponding directory path. The directory structure itself defines the URL route, and the file exports async handler functions named after HTTP methods like `GET` or `POST`.

### How does Lobe Chat handle dynamic parameters in API routes?

Dynamic parameters use **bracket notation** in the folder name, such as `[provider]` for single segments or `[...all]` for catch-all paths. According to the source code in `src/app/(backend)/api/webhooks/video/[provider]/route.ts`, handlers receive these parameters through the `params` property, which is a Promise resolving to an object containing the dynamic values (e.g., `{ provider: string }`).

### Can I add custom API endpoints to Lobe Chat?

Yes. To extend the backend, create a new directory under `src/app/(backend)/api/` matching your desired URL path, then add a [`route.ts`](https://github.com/lobehub/lobe-chat/blob/main/route.ts) file exporting the required HTTP method handlers. The Next.js App Router will automatically register the new endpoint without additional routing configuration, following the same patterns used for existing routes like `agent/run` or `version`.

### What framework powers the API routing in Lobe Chat?

The backend API is built on **Next.js 13+** using the **App Router** architecture. This framework handles request routing, parsing, and response construction automatically based on the file system structure and exported handlers in each [`route.ts`](https://github.com/lobehub/lobe-chat/blob/main/route.ts) file, as implemented throughout the `lobehub/lobe-chat` repository.