7. Backend API System

Relevant source files

• api/apps/__init__.py
• api/apps/backward_compat.py
• api/settings.py
• api/utils/api_utils.py
• api/utils/validation_utils.py
• docs/references/http_api_reference.md
• docs/references/python_api_reference.md
• docs/release_notes.md
• internal/admin/router.go
• internal/cli/admin_command.go
• internal/cli/admin_parser.go
• internal/cli/cli.go
• internal/cli/cli_http.go
• internal/cli/common_command.go
• internal/cli/lexer.go
• internal/cli/parser.go
• internal/cli/types.go
• internal/cli/user_command.go
• internal/cli/user_parser.go
• internal/dao/document.go
• internal/dao/document_test.go
• internal/handler/document.go
• internal/handler/document_test.go
• internal/router/router.go
• internal/service/nlp/retrieval.go
• sdk/python/ragflow_sdk/modules/__init__.py
• sdk/python/ragflow_sdk/modules/agent.py
• sdk/python/ragflow_sdk/modules/base.py
• sdk/python/ragflow_sdk/modules/chat.py
• sdk/python/ragflow_sdk/modules/chunk.py
• sdk/python/ragflow_sdk/modules/dataset.py
• sdk/python/ragflow_sdk/modules/document.py
• sdk/python/ragflow_sdk/modules/session.py
• sdk/python/ragflow_sdk/ragflow.py
• test/testcases/test_web_api/test_system_app/test_apps_init_unit.py
• web/src/components/document-preview/md/index.tsx
• web/src/constants/markdown-remark-plugins.ts

Overview

The Backend API System provides programmatic access to RAGFlow's functionality through RESTful HTTP endpoints and a Python SDK. It enables developers to manage datasets, documents, chat assistants, agents, and execute RAG workflows without using the web interface. The API follows REST conventions and includes OpenAI-compatible endpoints for seamless integration with existing LLM tooling.

The system is built on a hybrid architecture. The Python-side utilizes the Quart framework api/apps/__init__.py61 providing an asynchronous implementation of the Flask API for handling long-lived SSE connections and concurrent background tasks. Simultaneously, a high-performance Go-based server layer handles core internal services, search operations, and ingestion logic. The Go router in internal/router/router.go manages a wide array of handlers including AuthHandler, UserHandler, DatasetsHandler, AgentHandler, and ChatChannelHandler internal/router/router.go26-58

For information about the visual workflow system and canvas-based agent orchestration, see Agent and Workflow System. For details on the web frontend that consumes these APIs, see Frontend Application.

Scope and Purpose

This page covers:

• Overall API architecture and the hybrid Python/Go routing design.
• Request/response formats and error handling.
• Endpoint organization across functional domains.
• Python SDK structure and design.
• OpenAI compatibility layer.

Detailed coverage of specific endpoint categories is provided in child pages:

• API Architecture and SDK — Document the API design, request/response patterns, SDK structure, and OpenAPI compatibility.
• Authentication and Authorization — Explain the authentication flow (JWT, OAuth, API tokens), the @login_required decorator, and current_user proxy.
• User and Tenant Management — Document user registration, OAuth integration, password reset flow with OTP, and multi-tenant architecture.
• Dataset and Knowledge Base APIs — Detail the dataset CRUD operations, parser configuration, metadata settings, and knowledge base management endpoints.
• Document and File Management APIs — Explain document upload, parsing triggers, file hierarchy, metadata updates, and the relationship between files and documents.
• Chat and Conversation APIs — Document the chat completion endpoint, session management, streaming responses, and the RAG retrieval flow.
• Agent and Memory APIs — Detail the agent/canvas management endpoints and memory system APIs for persistent agent state.
• System Status and Health Monitoring — Explain the health check endpoints, component status reporting, task executor heartbeat monitoring, and the MCP server integration.
• Chat Channel Integrations — Document the chat channel runtime system that integrates RAGFlow with external messaging platforms.

API Layer Architecture

The Backend API is structured to separate routing logic from business logic. RAGFlow employs a dual-server strategy where Go handles system-critical and high-throughput tasks, while Python manages complex RAG logic and LLM integrations. The Go server marks its responses with an X-API-Source: go header for debugging internal/router/router.go135

Title: Hybrid API Layer Architecture

Sources: internal/router/router.go25-58 internal/router/router.go135 api/apps/__init__.py61-65

