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 1.

Registered Blueprints and URL Prefixes#

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

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

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 4. 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 5.

inner_api Blueprint#

The inner_api blueprint at /inner/api is the internal/enterprise control plane 6. It is intentionally excluded from CORS and license-gating 7, 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 8
• 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 9. The __all__ export in __init__.py lists every sub-module to prevent linters from flagging the side-effect imports 10.

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 11.

Key Entry Points#