Where to Find Lobe Chat API Documentation: A Complete Developer Guide

Lobe Chat's API documentation lives directly in the source code under src/app/(backend)/api, where Next.js route handlers define REST endpoints for agent execution, streaming, and authentication.

The Lobe Chat API is built into the lobehub/lobe-chat repository as a set of conventional HTTP endpoints. Unlike external documentation sites, the authoritative reference for request shapes, authentication requirements, and response formats is found in the TypeScript route files themselves.

Lobe Chat API Architecture Overview

Lobe Chat implements its public API using the Next.js App Router convention. Each folder under src/app/(backend)/api represents an endpoint, with route.ts files exporting HTTP method handlers (GET, POST, etc.).

The architecture follows these principles:

• Route handlers are located at src/app/(backend)/api/**/route.ts
• Request validation checks for AGENT_EXEC_API_KEY or QStash signatures before processing
• Business logic is delegated to server services (e.g., src/server/services/aiAgent.ts)
• Response formats return JSON with a standard shape ({ error?, data?, executionTime }) or Server-Sent Events (SSE) for streaming

Core API Endpoints and Source Locations

The following table maps key Lobe Chat API functionality to its source file location and purpose:

Feature	Route (Method)	Purpose	Source File
Version	GET /api/version	Returns the current package version for health checks.	src/app/(backend)/api/version/route.ts
Agent Execution	POST /api/agent	Execute an agent with a prompt and optional context.	src/app/(backend)/api/agent/route.ts
Agent Streaming	GET /api/agent/stream	SSE endpoint that streams the LLM response token-by-token.	src/app/(backend)/api/agent/stream/route.ts
Agent Run (Legacy)	POST /api/agent/run	Compatibility wrapper forwarding to newer execution endpoint.	src/app/(backend)/api/agent/run/route.ts
Authentication	GET/POST /api/auth/*	All auth operations delegated to better-auth.	src/app/(backend)/api/auth/[...all]/route.ts
Webhooks	POST /api/webhooks/*	Handlers for QStash, video platforms, and memory extraction.	src/app/(backend)/api/webhooks/**/route.ts
Plugin Manifest	Internal helper	Parses OpenAPI manifests for third-party plugin function calling.	packages/utils/src/toolManifest.ts

Authentication and Security

Lobe Chat API endpoints implement two primary authentication mechanisms:

API Key Authentication: The agent execution endpoints accept an AGENT_EXEC_API_KEY environment variable. Requests must include this key in the Authorization: Bearer <key> header to access /api/agent and related routes.

Better-Auth Integration: All user authentication flows (login, token refresh, session management) are handled by the better-auth library through the catch-all route at src/app/(backend)/api/auth/[...all]/route.ts.

For webhook endpoints (such as QStash integrations), requests are validated using signature verification rather than bearer tokens.

Practical API Usage Examples

Check the Version Endpoint

Use the version endpoint to verify connectivity and determine the running build:

// Example using fetch (Node.js or browser)
const resp = await fetch('https://your-lobehub-instance.com/api/version');
if (!resp.ok) throw new Error('Failed to fetch version');
const data = await resp.json();   // { version: '2.1.35-canary.9' }
console.log('LobeChat version:', data.version);

Source: src/app/(backend)/api/version/route.ts

Execute an Agent (POST /api/agent)

Submit a prompt to an agent and receive a synchronous response:

import fetch from 'node-fetch';

const payload = {
  userId: 'user-123',
  // either `agentId` or `slug` – here we use a slug for the built-in "chat" agent
  slug: 'chat',
  prompt: 'Explain the theory of relativity in simple terms.',
  appContext: {},               // optional extra context
  autoStart: true,              // start the run immediately
};

const resp = await fetch('https://your-lobehub-instance.com/api/agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // optional API-key header if the server is configured with AGENT_EXEC_API_KEY
    // Authorization: 'Bearer <your-key>',
  },
  body: JSON.stringify(payload),
});

const result = await resp.json();
if (result.error) {
  console.error('Agent error:', result.error);
} else {
  console.log('Agent operation ID:', result.operationId);
  console.log('Full result:', result);
}

Source: src/app/(backend)/api/agent/route.ts

Stream the LLM Response (GET /api/agent/stream)

Consume token-by-token output using Server-Sent Events:

// Browser example using EventSource
const es = new EventSource(
  'https://your-lobehub-instance.com/api/agent/stream?operationId=op-abc123',
);

es.onmessage = (e) => {
  // Each message contains a JSON fragment: { token: "...", done: false }
  const part = JSON.parse(e.data);
  process.stdout.write(part.token);
  if (part.done) es.close();
};

es.onerror = (err) => {
  console.error('Streaming error', err);
  es.close();
};

Source: src/app/(backend)/api/agent/stream/route.ts

Authenticate a Request

The authentication endpoints are handled by better-auth:

// Using the better-auth client (example – details are in the auth library docs)
import { signIn } from 'better-auth/client';

await signIn('credentials', {
  email: 'you@example.com',
  password: 'super-secret',
});

Source: src/app/(backend)/api/auth/[...all]/route.ts

Summary

• Lobe Chat API documentation is located directly in the source code at src/app/(backend)/api, where Next.js route handlers define REST endpoints.
• Key endpoints include /api/version for health checks, /api/agent for synchronous execution, and /api/agent/stream for SSE streaming.
• Authentication uses AGENT_EXEC_API_KEY for programmatic access and better-auth for user sessions.
• Plugin manifests are parsed via packages/utils/src/toolManifest.ts for OpenAPI-based tool calling.

Frequently Asked Questions

Is there an official external documentation site for the Lobe Chat API?

While the repository's README points to a "Getting Started" guide and general Docs site, the authoritative reference for API endpoints is the source code itself. The route handlers in src/app/(backend)/api/**/route.ts contain the most current request/response schemas and authentication requirements.

How do I authenticate requests to the Lobe Chat API?

Programmatic access to agent endpoints requires an Authorization: Bearer <token> header containing the AGENT_EXEC_API_KEY value configured in your environment. User authentication flows (login, signup, session management) are handled by the better-auth library through the /api/auth/* catch-all route.

What is the difference between /api/agent and /api/agent/stream?

The POST /api/agent endpoint returns a complete JSON response after the LLM finishes processing, suitable for synchronous use cases. The GET /api/agent/stream endpoint establishes a Server-Sent Events (SSE) connection that streams tokens as they are generated by the model, enabling real-time chat interfaces.

Where can I find the OpenAPI specification for Lobe Chat plugins?

Plugin manifest parsing is implemented in packages/utils/src/toolManifest.ts. This utility file handles the conversion of third-party OpenAPI specifications into the internal format required by Lobe Chat's function-calling system, though it is not a publicly exposed HTTP endpoint.

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