Dify Service API Compatibility

For provider/application setup through the website, start with the administrator guide. For end-user behavior, see the user guide. This document describes integration contracts rather than a complete upstream feature list.

AgentifUI uses Dify’s application-scoped Service API, normally served under /v1. Compatibility work targets the Dify 1.19.0 tagged implementation; this does not mean every newer Dify feature is available in the AgentifUI interface. Keep the Dify API URL and application API keys in private deployment configuration. No Dify server upgrade is required. The shared generation governance gate requires the AgentifUI migrations described in Agent Governance; deploy its API and browser client together.

Generation requests now require x-agentifui-submission-id (a UUID). Existing cached browser pages must be refreshed after this coordinated upgrade. The Dify service helpers create a new UUID per generation; their final optional { submissionId } argument lets an explicit replay reuse the original UUID. Do not automatically resend a generation after a network interruption, and do not reuse an ID for a new question. Existing legacy paths retain upstream user binding and browser-side conversation/message saving. Explicitly negotiated AG-UI chatbot conversations instead use trusted server bindings and server-side saving; see the compatibility reference and AG-UI integration. Never enable both persistence writers for the same conversation.

Implementation Boundaries

The authenticated proxy lives in apps/api/src/routes/dify-proxy.ts and apps/api/src/routes/dify-proxy-route/. The legacy Next.js Dify route is a disabled compatibility stub; add proxy behavior in Fastify rather than restoring the old handler.
Keep client operations, streaming handling, and result processing in the relevant modules under lib/services/dify/. Browser requests use the authenticated AgentifUI proxy and never carry an upstream application API key.
Define upstream request, response, and event types under lib/services/dify/types/, with exports through lib/services/dify/types.ts. Reuse existing error and stream-handling patterns.
When adding an operation, verify its route and behavior against the supported Dify release, cover the affected app types, and update this compatibility document. Parsing a new event does not by itself implement the corresponding UI feature.

Existing Interfaces

Application or operation	Service API path
Chatbot, legacy Agent and Chatflow messages	`POST /chat-messages`
Text generation	`POST /completion-messages`
Workflow execution	`POST /workflows/run`
Workflow run detail	`GET /workflows/run/{run_id}`
Stop Workflow	`POST /workflows/tasks/{task_id}/stop`
App information and configuration	`GET /info`, `/parameters`, `/meta`, `/site`
File upload and download	`POST /files/upload`, `GET /files/{file_id}/preview`

Conversation, message, feedback and suggested-question requests retain their existing Service API endpoints. Workflow apps keep shared app/file/audio routes outside the /workflows prefix. Only recognized legacy Workflow shorthand paths are expanded; unsupported Workflow routes are rejected rather than guessed.

The Dify 1.19.0 release notes also discuss run-based stop operations under /openapi/v1. Those belong to a different API surface and do not replace the Service API task-based stop endpoint used here. Console APIs, workspace Skills, package imports and tracing administration are not part of this integration.

Streaming And Results

Chat, Completion and Workflow share a buffered SSE parser with UTF-8, BOM, LF/CR/CRLF, keepalive and final-frame handling. Unknown JSON event types remain parseable; that alone does not give them UI support.
Message persistence prefers message_id, with the legacy id fallback. Completion token usage accepts metadata.usage and the legacy top-level field.
Workflow detail inputs can be JSON values, not only serialized strings. Workflow logs have a nested workflow_run record, which can be null.
partial-succeeded is a finished upstream result, not a fully successful run. Outputs and the original status are retained; the existing local history marks it failed with an explanation instead of claiming complete success. Stopped runs retain the local stopped status.
Human Input pauses are detected and reported explicitly. Human Input forms, submitting answers and resuming paused runs are not implemented. Do not use HITL-dependent apps here until that separate feature is supported. The client reports an unsupported-operation error; the upstream run remains paused, not stopped or resumed by that error.
New Agent variants, separated reasoning streams, Workflow text-delta rendering and nested tracing are not automatically enabled by a Dify backend upgrade.

Files And Limits

Successful file-preview responses are forwarded without converting file bytes to text, including document/archive MIME types. HTML, SVG and XML responses keep forced-download, sandbox and nosniff protections.

DIFY_UPLOAD_MAX_BYTES sets the total buffered multipart request limit for POST /files/upload and POST /audio-to-text. The default is 16777216 bytes (16 MiB), leaving room for multipart overhead around a 15 MiB file. It must be a decimal safe integer of at least 1024; an invalid configured value prevents API startup. Other API routes keep their original body limits. Dify and reverse proxies enforce their own limits independently; larger audio/file requirements need an appropriately bounded setting at each layer. Uploads are buffered, so account for concurrency and available memory before increasing the limit.

Identity Boundary

Browsers call AgentifUI’s authenticated proxy, not Dify with exposed API keys. The proxy replaces user with the current application user in JSON, multipart and query data. Generation inputs under agentifui_user_ are server-controlled, including version-specific Workflow execution paths.

An upstream user parameter is not a universal resource-ownership check: some Dify operations are application-scoped. Workflow logs, Workflow run details, Workflow task stopping and proxied file previews currently require an AgentifUI administrator. Other authenticated roles receive HTTP 403 before an upstream request is sent. This also applies to the shortened Workflow route aliases. Normal chat requests and user-scoped chat stop operations retain their existing behavior. Workflow execution itself is still available to authorized users, but the restricted follow-up operations are not available to ordinary users.

This is an interim restriction, not full per-resource ownership enforcement. Restoring these operations for ordinary users requires trusted server-observed ownership records; client-supplied run/task/file identifiers or locally saved execution records are not sufficient proof. Existing signed file URLs remain subject to their own authorization and expiration rules.

Authenticated proxy requests resolve the exact requested application under the current user’s permissions. An unavailable or unauthorized application does not fall back to another application’s default configuration.

References

The documentation site may describe a newer version; use the fixed release tag when checking version-specific behavior. Validate the app types actually used by your installation before rollout, rather than assuming a passing chat test also verifies Workflow, Completion, audio or files.