This document describes DB-GPT's web interface and REST API layer, which provides the primary user-facing interaction mechanisms for the system. The web interface consists of a Next.js frontend application and a FastAPI backend that exposes REST endpoints for all core functionalities.
Related Documentation:
DB-GPT's web layer follows a modern client-server architecture with clear separation between the presentation layer (Next.js) and the API layer (FastAPI).
Sources: README.md62-66 README.zh.md62-66
DB-GPT uses FastAPI as its REST API framework, providing automatic OpenAPI documentation, request validation, and high-performance asynchronous request handling.
Sources: README.md55-58 README.zh.md55-58
Sources: README.md55-81
All API requests follow a consistent schema validation pattern using Pydantic models:
Request Body:
- Validated against Pydantic models
- Type checking enforced
- Required fields validated
- Default values applied
Standard response format across all endpoints:
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates if the request was successful |
data | object | Response payload data |
message | string | Human-readable message |
error_code | string | Error code (if applicable) |
Sources: packages/dbgpt-core/src/dbgpt/storage/metadata/db_storage.py1-132
| Endpoint | Method | Description |
|---|---|---|
/api/v1/model/types | GET | List supported model types |
/api/v1/model/list | GET | List deployed models |
/api/v1/model/start | POST | Start a model instance |
/api/v1/model/stop | POST | Stop a model instance |
/api/v1/model/metadata | GET | Get model metadata |
Sources: README.md180-292 README.zh.md192-303
| Endpoint | Method | Description |
|---|---|---|
/api/v1/knowledge/space/list | GET | List knowledge spaces |
/api/v1/knowledge/space/create | POST | Create knowledge space |
/api/v1/knowledge/document/upload | POST | Upload documents |
/api/v1/knowledge/document/sync | POST | Sync document embeddings |
/api/v1/rag/retrieve | POST | Retrieve relevant context |
/api/v1/rag/query | POST | RAG-based query |
Sources: README.md70-71 README.zh.md68-69
| Endpoint | Method | Description |
|---|---|---|
/api/v1/agent/list | GET | List available agents |
/api/v1/agent/create | POST | Create agent instance |
/api/v1/agent/execute | POST | Execute agent task |
/api/v1/awel/flow/list | GET | List AWEL workflows |
/api/v1/awel/flow/create | POST | Create workflow |
/api/v1/awel/flow/trigger | POST | Trigger workflow execution |
Sources: README.md76-77 README.zh.md74-75
| Endpoint | Method | Description |
|---|---|---|
/api/v1/gbi/datasource/list | GET | List data sources |
/api/v1/gbi/datasource/connect | POST | Connect to data source |
/api/v1/gbi/query | POST | Natural language to SQL query |
/api/v1/gbi/execute | POST | Execute SQL query |
/api/v1/gbi/visualize | POST | Generate visualization |
Sources: README.md72-73 README.zh.md70-71
The web frontend is a modern React application built with Next.js, providing server-side rendering and optimized client-side navigation.
Sources: .gitignore161-184
| Directory | Purpose |
|---|---|
/web/pages/ | Next.js page routes |
/web/components/ | React components |
/web/public/ | Static assets |
/web/styles/ | CSS and styling |
/web/.next/ | Next.js build output (generated) |
Sources: .gitignore161-184
The frontend uses a centralized API client service to communicate with the FastAPI backend:
Key Features:
Sources: .gitignore161-184
| Feature | Implementation |
|---|---|
| Authentication | JWT-based token authentication |
| Authorization | Role-based access control (RBAC) |
| CORS | Configurable cross-origin resource sharing |
| Input Validation | Pydantic schema validation |
| SQL Injection Prevention | SQLAlchemy ORM with parameterized queries |
| XSS Protection | Content Security Policy headers |
Sources: packages/dbgpt-core/src/dbgpt/storage/metadata/db_storage.py1-132
DB-GPT provides WebSocket endpoints for real-time streaming of LLM responses and agent execution status.
| Endpoint | Protocol | Purpose |
|---|---|---|
/api/v1/stream/chat | WebSocket | Stream chat responses |
/api/v1/stream/agent | WebSocket | Stream agent execution |
/api/v1/stream/sql | WebSocket | Stream SQL execution results |
Sources: README.md55-58
The API server can be configured through environment variables or configuration files:
| Variable | Default | Description |
|---|---|---|
API_HOST | 0.0.0.0 | API server bind address |
API_PORT | 5670 | API server port |
API_WORKERS | 4 | Number of worker processes |
CORS_ORIGINS | ["*"] | Allowed CORS origins |
JWT_SECRET | (required) | Secret key for JWT signing |
JWT_EXPIRATION | 86400 | JWT token expiration (seconds) |
Web configuration in /web/.env:
| Variable | Description |
|---|---|
NEXT_PUBLIC_API_BASE_URL | Backend API base URL |
NEXT_PUBLIC_WS_URL | WebSocket server URL |
NEXT_PUBLIC_API_TIMEOUT | API request timeout (ms) |
Sources: .gitignore178-180 README.md145-159
The web interface and API are typically deployed together using Docker Compose:
Service Configuration:
webserver service runs both Next.js and FastAPIFor standalone deployment:
Backend (FastAPI):
dbgpt start webserver --host 0.0.0.0 --port 5670
Frontend (Next.js):
cd web
npm run build
npm run start
Sources: README.md139-159 README.zh.md142-173
DB-GPT automatically generates interactive API documentation:
| URL | Description |
|---|---|
http://localhost:5670/docs | Swagger UI (OpenAPI documentation) |
http://localhost:5670/redoc | ReDoc alternative documentation |
http://localhost:5670/openapi.json | OpenAPI specification (JSON) |
The documentation includes:
Sources: README.md55-58
All errors follow a consistent format:
| Status Code | Meaning | Common Causes |
|---|---|---|
| 200 | Success | Request processed successfully |
| 400 | Bad Request | Invalid request parameters |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource does not exist |
| 422 | Unprocessable Entity | Request validation failed |
| 500 | Internal Server Error | Server-side error |
| 503 | Service Unavailable | Service temporarily unavailable |
Sources: packages/dbgpt-core/src/dbgpt/storage/metadata/db_storage.py1-132
Refresh this wiki