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

Lobe Chat defines all API routes within the Next.js 13+ App Router at src/app/(backend)/api/, where each 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 (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 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:

// 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:

// 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 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 (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 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 file, as implemented throughout the lobehub/lobe-chat repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}