Request Processing Flow

Every API request follows a standardized processing pipeline to ensure security and consistency.

1. Authentication: API requests use authentication decorators (Python) or middleware (Go). The Python layer supports AUTH_JWT, AUTH_API, and AUTH_BETA types api/apps/__init__.py94-96
2. Validation: Python endpoints use validate_and_parse_json_request which employs Pydantic models for schema validation, ensuring correct Content-Type and JSON syntax api/utils/validation_utils.py36-112 Query arguments are validated via validate_and_parse_request_args api/utils/validation_utils.py115-162
3. Business Logic: Handlers invoke specific service modules. The Go router maps requests to specific handlers like documentHandler or datasetsHandler internal/router/router.go30-31
4. Response Formatting: Success results are returned via standardized envelopes. Python utilizes _safe_jsonify and custom encoders to handle model serialization api/utils/api_utils.py55-58 api/utils/api_utils.py96-118

Sources: api/apps/__init__.py94-110 api/utils/validation_utils.py36-162 internal/router/router.go30-31 api/utils/api_utils.py55-118

Standard Response and Error Codes

RAGFlow uses a uniform response envelope. Success is indicated by HTTP 200 and a specific code in the JSON body. Error handling is standardized across both Go and Python layers.

Code	Message	Description
200	(Success)	Request processed successfully.
400	Bad Request	Invalid request parameters docs/references/http_api_reference.md20
401	Unauthorized	Invalid or missing authentication credentials docs/references/http_api_reference.md21
403	Forbidden	Access denied to the specific resource docs/references/http_api_reference.md22
1001	Invalid Chunk ID	The specified chunk identifier does not exist docs/references/http_api_reference.md25
1002	Chunk Update Failed	Failure during the manual editing of a chunk docs/references/http_api_reference.md26

Sources: docs/references/http_api_reference.md14-26 api/utils/api_utils.py121-154

Python SDK and Object Mapping

The ragflow-sdk provides an object-oriented interface that mirrors the REST API hierarchy, bridging Natural Language space to code entities.

Title: SDK to Backend Mapping

Key Features:

• Resource Management: High-level methods like create_dataset allow defining the chunk_method (e.g., naive, qa, laws) and complex parser_config docs/references/python_api_reference.md124-208
• Authentication: The SDK requires a ragflow-api-key for authentication docs/references/python_api_reference.md10
• Integration: The SDK can be installed via pip install ragflow-sdk docs/references/python_api_reference.md16

Sources: docs/references/python_api_reference.md8-208 sdk/python/ragflow_sdk/ragflow.py1-50

OpenAI Compatibility Layer

RAGFlow implements a compatibility layer to allow standard LLM clients to interact with RAGFlow "Chats" and "Agents".

• Endpoint Paths:
  • Chats: /api/v1/openai/{chat_id}/chat/completions docs/references/http_api_reference.md63
• Extended Parameters: Supports extra_body for RAG-specific features like reference (to return citations) and metadata_condition for complex retrieval filtering docs/references/http_api_reference.md97-113
• Backward Compatibility: RAGFlow maintains a backward compatibility layer for deprecated REST API paths (e.g., mapping /api/v1/file/upload to /api/v1/files) docs/references/http_api_reference.md30-53

Sources: docs/references/http_api_reference.md30-113 docs/references/python_api_reference.md39-114

System Health and Monitoring

The API system includes comprehensive health and status monitoring endpoints.

• Health Check: /api/v1/system/healthz provides the operational status of the system docs/references/http_api_reference.md41 The Go router exposes this at the same path internal/router/router.go163
• CLI Tooling: RAGFlow provides a Go-based CLI in internal/cli/ that interacts with these APIs for administrative tasks, including APIShowVersionCommand and ListConfigs internal/cli/user_command.go42-115
• MCP Integration: The system adds MCP tools like ragflow_list_datasets and ragflow_list_chats to the RAGFlow MCP server docs/release_notes.md41
• Chat Channels: Integrations for WhatsApp, DingTalk, and WeCom are managed through dedicated handlers like chatChannelHandler internal/router/router.go37 and documented in release notes docs/release_notes.md62-65

Sources: docs/references/http_api_reference.md41 internal/router/router.go163 internal/cli/user_command.go42-115 docs/release_notes.md41-65