Dify OpenAPI (/openapi/v1)#

/openapi/v1 is Dify's user-scoped, bearer-authenticated programmatic API — the primary interface for the difyctl CLI and external integrations. It is described internally as "User-scoped programmatic API (bearer auth)" and is distinct from the cookie-authenticated /console/api surface used by the web UI 1.

The blueprint is registered at api/controllers/openapi/__init__.py with two pieces of middleware attached at startup:

• Anti-framing security (via attach_anti_framing)
• Version gate (via attach_version_gate) — rejects outdated difyctl clients before they reach any endpoint 2

API Design: Resource-Oriented Paths and AIP-136#

As of Dify 1.16.0 (PR #38367), all /openapi/v1 paths follow REST resource-oriented conventions aligned with AIP-136 2. Verb-suffix paths were replaced with standard GET resource reads and AIP-136 :action custom methods:

This was a hard cutover — no dual-mount or /v2 strategy — because difyctl and the server ship in lockstep 2.

Endpoint Surface#

Each domain is implemented in its own module under api/controllers/openapi/ 3:

Workspace Collaboration and Team Member Management#

The workspace endpoints in workspaces.py are the bearer-authenticated counterpart to the console's cookie-auth workspace APIs. Key behavior:

• GET /workspaces — lists workspaces for the authenticated account; external SSO tokens (no account_id) return an empty list 14.
• POST /workspaces/{id}:switch — server-side workspace switch used by difyctl use workspace <id>. The CLI must abort on failure to prevent hosts.yml diverging from server state 15.
• GET /workspaces/{id}/members — paginated member list; accessible to any member 16.
• POST /workspaces/{id}/members — invite by email; requires owner or admin role, enforces billing/license limits, returns an activation URL 17.
• DELETE /workspaces/{id}/members/{mid} — remove a member; self-removal and owner-removal rejected as 400 18.
• PATCH /workspaces/{id}/members/{mid} — update role; owner role unassignable here (ownership transfer is console-only) 19.

All write endpoints require WORKSPACE_WRITE scope and account subject — external SSO subjects have no write access 20.

Authentication and Subject Model#

All endpoints except /_health and /_version use bearer token authentication. Routes declare their requirements via the @endpoint decorator, which combines authentication, request validation, and response serialization under a subject-based routing system implemented in api/controllers/openapi/auth/ 3.

Two subjects exist, each with its own token prefix and fixed scopes:

• dfoa_ — Account subject (SubjectType.ACCOUNT): Full access including workspace write and app build/management operations. Carries Scope.FULL.
• dfoe_ — External SSO subject (SubjectType.EXTERNAL_SSO): Read-only access to permitted apps via /permitted-external-apps; no workspace membership and no write access. Carries Scope.APPS_RUN and Scope.APPS_READ_PERMITTED_EXTERNAL 14.

Scopes are bound to the subject type at mint time and enforced at resolve time via libs/oauth_bearer.py.

PR #37641 formalized this split into two CLI "faces" 21:

• app face (usage): describe, run, get, resume — dual-subject capable via an AppReader abstraction that dispatches to AppsClient (account) or PermittedExternalAppsClient (external SSO) depending on the token.
• studio-app face (build): export, import — account-only.

The AppReader dispatch is implemented in cli/src/api/app-reader.ts 21.

Version Gating (difyctl ↔ Server Compatibility)#

Because the API surface undergoes breaking changes on hard cutovers, a symmetric version gate is enforced on both sides 2:

Server-side (api/controllers/openapi/_version_gate.py):

• Attached as a before_app_request hook on the /openapi/v1 blueprint.
• Rejects difyctl clients older than 0.2.0-alpha (paired with Dify 1.16.0) with HTTP 426 Upgrade Required.
• Fails open for non-difyctl or unparseable User-Agent headers — never blocks non-CLI traffic.
• Allowlists /_version and /_health so outdated clients can discover the required upgrade.

Client-side (cli/src/version/enforce.ts):

• Probes GET /_version (unauthenticated, 2-second timeout) before executing any command.
• Rejects servers older than 1.16.0 with exit code 6 (ErrorCode.VersionSkew); issues a soft nudge for too-new servers.
• Caches the compatibility verdict per-host for 1 hour (positive-only cache; fresh servers clear it immediately).
• Fails open on probe timeout or network errors.

Together these gates convert confusing 404 errors (calling a removed path) into explicit upgrade messages 2.

Generated Contracts and Type Safety#

The CLI uses generated oRPC/Zod contracts that are committed to the repository under packages/contracts/generated/api/openapi/ 2. The codegen pipeline produces:

• orpc.gen.ts — typed oRPC client with nested method paths (e.g., apps.byAppId.run rather than apps.appIdRun)
• types.gen.ts — TypeScript types derived from the OpenAPI schema
• zod.gen.ts — Zod validators for runtime request/response validation

The backend contract is defined via the @endpoint decorator in _contract.py, which composes @accepts (request validation), @returns (response serialization), and subject-based auth into a single declaration. Response/query models are backed by _models.py 22. Generated Markdown documentation lives at api/openapi/markdown/openapi-openapi.md 2. Any route change requires regenerating these contracts.