{
  "schemaVersion": "1.0",
  "title": "Dify connector",
  "description": "The Dify connector exposes configured Dify applications and workspace Knowledge APIs as governed AIP capabilities. Use it when AIP must invoke published apps, manage conversations or files, operate knowledge data, stream workflow events, or",
  "canonical": "https://getaip.org/docs/connectors/dify",
  "route": "/docs/connectors/dify",
  "source": "docs/connectors/dify/README.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "97be86e9efedf07ecf1783b03800f683f107fb04",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/connectors/dify.md",
    "txt": "/docs/download/connectors/dify.txt",
    "json": "/docs/download/connectors/dify.json",
    "pdf": "/docs/download/connectors/dify.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Dify connector\ndescription: >-\n  Decide whether the Dify connector fits an integration and understand its\n  application, Knowledge API, execution, and isolation boundaries\nkind: overview\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: dify\n---\n\n# Dify connector\n\nThe Dify connector exposes configured Dify applications and workspace\nKnowledge APIs as governed AIP capabilities. Use it when AIP must invoke\npublished apps, manage conversations or files, operate knowledge data, stream\nworkflow events, or cancel a retained Dify task without putting API keys in\nAction input.\n\nThe connector is not a generic pass-through. Its source pins provider routes,\ncredentials, request encoding, user placement, response transport, risk,\napproval, retry, and size limits.\n\n## Decide whether it fits\n\n| Requirement | Fit |\n|---|---|\n| Invoke a configured workflow, completion, chat, advanced-chat, agent-chat, or agent app | Yes, through one app invocation alias |\n| Use frozen application Service API operations | Yes, when the operation supports the configured app mode |\n| Manage workspace knowledge data | Yes, through a separate Knowledge API credential |\n| Stream app or workflow output | Yes, for the app alias and two catalogue SSE routes |\n| Cancel an active app execution | Yes, after task identity is known or supplied safely |\n| Retry provider mutations automatically | No |\n| Use AIP transactions, reconciliation, or rollback | No |\n| Select a Dify URL or API key from Action input | No |\n| Prove compatibility with any Dify deployment | No; qualification belongs to an exact artifact and upstream boundary |\n\nChoose another integration boundary when arbitrary provider routes, dynamic\ncredentials from callers, or automatic rollback are required.\n\n## Understand the deployment boundary\n\nOne standalone `aip-host-dify` process loads deployment-owned descriptors and\nowner-only key files. It constructs a manifest, receives signed routed Actions,\ncalls one configured Dify origin, and publishes signed AIP results.\n\nThe base URL, app set, knowledge set, credentials, connector identity,\nartifact, manifest, tenant, and registry assignment are outside Action input.\nThe host uses runtime profile state to retain the Action-to-task mapping needed\nfor cancellation across process replacement within one logical instance.\n\nThis topology separates four authorities:\n\n| Authority | Owns |\n|---|---|\n| AIP tenant and policy | Discovery, approval, routing, retry budget, and Action lifecycle |\n| Dify host instance | Static descriptors, bounded keys, task correlation, and provider transport |\n| Dify application | Published app behavior, conversations, messages, files, and remote tasks |\n| Dify workspace | Knowledge datasets, documents, chunks, metadata, models, and pipelines |\n\n## Keep credential domains separate\n\nApplication Service API keys and workspace Knowledge API keys are different\ncredential classes.\n\n| Credential | Capability prefix | Health probe | Scope |\n|---|---|---|---|\n| Per-app API key | `cap:dify:<app_id>` | `GET /v1/parameters` | One configured published application |\n| Knowledge API key | `cap:dify:knowledge:<credential_id>` | `GET /v1/datasets?limit=1` | One configured workspace knowledge boundary |\n\nEvery app should use its own key file. A legacy global app-key file is accepted\nonly when all listed applications intentionally share that key. Knowledge\ncredentials always name their own files.\n\nNo capability advertises frozen connector credential-handle routing at this\nrevision. Isolate hosts and key files by tenant and intended provider scope.\n\n## Choose an app mode deliberately\n\n| Configured mode | Invocation route | Approval on the app alias |\n|---|---|---|\n| `workflow` | `POST /v1/workflows/run` | Required |\n| `completion` | `POST /v1/completion-messages` | Not required by the connector contract |\n| `chat` | `POST /v1/chat-messages` | Not required by the connector contract |\n| `advanced-chat` | `POST /v1/chat-messages` | Required |\n| `agent-chat` | `POST /v1/chat-messages` | Required |\n| `agent` | `POST /v1/chat-messages` | Required |\n\nThe mode also controls which app-scoped catalogue operations are discoverable.\nAn unsupported mode fails connector construction instead of falling back to a\ndifferent provider family.\n\nPlain chat and completion aliases still perform external model work and require\na tenant-scoped idempotency key. The absence of connector-required approval is\nnot a claim that every deployment should authorize them without policy.\n\n## Read capability IDs by domain\n\nThe manifest is configuration-dependent:\n\n| Shape | Meaning | Example |\n|---|---|---|\n| `cap:dify:<app_id>` | Invoke the configured app in its declared mode | `cap:dify:support-chat` |\n| `cap:dify:<app_id>:<operation>` | Use a supported app Service API operation | `cap:dify:support-chat:conversation.list` |\n| `cap:dify:knowledge:<credential_id>:<operation>` | Use a workspace Knowledge API operation | `cap:dify:knowledge:main:dataset.list` |\n\nThe frozen catalogue contains 79 provider operations: 33 app-scoped and 46\nKnowledge-scoped. One app publishes only the operations compatible with its\nmode, plus its invocation alias. Each Knowledge credential publishes all 46\nKnowledge operations.\n\nThere is no universal Dify manifest count. The controlled fixture happens to\npublish 74 capabilities from one `chat` app and one Knowledge credential. That\nnumber is not a general deployment invariant.\n\n## Apply the execution controls\n\n| Surface | Approval | Idempotency | Retry | Streaming | Cancellation |\n|---|---|---|---|---|---|\n| App invocation alias | Workflow and agent-family aliases | Required | Disabled | Yes | Yes |\n| Catalogue `GET` | No | Optional | Published safe | Only `workflow.event.stream` | Operation-specific |\n| Catalogue mutation | Required | Required | Disabled | `workflow.run_by_id` only | Operation-specific |\n| Knowledge mutation | Required | Required | Disabled | No | No |\n\nAll keys use tenant scope, input-hash revalidation, and a 24-hour contract TTL.\nThe connector does not publish transaction, reconciliation, or provider\nrollback support. Approval expires after 15 minutes where the connector\nrequires it.\n\nA transport category or temporary provider response never overrides these\ncontracts. Read durable Action and provider state before replacing an unsafe\noperation.\n\n## Preserve end-user isolation\n\nEvery app invocation requires a non-empty `user`. Operations that Dify binds to\nan end user also require it in the exact query, JSON, or multipart location\ndeclared by the catalogue. The connector rejects a conflicting `user` supplied\ninside another input partition.\n\nUse a stable, non-secret, tenant-scoped external value. Reusing one value across\nunrelated users can merge Dify conversation identity even when AIP Actions are\notherwise isolated.\n\nKnowledge operations do not inject an app end-user value. Their isolation comes\nfrom the selected workspace credential and AIP tenant route.\n\n## Treat streams and cancellation as durable work\n\nThe app alias requests Dify streaming mode and converts bounded SSE events to\nordered AIP chunks. It retains the remote task ID when Dify emits it, requires\nan explicit terminal event, and maps human-input events to `requires_human`.\n\nEach SSE frame is limited to 1 MiB, a stream to 10,000 events, and the complete\nresponse to the configured byte bound. Provider close without a terminal event\nis a failure, not successful completion.\n\nCancellation uses the retained app ID, task ID, and end-user value. Dropping an\nHTTP response before task identity is known is only cooperative cancellation;\nit does not prove that remote work stopped. Preserve the original Action and\nreconcile provider state before starting replacement work.\n\n## Respect request and response bounds\n\n| Boundary | Source limit |\n|---|---:|\n| JSON request body | 8 MiB |\n| Decoded upload file | 32 MiB |\n| Default response or complete stream | 8 MiB |\n| Maximum configurable response | 64 MiB |\n| SSE frame | 1 MiB |\n| SSE events per stream | 10,000 |\n\nBinary outputs are returned as bounded base64 with content type and byte size.\nThey are not written to a caller-selected filesystem path by the connector.\n\n## Know what is not guaranteed\n\nThe reviewed source does not establish:\n\n- live compatibility with every Dify edition or deployment;\n- automatic provider-state reconciliation after an uncertain mutation;\n- exactly-once external effects;\n- transactional grouping across app and Knowledge operations;\n- provider rollback or AIP compensation;\n- durable provider runs after Dify-side retention or restart;\n- production qualification for the current artifact.\n\nThe source pins upstream commit\n`f8d47616c15d0959f604f6a5e2e1d32d3108991b`. A pin records the reviewed\nmapping baseline; it is not an identity for a deployed Dify image.\n\n## Choose the next path\n\nFor an existing V1 reader, use the concise legacy page for the previous\nhigh-level contract. Read the AIP execution model before integrating Actions,\nuse the fleet guide for the standalone topology, and use the global error\nreference before implementing retries. The upstream-baseline page explains how\nprovider identities are bounded.\n\n## Related documentation\n\n- [Legacy Dify connector overview](../dify.md)\n- [How AIP works](../../getting-started/how-aip-works.md)\n- [Deploy the connector fleet](../../guides/deploy-connector-fleet.md)\n- [Errors and retry decisions](../../reference/errors.md)\n- [Connector upstream baselines](../upstream-baselines.md)\n",
    "text": "Dify connector\n\nThe Dify connector exposes configured Dify applications and workspace\nKnowledge APIs as governed AIP capabilities. Use it when AIP must invoke\npublished apps, manage conversations or files, operate knowledge data, stream\nworkflow events, or cancel a retained Dify task without putting API keys in\nAction input.\n\nThe connector is not a generic pass-through. Its source pins provider routes,\ncredentials, request encoding, user placement, response transport, risk,\napproval, retry, and size limits.\n\nDecide whether it fits\n\n| Requirement | Fit |\n\n| Invoke a configured workflow, completion, chat, advanced-chat, agent-chat, or agent app | Yes, through one app invocation alias |\n| Use frozen application Service API operations | Yes, when the operation supports the configured app mode |\n| Manage workspace knowledge data | Yes, through a separate Knowledge API credential |\n| Stream app or workflow output | Yes, for the app alias and two catalogue SSE routes |\n| Cancel an active app execution | Yes, after task identity is known or supplied safely |\n| Retry provider mutations automatically | No |\n| Use AIP transactions, reconciliation, or rollback | No |\n| Select a Dify URL or API key from Action input | No |\n| Prove compatibility with any Dify deployment | No; qualification belongs to an exact artifact and upstream boundary |\n\nChoose another integration boundary when arbitrary provider routes, dynamic\ncredentials from callers, or automatic rollback are required.\n\nUnderstand the deployment boundary\n\nOne standalone aip-host-dify process loads deployment-owned descriptors and\nowner-only key files. It constructs a manifest, receives signed routed Actions,\ncalls one configured Dify origin, and publishes signed AIP results.\n\nThe base URL, app set, knowledge set, credentials, connector identity,\nartifact, manifest, tenant, and registry assignment are outside Action input.\nThe host uses runtime profile state to retain the Action-to-task mapping needed\nfor cancellation across process replacement within one logical instance.\n\nThis topology separates four authorities:\n\n| Authority | Owns |\n\n| AIP tenant and policy | Discovery, approval, routing, retry budget, and Action lifecycle |\n| Dify host instance | Static descriptors, bounded keys, task correlation, and provider transport |\n| Dify application | Published app behavior, conversations, messages, files, and remote tasks |\n| Dify workspace | Knowledge datasets, documents, chunks, metadata, models, and pipelines |\n\nKeep credential domains separate\n\nApplication Service API keys and workspace Knowledge API keys are different\ncredential classes.\n\n| Credential | Capability prefix | Health probe | Scope |\n\n| Per-app API key | cap:dify: | GET /v1/parameters | One configured published application |\n| Knowledge API key | cap:dify:knowledge: | GET /v1/datasets?limit=1 | One configured workspace knowledge boundary |\n\nEvery app should use its own key file. A legacy global app-key file is accepted\nonly when all listed applications intentionally share that key. Knowledge\ncredentials always name their own files.\n\nNo capability advertises frozen connector credential-handle routing at this\nrevision. Isolate hosts and key files by tenant and intended provider scope.\n\nChoose an app mode deliberately\n\n| Configured mode | Invocation route | Approval on the app alias |\n\n| workflow | POST /v1/workflows/run | Required |\n| completion | POST /v1/completion-messages | Not required by the connector contract |\n| chat | POST /v1/chat-messages | Not required by the connector contract |\n| advanced-chat | POST /v1/chat-messages | Required |\n| agent-chat | POST /v1/chat-messages | Required |\n| agent | POST /v1/chat-messages | Required |\n\nThe mode also controls which app-scoped catalogue operations are discoverable.\nAn unsupported mode fails connector construction instead of falling back to a\ndifferent provider family.\n\nPlain chat and completion aliases still perform external model work and require\na tenant-scoped idempotency key. The absence of connector-required approval is\nnot a claim that every deployment should authorize them without policy.\n\nRead capability IDs by domain\n\nThe manifest is configuration-dependent:\n\n| Shape | Meaning | Example |\n\n| cap:dify: | Invoke the configured app in its declared mode | cap:dify:support-chat |\n| cap:dify:: | Use a supported app Service API operation | cap:dify:support-chat:conversation.list |\n| cap:dify:knowledge:: | Use a workspace Knowledge API operation | cap:dify:knowledge:main:dataset.list |\n\nThe frozen catalogue contains 79 provider operations: 33 app-scoped and 46\nKnowledge-scoped. One app publishes only the operations compatible with its\nmode, plus its invocation alias. Each Knowledge credential publishes all 46\nKnowledge operations.\n\nThere is no universal Dify manifest count. The controlled fixture happens to\npublish 74 capabilities from one chat app and one Knowledge credential. That\nnumber is not a general deployment invariant.\n\nApply the execution controls\n\n| Surface | Approval | Idempotency | Retry | Streaming | Cancellation |\n\n| App invocation alias | Workflow and agent-family aliases | Required | Disabled | Yes | Yes |\n| Catalogue GET | No | Optional | Published safe | Only workflow.event.stream | Operation-specific |\n| Catalogue mutation | Required | Required | Disabled | workflow.runbyid only | Operation-specific |\n| Knowledge mutation | Required | Required | Disabled | No | No |\n\nAll keys use tenant scope, input-hash revalidation, and a 24-hour contract TTL.\nThe connector does not publish transaction, reconciliation, or provider\nrollback support. Approval expires after 15 minutes where the connector\nrequires it.\n\nA transport category or temporary provider response never overrides these\ncontracts. Read durable Action and provider state before replacing an unsafe\noperation.\n\nPreserve end-user isolation\n\nEvery app invocation requires a non-empty user. Operations that Dify binds to\nan end user also require it in the exact query, JSON, or multipart location\ndeclared by the catalogue. The connector rejects a conflicting user supplied\ninside another input partition.\n\nUse a stable, non-secret, tenant-scoped external value. Reusing one value across\nunrelated users can merge Dify conversation identity even when AIP Actions are\notherwise isolated.\n\nKnowledge operations do not inject an app end-user value. Their isolation comes\nfrom the selected workspace credential and AIP tenant route.\n\nTreat streams and cancellation as durable work\n\nThe app alias requests Dify streaming mode and converts bounded SSE events to\nordered AIP chunks. It retains the remote task ID when Dify emits it, requires\nan explicit terminal event, and maps human-input events to requireshuman.\n\nEach SSE frame is limited to 1 MiB, a stream to 10,000 events, and the complete\nresponse to the configured byte bound. Provider close without a terminal event\nis a failure, not successful completion.\n\nCancellation uses the retained app ID, task ID, and end-user value. Dropping an\nHTTP response before task identity is known is only cooperative cancellation;\nit does not prove that remote work stopped. Preserve the original Action and\nreconcile provider state before starting replacement work.\n\nRespect request and response bounds\n\n| Boundary | Source limit |\n\n| JSON request body | 8 MiB |\n| Decoded upload file | 32 MiB |\n| Default response or complete stream | 8 MiB |\n| Maximum configurable response | 64 MiB |\n| SSE frame | 1 MiB |\n| SSE events per stream | 10,000 |\n\nBinary outputs are returned as bounded base64 with content type and byte size.\nThey are not written to a caller-selected filesystem path by the connector.\n\nKnow what is not guaranteed\n\nThe reviewed source does not establish:\n• live compatibility with every Dify edition or deployment;\n• automatic provider-state reconciliation after an uncertain mutation;\n• exactly-once external effects;\n• transactional grouping across app and Knowledge operations;\n• provider rollback or AIP compensation;\n• durable provider runs after Dify-side retention or restart;\n• production qualification for the current artifact.\n\nThe source pins upstream commit\nf8d47616c15d0959f604f6a5e2e1d32d3108991b. A pin records the reviewed\nmapping baseline; it is not an identity for a deployed Dify image.\n\nChoose the next path\n\nFor an existing V1 reader, use the concise legacy page for the previous\nhigh-level contract. Read the AIP execution model before integrating Actions,\nuse the fleet guide for the standalone topology, and use the global error\nreference before implementing retries. The upstream-baseline page explains how\nprovider identities are bounded.\n\nRelated documentation\n• Legacy Dify connector overview (../dify.md)\n• How AIP works (../../getting-started/how-aip-works.md)\n• Deploy the connector fleet (../../guides/deploy-connector-fleet.md)\n• Errors and retry decisions (../../reference/errors.md)\n• Connector upstream baselines (../upstream-baselines.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "f71f243a4080fed6797b77621192527890ef6e230925f2a548e76f2f193018bd"
  }
}