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

> Find comprehensive Lobe Chat API documentation within the source code at src/app/(backend)/api. Discover REST endpoints for agent execution streaming and authentication.

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

---

**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`](https://github.com/lobehub/lobe-chat/blob/main/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`](https://github.com/lobehub/lobe-chat/blob/main/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`](https://github.com/lobehub/lobe-chat/blob/main/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:

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

```typescript
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:

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

```typescript
// 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`](https://github.com/lobehub/lobe-chat/blob/main/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`](https://github.com/lobehub/lobe-chat/blob/main/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.