Dify Docs API Reference

Dify API Reference Documentation

OpenAPI specs for developers integrating Dify over REST. The code is the source of truth: when the spec disagrees with the code, the spec is wrong. Every detail you write must be traceable to a controller, model, or converter in the Dify codebase.

Not an entry point for writing — editing or creating specs runs under dify-docs-write; the procedures below implement its stages for the Service API specs.

Standalone audit (read-only, own trigger — no pipeline needed): auditing an existing spec is the app-type lens (procedure 1 below) plus Verifying Against Code applied systematically from references/audit-checklist.md.

Procedures by stage

All four are non-negotiable.

1. S1 — scope. Identify which app types the operation serves from the AppMode table in references/codebase-paths.md; every later check is filtered through that app-type lens (see App-Type Scoping). Read code at the ref pinned in S1 per writing-guides/index.md § "Syncing the Dify codebase safely"; never git checkout or git pull in a tree you have not confirmed is clean.
2. S5 — write or edit to the conventions. Apply references/spec-conventions.md for every element: summaries, operationId, descriptions, parameters, responses, error format, schemas, examples, tags, ordering. That file is the single source for formatting rules; do not reinvent them here. At S6, say that this pack modifies the stage: all three language specs are edited directly in the same pass (see Spec Structure); parity_check replaces a separate translate step.
3. S2/S7 — verify every detail against the code. Nothing ships unverified (see Verifying Against Code). Use references/codebase-paths.md to locate controllers, error definitions, and global handlers. Flag suspected code bugs; never silently document them (see Flagging Suspected Bugs).
4. S7 verifiers (after the pipeline's check chain): the independent subagent audit — required for new or substantially changed endpoints — and the example/schema consistency pass (both under S7 Verifiers). Substantially changed = any change to paths, methods, parameters, schema fields or constraints, status codes, error codes, example values, or availability; only pure prose rewording (summaries, descriptions, translations) is exempt.

Reader Persona

Backend developers integrating Dify apps or knowledge bases via REST. Strong coding ability; familiar with HTTP, authentication patterns, and JSON. Be precise about parameter types, required vs optional, error codes, and realistic examples. Do not explain what a REST API is.

Spec Structure

One spec per language — {en,zh,ja}/api-reference/openapi_service.json — is the spec of record. Edit it directly, in all three languages; parity_check enforces structural parity with en. (The five legacy per-app-type source specs and the merge pipeline that consolidated them are retired; recover from git history if needed.)

App types map to AppMode values. The one mapping table (docs names, spec groups, key endpoints, and the modes the Service API does not cover) is references/codebase-paths.md § "AppMode ↔ app-type names" — use it, never memory.

Shared endpoints (file upload, audio, feedback, app info, parameters, meta, site, end-user) appear once, with an availability line and per-mode notes in the description — a fix applies in one place, no propagation. tools/api-pipeline/memberships.json records which app types support each operation and drives the app-type overview pages plus check-coverage.

Every operation carries x-mint.href (/{lang}/api-reference/{en-tag-kebab}/{en-summary-kebab} — English slugs in all languages for language-switcher parity) and x-mint.metadata.title/sidebarTitle (the translated summary; without them the sidebar shows the English slug). Set all of these when adding an operation, and keep the tags arrays index-aligned across languages.

After structural edits (adding, removing, retitling, or reordering operations, or changing availability): update memberships.json and the app-type overview pages, then run wire, check-coverage, lint_specs, and parity_check per tools/api-pipeline/README.md. Description-only edits need the lints but not wire.

App-Type Scoping

The codebase shares controllers and Pydantic models across app modes; the merged spec documents each shared endpoint once, mode-aware. Filter every claim through the app types the operation actually serves (its availability line and memberships.json):

• Shared models: include only fields that have an effect in at least one supported mode; mark mode-specific fields in a mode note.
• Shared error handlers: include only errors triggerable in a supported mode.
• Internal-only fields (e.g., retriever_from): omit from the spec.

To judge relevance, check the controller's AppMode guard; when in doubt, trace through AppGenerateService.generate(). For example, workflow_id matters in chatflow mode, not chat.