Dosu LogoDosu Logo
Ask
Join our Discord
Organization avatar
difyPublic
Dify
Documentsdify
Flask Blueprint and Route Registration
Flask Blueprint and Route Registration
Type
Topic
Status
Published
Created
Aug 2, 2026
Updated
Aug 19, 2026
Created by
Dosu Bot
Updated by
Dosu Bot

Flask Blueprint and Route Registration#

All Flask blueprints in Dify's API layer are registered in a single place: ext_blueprints.init_app(). This function is called during app startup by initialize_extensions(), which runs the full extension chain in a fixed order — ext_blueprints runs after database, storage, and other infrastructure extensions are ready .

Registered Blueprints and URL Prefixes#

Eight blueprints are registered, each with a distinct URL prefix:

BlueprintURL PrefixCORS
service_api/v1Yes (Bearer auth)
openapi/openapi/v1Yes (configurable origins, credentials)
web/apiYes (split: embed vs. authenticated)
console/console/apiYes (credentials)
files/filesYes
inner_api/inner/apiNo
mcp/mcpNo
trigger/triggersYes

openapi_bp is only registered when dify_config.OPENAPI_ENABLED is set . inner_api_bp and mcp_bp are registered without CORS .

CORS is applied via the idempotent helper _apply_cors_once(), which guards against double-application across multiple app instances using a _dify_cors_applied flag on the blueprint object.

Module Import Timing#

Controller blueprint imports happen inside init_app(), not at module level . This late-binding pattern prevents circular imports: route modules depend on services and models that aren't fully initialized when ext_blueprints.py is first parsed.

ExternalApi and Namespace Pattern#

Most blueprints wrap their Flask Blueprint with ExternalApi — a custom flask_restx.Api subclass from libs/external_api.py. ExternalApi adds standardized error handling, Bearer token authorization defaults, and Swagger UI configuration. It also overrides private flask-restx methods to scope 404 errors to the blueprint's prefix, preventing route enumeration.

Route classes then use a flask_restx.Namespace for grouping — e.g., inner_api_ns = Namespace("inner_api", path="/") registered against the ExternalApi instance .

inner_api Blueprint#

The inner_api blueprint at /inner/api is the internal/enterprise control plane . It is intentionally excluded from CORS and license-gating , since blocking it would break workflow execution and license recovery. Sub-modules imported in controllers/inner_api/__init__.py cover:

  • Plugin invocations (plugin/plugin.py) — backwards-invocation of LLM, tools, apps, encryption, summary, file upload/download
  • Agent config (plugin/agent_config.py) — Agent Soul config versioning endpoints
  • Knowledge retrieval (knowledge/retrieval.py)
  • App DSL (app/dsl.py)
  • Mail (mail.py)
  • Runtime credentials (runtime_credentials.py)
  • Workspace (workspace/workspace.py)

Routes within inner_api are decorated with @plugin_inner_api_only for authentication . The __all__ export in __init__.py lists every sub-module to prevent linters from flagging the side-effect imports .

License Gating#

app_factory.py registers a before_request hook that checks the enterprise license for most surfaces. /inner/api, /files, and /health are explicitly excluded from license gating to avoid blocking workflow execution or license recovery .

Key Entry Points#

