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