# How to Use the DB‑GPT API to Integrate Chat Functionality into External Applications

> Easily integrate chat into your apps using the DB-GPT API. Discover how to leverage its OpenAI-compatible endpoint with the Python SDK or HTTP requests for seamless chat functionality.

- Repository: [eosphoros/DB-GPT](https://github.com/eosphoros-ai/db-gpt)
- Tags: how-to-guide
- Published: 2026-02-23

---

**DB‑GPT exposes an OpenAI‑compatible HTTP API at `/api/v2/chat/completions` that you can call using the official `dbgpt_client` Python SDK or raw HTTP requests, supporting both synchronous responses and streaming Server‑Sent Events.**

The eosphoros-ai/DB‑GPT repository provides a production‑ready chat API that allows external applications to leverage its LLM capabilities, including RAG, SQL execution, and AWEL flows. By implementing an OpenAI‑compatible endpoint, DB‑GPT enables seamless integration with existing AI tooling and custom client implementations without requiring proprietary protocols.

## Architecture of the DB‑GPT Chat API

Understanding the request flow helps debug integration issues and optimize performance. The architecture consists of five distinct layers:

- **Client SDK**: The `dbgpt_client.Client` class wraps `httpx.AsyncClient` and provides high‑level `chat` and `chat_stream` helpers. It builds a `ChatCompletionRequestBody` payload and posts it to the server. Source: [[`packages/dbgpt-client/src/dbgpt_client/client.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-client/src/dbgpt_client/client.py)](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-client/src/dbgpt_client/client.py#L52-L70).

- **Request Model**: `ChatCompletionRequestBody` is a Pydantic model that mirrors OpenAI’s Chat Completion schema while adding DB‑GPT‑specific fields like `chat_mode`, `conv_uid`, and `enable_vis`. Source: [[`packages/dbgpt-client/src/dbgpt_client/schema.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-client/src/dbgpt_client/schema.py)](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-client/src/dbgpt_client/schema.py#L16-L55).

- **HTTP Transport**: The client uses `httpx.AsyncClient` to perform async POST requests to `"{api_base}/chat/completions"` (defaulting to `http://localhost:5670/api/v2`). Source: [[`client.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/client.py) lines 180‑183](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-client/src/dbgpt_client/client.py#L180-L183).

- **Server Router**: The FastAPI `chat_completions` endpoint receives requests, validates them via dependencies, and instantiates a concrete `BaseChat` implementation based on the `chat_mode` parameter. It returns either JSON or a `StreamingResponse` (SSE). Source: [[`packages/dbgpt-app/src/dbgpt_app/openapi/api_v2.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/openapi/api_v2.py)](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/openapi/api_v2.py#L71-L100).

- **Chat Engine**: Concrete `BaseChat` subclasses in `dbgpt_app/scene` handle the actual LLM inference, vector store queries, or SQL execution based on the selected mode.

- **Authentication**: The optional `check_api_key` dependency validates `Authorization: Bearer <key>` headers against configured API keys. Source: [[`api_v2.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/api_v2.py) lines 43‑66](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/openapi/api_v2.py#L43-L66).

## Installing the DB‑GPT Python Client

To use the SDK, install the `dbgpt-client` package from the DB‑GPT repository:

```bash
pip install dbgpt-client

```

The client defaults to `http://localhost:5670/api/v2` but can be configured via the `DBGPT_API_BASE` environment variable or constructor arguments.

## Sending Chat Requests with the Python SDK

The `Client` class provides both synchronous‑style (async) and streaming interfaces for chat completions.

### Non‑Streaming Chat Requests

For simple request‑response interactions, use the `chat` method which returns a complete `ChatCompletionResponse`:

```python
from dbgpt_client import Client

client = Client(
    api_base="http://localhost:5670/api/v2",
    api_key="your-dbgpt-api-key"  # Optional: only if server requires auth

)

response = await client.chat(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello, DB‑GPT!"}],
    temperature=0.7,
    chat_mode="chat_normal"
)

print(response.choices[0].message.content)

```

The `chat_mode` parameter defaults to `"chat_normal"` but supports other modes for specialized functionality.

### Streaming Responses for Real‑Time UIs

For applications that require incremental output (like chat UIs), use `chat_stream` which yields Server‑Sent Events:

```python
async for chunk in client.chat_stream(
    model="gpt-4",
    messages="Explain quantum computing in one sentence.",
    stream=True
):
    # Each chunk is a ChatCompletionStreamResponse

    print(chunk.choices[0].delta.content, end="", flush=True)

```

This method handles the SSE parsing automatically, providing typed `ChatCompletionStreamResponse` objects for each token chunk.

### Using Different Chat Modes (RAG, AWEL Flows, and Data Analysis)

DB‑GPT extends standard chat completion with **chat modes** that trigger specific pipelines:

- **`chat_normal`**: Standard conversational AI without external data sources.
- **`chat_knowledge`**: Enables RAG (Retrieval‑Augmented Generation) against configured knowledge bases.
- **`chat_flow`**: Triggers an AWEL (Agentic Workflow Expression Language) flow.
- **`chat_data`**: Executes SQL queries against connected databases.

Specify the mode in the request:

```python
response = await client.chat(
    model="gpt-4",
    messages="What are the main challenges of LLM‑based RAG?",
    chat_mode="chat_knowledge",  # Enables vector store retrieval

    temperature=0.6
)

```

## Integrating via Raw HTTP Requests

If you cannot use the Python SDK, send raw HTTP POST requests to the `/chat/completions` endpoint. The API accepts standard JSON payloads and returns OpenAI‑compatible responses.

```bash
curl -X POST http://localhost:5670/api/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-dbgpt-api-key" \
  -d '{
        "model": "gpt-4",
        "messages": [{"role":"user","content":"What is the capital of France?"}],
        "temperature": 0.5,
        "chat_mode": "chat_normal",
        "stream": false
      }'

```

For streaming, set `"stream": true` and process the Server‑Sent Events returned by the server. Use tools like `curl --no-buffer -N` or HTTP libraries with SSE support to handle the incremental response chunks.

## Authentication and API Security

When the DB‑GPT server is configured with `api_keys` (set via the `DBGPT_API_KEYS` environment variable), all requests must include an `Authorization` header:

- **Header format**: `Authorization: Bearer <your-api-key>`
- **Client handling**: The `dbgpt_client.Client` automatically injects this header when initialized with an `api_key` parameter.
- **Server validation**: The `check_api_key` dependency in [`api_v2.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/api_v2.py) validates tokens against the server’s configured key store.

If the server runs without API key configuration, requests proceed without authentication headers.

## Complete Integration Examples

### Basic Q&A Implementation

This example demonstrates a minimal async script for simple question‑answering:

```python
import asyncio
from dbgpt_client import Client

async def main():
    client = Client()  # Uses DBGPT_API_BASE from environment

    reply = await client.chat(
        model="gpt-4o-mini",
        messages="Summarize the plot of *The Matrix* in 2 sentences.",
        temperature=0.3
    )
    print(reply.choices[0].message.content)

asyncio.run(main())

```

### Knowledge‑Augmented Retrieval (RAG)

To query documents stored in DB‑GPT’s vector stores:

```python
import asyncio
from dbgpt_client import Client

async def rag_query():
    client = Client()
    resp = await client.chat(
        model="gpt-4o-mini",
        messages="What are the main challenges of LLM‑based RAG?",
        chat_mode="chat_knowledge",
        temperature=0.6
    )
    print(resp.choices[0].message.content)

asyncio.run(rag_query())

```

The `chat_mode="chat_knowledge"` setting activates the RAG pipeline defined in the `BaseChat` implementation within the `dbgpt_app/scene` module.

### Building a Proxy API with FastAPI

You can wrap DB‑GPT’s client in your own FastAPI application to add business logic or rate limiting:

```python
from fastapi import FastAPI
from dbgpt_client import Client

app = FastAPI()
client = Client()

@app.post("/proxy/chat")
async def proxy_chat(messages: str):
    async for chunk in client.chat_stream(
        model="gpt-4o-mini",
        messages=messages,
        stream=True
    ):
        # Forward SSE chunks to the caller

        yield f"data: {chunk.json()}\n\n"

```

This pattern allows you to expose DB‑GPT capabilities through your own API contract while leveraging the underlying streaming infrastructure.

## Summary

- **DB‑GPT provides an OpenAI‑compatible API** at `/api/v2/chat/completions` defined in [`packages/dbgpt-app/src/dbgpt_app/openapi/api_v2.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/openapi/api_v2.py).
- **Use the `dbgpt_client` Python SDK** for type‑safe, async interactions instead of raw HTTP.
- **Support for multiple chat modes** (`chat_normal`, `chat_knowledge`, `chat_flow`, `chat_data`) enables RAG, SQL execution, and workflow automation through the same endpoint.
- **Streaming is implemented via Server‑Sent Events** using the `chat_stream` method or by setting `stream: true` in HTTP requests.
- **Authentication uses standard Bearer tokens** validated by the `check_api_key` dependency when `DBGPT_API_KEYS` is configured.
- **Key source files** include [`client.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/client.py) for the SDK, [`schema.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/schema.py) for request models, and [`api_v2.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/api_v2.py) for the FastAPI router implementation.

## Frequently Asked Questions

### Is the DB‑GPT API compatible with OpenAI's API format?

Yes, DB‑GPT implements an OpenAI‑compatible Chat Completions interface. The `ChatCompletionRequestBody` model in [`packages/dbgpt-client/src/dbgpt_client/schema.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-client/src/dbgpt_client/schema.py) mirrors OpenAI’s request schema, allowing you to use standard OpenAI client libraries by simply changing the `base_url` to your DB‑GPT instance (e.g., `http://localhost:5670/api/v2`).

### What are the available chat modes in DB‑GPT?

DB‑GPT supports several chat modes controlled by the `chat_mode` parameter: `chat_normal` for standard conversation, `chat_knowledge` for RAG‑augmented responses using vector stores, `chat_flow` for executing AWEL agentic workflows, and `chat_data` for SQL generation and database querying. These modes are processed by corresponding `BaseChat` subclasses in the `dbgpt_app/scene` directory.

### How do I handle streaming responses in my application?

For streaming, set `stream=True` in your request and use the `chat_stream` method in the Python SDK, which yields `ChatCompletionStreamResponse` objects. If using raw HTTP, consume the response as Server‑Sent Events (SSE) from the `/chat/completions` endpoint. The SDK handles SSE parsing automatically, while raw implementations must parse the event stream format.

### Where is the chat completion endpoint defined in the source code?

The main chat completion endpoint is defined in [`packages/dbgpt-app/src/dbgpt_app/openapi/api_v2.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/openapi/api_v2.py) within the `chat_completions` function (lines 71‑100). This FastAPI route handles request validation via the `check_api_key` dependency, instantiates the appropriate `BaseChat` implementation based on `chat_mode`, and returns either JSON or a `StreamingResponse` for SSE streams.