FilePurpose
api/extensions/ext_blueprints.pyCentral registration, CORS config
api/app_factory.pyExtension init order, license-gating hook
api/controllers/inner_api/__init__.pyinner_api blueprint + sub-module imports
api/libs/external_api.pyExternalApi wrapper (error handling, Swagger)
Documents
Account Activity Tracking
Agent API Routes
Agent App Architecture
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent App Event Architecture
Agent App Input Variables
Agent Cost and Usage Tracking
Agent File Handling
Agent File Upload Configuration
Agent Icon Data Model
Agent Log Event Pipeline
Agent Message History
Agent Model Settings
Agent Node Data Models
Agent Response Schema
Agent Runtime
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Runtime Backend Initialization
Agent Runtime Layer Provider Registration
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Sandbox SSRF Allowlisting
Agent Shell Layer
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Strategy Plugin Architecture
Agent V2 Architecture
Agent V2 Configure Interface
Agent V2 Feature Flags
Agent V2 File and Vision Handling
Agent V2 Variable System
API Documentation Pipeline
App Mode Configuration
App Publishing and Embedding
Audio to Text API
Auth Route Architecture
Automatic Rule Generation
Avatar Management
Branding Customization
Browser Tab and State Management
Builtin Tool Provider Credentials
Celery Task Resilience
Chat Action Bar Mobile Visibility
Chat Avatar Rendering
Chatbot Conversation State Recovery
Chatbot Widget Embedding
Code Node Execution
Code Node Output Validation
Collaborative Workflow Editing
Console API DELETE Request Handling
Console Authentication
Conversation Auto-Naming
Conversation Deep-Linking
Credential Encryption and Secret Management
CSV Data Ingestion
Custom Tool Authentication
Custom Tool HTTP Timeout Configuration
Custom Tool OpenAPI Integration
Data Export
Database Migration System
Database Session Management
Database Transaction Isolation
Dataset Batch Import
Dataset Deletion
Dataset Permission Model
Dataset Segmentation Configuration
Dependency Injection and Testability
Dify Agent Server 模块分析 (Commit 55f95dbc)
Dify Agent Monorepo Structure
Dify Agent Server 模块分析 (Commit 55f95dbc)
Dify Cloud Billing
Dify OpenAPI
difyctl CLI
Docker Container Security
Docker Deployment and Upgrades
Docker Frontend Configuration
Docker Image Publishing
Docker Networking
Docker Storage and Permissions
Document Indexing Operations
Edition-Based Feature Gating
Elasticsearch Integration
Embedding Cache Integrity
Excel Extractor
External Knowledge Integration
Extractor Encoding Fallback
File Access Control
File Array Handling
File Download Architecture
File Download Security
File Storage Synchronization
File Upload and Download Integrity
File Upload Configuration
File Upload Processing
File URL Resolution
Flask Application Architecture
Flask Blueprint and Route Registration
Graph Streaming Infrastructure
Home Directory Management
HTTP Request Node
HTTP Request Node Key-Value Editor
HTTP Request Node Size Constraints
httpx and Gevent Compatibility
Human Input Node
Hybrid Search
Icon URL Resolution
Iframe Embedding Security
Internationalization and Locale Management
Jina Reranker Integration
JSON-in-Markdown Parsing
JWT Authentication
Keyboard Shortcut Management
Keyword Moderation
Knowledge Base API
Knowledge Base Document Processing
Knowledge Base Metadata Filtering
Knowledge Base Summarization Pipeline
Langfuse Integration
Lexical Editor Integration
LLM Provider Message Validation
LLM Structured Output
Local Development Configuration
Local Embedding Model Deployment
Log Filtering
Markdown Extractor Heading Parsing
Markdown Rendering
MCP Client Transport and Connectivity
MCP Protocol Integration for Dify Workflows
MCP OAuth Integration
MCP Protocol Integration
MCP Protocol Integration for Dify Workflows
MCP Provider Architecture
MCP Tool Content Processing
MCP Tool Integration
MCP Protocol Integration for Dify Workflows
MCP Tool Parameter Binding
MCP Tool Provider Management
Messaging Platform Integration
Milvus Integration
Model Provider Error Handling
Monaco Editor Integration
Multi-Tenant Context Propagation
Multimodal Knowledge Base Support
Next.js Routing and Redirects
Next.js SSR Authentication
Nginx Reverse Proxy Configuration
Notion Extractor Table Parsing
NumPy CPU Compatibility
OAuth Login Flow
Observability and Tracing
OpenAI-Compatible Server Integration
OpenAPI Spec Accuracy
OpenDAL Storage Backend
Ops Trace Data Models
Oracle Database Connectivity
Parallel Workflow Execution
Parent-Child Retrieval Architecture
Plugin API Key Configuration
Plugin Architecture
Plugin Credential Management
Plugin Daemon Architecture
Plugin Daemon Communication
Plugin Daemon Model Parameter Handling
Plugin Daemon Port Configuration
Plugin Database Integrity
Plugin Error Handling
Plugin File Handling
Plugin Lifecycle Management
Plugin Marketplace Connectivity
Plugin Model Caching
Plugin Permissions
Plugin Storage Configuration
Plugin System Timeouts
Plugin Taxonomy and Validation
Plugin Trigger OAuth Refresh
Private Address Detection
Provider Model & Credential Management
Pyrefly Type Checker
RAG Web Crawling Providers
Rate Limiting and Concurrency Control
RBAC Initialization
RBAC Permission Key Lookup
Reasoning Model Integration
Reasoning Tag Filtering
Redis Connection Management
Redis Streaming Resilience
Release Breaking Changes
Remote File Handling and Validation
Retrieval Filtering and Scoring
RTL Locale Support
Sandbox Code Execution
Sandbox Network Isolation
Sandbox Seccomp Security
Segment Update and Attachment Lifecycle
Server Deployment Configuration
Service API Error Handling
Service API Pagination
Shell Provider Lifecycle
Snippet Variable Handling
SQLite Test Infrastructure
SSE Stream Lifecycle
SSE Stream Terminal Event Delivery
SSR Data Fetching
SSRF Proxy
Suggested Questions After Answer
Summary Index
Tenant-Isolated Document Indexing Queue
Test Doubles and In-Memory Repositories
Dify Agent Server 模块分析 (Commit 55f95dbc)
TiDB Vector Full-Text Search
Time Tools
Timestamp Management
Tool File URL Signing
Tool Node Input Validation
Tool Provider Authorization
Trace Task Pipeline
User and Tenant Context Propagation
Dify Agent Server 模块分析 (Commit 55f95dbc)
User Roles and Permissions
Variable Pool Falsy Value Handling
Variable Resolution and Template Substitution
Vector Database Plugin Architecture
Vector Store Integration
Weaviate Vector Store
Web Container Docker Configuration
Webhook Trigger System
WebSocket Service Architecture
Word Document Extraction
Workflow Agent Node Configuration
Workflow Agent Retry Configuration
Workflow and Agent Composition
Dify Agent Server 模块分析 (Commit 55f95dbc)
Workflow Conditional Branching
Workflow Container Nodes
Workflow Conversation State Management
Workflow Draft Synchronization
Workflow Execution Dispatch
Workflow Execution Persistence
Workflow Fail Branch Architecture
Workflow File Handling
Workflow Iteration Node Execution
Workflow LLM Node Configuration
Workflow Memory Management
Workflow Node Canvas Summary Rendering
Workflow Node Versioning
Workflow Pause-Resume State Management
Workflow Resume Architecture
Workflow Run State Management
Workflow Schedule Triggers
Workflow Test Run Execution
Workflow Timeout and Execution Limits
Workflow Tool Visibility and Access Control
Workflow Trigger Log Lifecycle
Workflow Variable Size Management