dify/api/AGENTS.md

API Agent Guide

Read surrounding module, class, and function docstrings plus non-obvious comments before changing backend behavior. They are local contracts; update them only when their owned behavior changes, and keep them aligned with the current code.

Commands

Run backend checks from the repository root:

• Format and lint: make lint
• Type check: make type-check
• Unit tests: make test
• Targeted tests: make test TARGET_TESTS=./api/tests/<path>

Run direct Python commands through uv run --project api. Docker-backed integration suites are normally CI-owned. Do not start long-running services as part of routine agent work.

Follow the backend developer guide's test layout and naming requirements when adding or moving unit tests.

Architecture And Boundaries

• Treat api/core/ as a migration-only area: do not add files or move implementations into it. Move responsibilities out; limit changes to existing callers to the adaptations needed for that migration.
• Keep transport parsing and serialization in controllers, orchestration in services, and domain policy in its domain owner. New or extracted implementations must stay outside core/. Keep libs/ business-agnostic and reuse existing owners before adding abstractions.
• Before changing controller schemas, generated API contracts, or SystemFeatureModel, read controllers/API_SCHEMA_GUIDE.md. Treat /system-features as a minimal unauthenticated bootstrap allowlist, not a general configuration registry.
• Scope tenant-owned reads and writes by the complete owner chain, and propagate tenant_id across every affected layer. Reconstruct trusted internal references from validated database state after payload or async boundaries.
• Keep write transactions explicit and bounded. Do not perform external I/O inside an open transaction unless a documented consistency contract requires it.
• Read configuration through configs.dify_config, access storage through extensions.ext_storage.storage, and route outbound HTTP through the existing SSRF-safe owner in core.helper.ssrf_proxy.
• Use Pydantic v2 for request and response models. Reuse domain-specific exceptions and translate them at the controller boundary.
• Use existing Celery task and queue owners for asynchronous work; do not route unrelated jobs through workflow-specific services.
• Celery tasks that may be retried or redelivered must keep side effects idempotent and log affected resource identifiers.

New SQLAlchemy models must inherit from models.base.TypeBase. The ast-grep guard rejects new Base subclasses. Existing Base subclasses may be edited or migrated without adding more legacy inheritance. make lint checks local changes, and CI checks the PR against its target revision.

Typing Best Practises

• Treat nullable types (T | None) strictly as union types; document the semantic meaning for each branch.
• Treat default parameter values as introducing distinct function overloads; verify that every added default has demonstrable practical utility and avoids masking unsafe runtime states.