{
  "schemaVersion": "1.0",
  "title": "Dify app metadata and files",
  "description": "Use this family to inspect a published application's contract, read one Dify end user, upload one bounded user file, or retrieve one bounded file preview. All seven operations are available for every supported app mode.",
  "canonical": "https://getaip.org/docs/connectors/dify/capabilities/app-metadata-and-files",
  "route": "/docs/connectors/dify/capabilities/app-metadata-and-files",
  "source": "docs/connectors/dify/capabilities/app-metadata-and-files.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/dify/capabilities/app-metadata-and-files.md",
    "txt": "/docs/download/connectors/dify/capabilities/app-metadata-and-files.txt",
    "json": "/docs/download/connectors/dify/capabilities/app-metadata-and-files.json",
    "pdf": "/docs/download/connectors/dify/capabilities/app-metadata-and-files.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Dify app metadata and files\ndescription: >-\n  Read app metadata and end users, upload one user file, or preview one\n  message file through the frozen Dify connector\nkind: capability-reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: dify\n---\n\n# Dify app metadata and files\n\nUse this family to inspect a published application's contract, read one Dify\nend user, upload one bounded user file, or retrieve one bounded file preview.\nAll seven operations are available for every supported app mode.\n\nChoose the configured app through the capability ID. The host supplies its\napp-specific Bearer key and fixed provider origin.\n\n## Choose an operation\n\n| Operation suffix | Method and route | Required input | Result | Policy |\n|---|---|---|---|---|\n| `parameters.get` | `GET /v1/parameters` | None | JSON | Low-risk retry-supported read |\n| `meta.get` | `GET /v1/meta` | None | JSON | Low-risk retry-supported read |\n| `info.get` | `GET /v1/info` | None | JSON | Low-risk retry-supported read |\n| `site.get` | `GET /v1/site` | None | JSON | Low-risk retry-supported read |\n| `file.upload` | `POST /v1/files/upload` | `user` and `file` | JSON | Medium mutation; approval and key required |\n| `file.preview` | `GET /v1/files/{file_id}/preview` | `file_id` and `user` | Binary | Low-risk retry-supported read |\n| `end_user.get` | `GET /v1/end-users/{end_user_id}` | `end_user_id` | JSON | Low-risk retry-supported read |\n\nThe capability template is:\n\n```text\ncap:dify:<app_id>:<operation>\n```\n\nUse discovery to obtain the exact app ID. Do not insert a provider key, origin,\nor unrelated app ID into the Action.\n\n## Partition input correctly\n\nEvery operation accepts the generic frozen input object:\n\n| Field | Use in this family |\n|---|---|\n| Path fields | `file_id` or `end_user_id` where the route requires them |\n| `user` | Required for upload and preview |\n| `query` | Optional provider query; preview also receives the validated `user` |\n| `body` | Not used by the upload multipart builder; optional on other routes only when provider-compatible |\n| `file` | Required only for upload |\n\nPath values contain 1 to 512 bytes. `user` contains 1 to 256 bytes without\ncontrol characters. Query objects have at most 128 properties and arrays at\nmost 256 scalar values.\n\nThe connector appends the required preview `user` itself and rejects a\nconflicting query value.\n\n## Read app metadata\n\nUse the four metadata reads to answer different questions:\n\n| Read | Use it to inspect |\n|---|---|\n| `parameters.get` | Published application input parameters |\n| `meta.get` | Tool and model metadata |\n| `info.get` | Published application information |\n| `site.get` | Published site settings |\n\nAll four send an authenticated empty-path read to the selected app. They do not\nrequire Dify end-user identity and do not prove that model execution, file\naccess, or another app key works.\n\nEach result has the generic JSON shape:\n\n```json\n{\n  \"http_status\": 200,\n  \"body\": {},\n  \"content_type\": \"application/json\",\n  \"provider_request_id\": null\n}\n```\n\nThe provider owns the nested `body` schema. Treat unknown fields as compatible\nprovider data unless the selected task requires a stronger reviewed contract.\n\n## Read one end user\n\nSelect `end_user.get` and supply only the provider's end-user identifier:\n\n```json\n{\n  \"end_user_id\": \"end-user-identifier\"\n}\n```\n\nThis route does not use the caller's `user` field. Authorization comes from the\nselected app key and AIP tenant policy. A returned record can contain personal\ndata, so apply the connector's confidential and redaction-required contract.\n\nAn absent or wrong identifier is a read failure. It is not evidence that the\nsame person has no conversations, messages, files, or state under another app.\n\n## Upload one file\n\nBefore upload:\n\n1. select the intended app and stable tenant-scoped end-user value;\n2. confirm the file is authorized for that user and Dify application;\n3. calculate the decoded size and intended content type;\n4. create one Action ID and one idempotency key;\n5. obtain the required tenant-policy approval.\n\nThe Action input has this shape:\n\n```json\n{\n  \"user\": \"tenant-user-0190\",\n  \"file\": {\n    \"filename\": \"context.txt\",\n    \"content_type\": \"text/plain\",\n    \"content_base64\": \"ZXhhbXBsZQ==\"\n  }\n}\n```\n\nThe connector validates a safe basename, base64, content type, and decoded\nsize. It sends multipart fields named `file` and `user`. For this operation it\ndoes not serialize Action `body` as a multipart `data` field.\n\nThe decoded-file implementation limit is 32 MiB. The base64 schema and common\nnative envelope can impose lower effective limits. Do not raise a response\nlimit to work around an oversized request.\n\nUpload is a provider mutation. It requires approval and a tenant-scoped key,\npublishes no automatic retry, and has no rollback capability. After an\ninterrupted response, inspect provider and Action state before another upload.\n\n## Preview one message file\n\nSupply the file and the same stable Dify user identity that owns access:\n\n```json\n{\n  \"file_id\": \"file-identifier\",\n  \"user\": \"tenant-user-0190\"\n}\n```\n\nThe connector renders `file_id` in the path and `user` in the query. It returns\nbounded bytes as base64:\n\n```json\n{\n  \"http_status\": 200,\n  \"content_base64\": \"ZXhhbXBsZQ==\",\n  \"content_type\": \"text/plain\",\n  \"size_bytes\": 7,\n  \"provider_request_id\": null\n}\n```\n\nDecode only after authorization, content-type policy, malware controls, and\noutput-size checks. The connector does not write the result to a\ncaller-selected path.\n\n## Recover safely\n\n| Observation | Decision |\n|---|---|\n| Metadata read is unauthorized | Verify the selected app descriptor and key without printing it |\n| Preview is unauthorized | Verify both app scope and exact end-user identity |\n| Path field is rejected | Supply one non-empty identifier within 512 bytes |\n| File basename or base64 is rejected | Correct the input before provider dispatch |\n| Upload remains pending approval | Review and decide the same immutable Action |\n| Upload response is temporary, transport-failed, or oversized | Treat provider outcome as uncertain; inspect file state |\n| Binary result exceeds the response limit | Review expected file size and policy; do not retry blindly |\n| Returned data belongs to another user or app | Stop traffic and treat it as an isolation incident |\n\nFor reads, retry support still requires the same Action policy, budget, and\nverified error. For upload, neither a key nor approval authorizes automatic\nreplay.\n\n## Related documentation\n\n- [Dify capability index](README.md)\n- [Dify connector configuration](../reference/configuration.md)\n- [Authentication and credential scopes](../getting-started/authentication-and-credential-scopes.md)\n- [Dify connector overview](../README.md)\n- [Errors and retry decisions](../../../reference/errors.md)\n",
    "text": "Dify app metadata and files\n\nUse this family to inspect a published application's contract, read one Dify\nend user, upload one bounded user file, or retrieve one bounded file preview.\nAll seven operations are available for every supported app mode.\n\nChoose the configured app through the capability ID. The host supplies its\napp-specific Bearer key and fixed provider origin.\n\nChoose an operation\n\n| Operation suffix | Method and route | Required input | Result | Policy |\n\n| parameters.get | GET /v1/parameters | None | JSON | Low-risk retry-supported read |\n| meta.get | GET /v1/meta | None | JSON | Low-risk retry-supported read |\n| info.get | GET /v1/info | None | JSON | Low-risk retry-supported read |\n| site.get | GET /v1/site | None | JSON | Low-risk retry-supported read |\n| file.upload | POST /v1/files/upload | user and file | JSON | Medium mutation; approval and key required |\n| file.preview | GET /v1/files/{fileid}/preview | fileid and user | Binary | Low-risk retry-supported read |\n| enduser.get | GET /v1/end-users/{enduserid} | enduserid | JSON | Low-risk retry-supported read |\n\nThe capability template is:\n\ncap:dify::\n\nUse discovery to obtain the exact app ID. Do not insert a provider key, origin,\nor unrelated app ID into the Action.\n\nPartition input correctly\n\nEvery operation accepts the generic frozen input object:\n\n| Field | Use in this family |\n\n| Path fields | fileid or enduserid where the route requires them |\n| user | Required for upload and preview |\n| query | Optional provider query; preview also receives the validated user |\n| body | Not used by the upload multipart builder; optional on other routes only when provider-compatible |\n| file | Required only for upload |\n\nPath values contain 1 to 512 bytes. user contains 1 to 256 bytes without\ncontrol characters. Query objects have at most 128 properties and arrays at\nmost 256 scalar values.\n\nThe connector appends the required preview user itself and rejects a\nconflicting query value.\n\nRead app metadata\n\nUse the four metadata reads to answer different questions:\n\n| Read | Use it to inspect |\n\n| parameters.get | Published application input parameters |\n| meta.get | Tool and model metadata |\n| info.get | Published application information |\n| site.get | Published site settings |\n\nAll four send an authenticated empty-path read to the selected app. They do not\nrequire Dify end-user identity and do not prove that model execution, file\naccess, or another app key works.\n\nEach result has the generic JSON shape:\n\n{\n  \"httpstatus\": 200,\n  \"body\": {},\n  \"contenttype\": \"application/json\",\n  \"providerrequestid\": null\n}\n\nThe provider owns the nested body schema. Treat unknown fields as compatible\nprovider data unless the selected task requires a stronger reviewed contract.\n\nRead one end user\n\nSelect enduser.get and supply only the provider's end-user identifier:\n\n{\n  \"enduserid\": \"end-user-identifier\"\n}\n\nThis route does not use the caller's user field. Authorization comes from the\nselected app key and AIP tenant policy. A returned record can contain personal\ndata, so apply the connector's confidential and redaction-required contract.\n\nAn absent or wrong identifier is a read failure. It is not evidence that the\nsame person has no conversations, messages, files, or state under another app.\n\nUpload one file\n\nBefore upload:\n1. select the intended app and stable tenant-scoped end-user value;\n2. confirm the file is authorized for that user and Dify application;\n3. calculate the decoded size and intended content type;\n4. create one Action ID and one idempotency key;\n5. obtain the required tenant-policy approval.\n\nThe Action input has this shape:\n\n{\n  \"user\": \"tenant-user-0190\",\n  \"file\": {\n    \"filename\": \"context.txt\",\n    \"contenttype\": \"text/plain\",\n    \"contentbase64\": \"ZXhhbXBsZQ==\"\n  }\n}\n\nThe connector validates a safe basename, base64, content type, and decoded\nsize. It sends multipart fields named file and user. For this operation it\ndoes not serialize Action body as a multipart data field.\n\nThe decoded-file implementation limit is 32 MiB. The base64 schema and common\nnative envelope can impose lower effective limits. Do not raise a response\nlimit to work around an oversized request.\n\nUpload is a provider mutation. It requires approval and a tenant-scoped key,\npublishes no automatic retry, and has no rollback capability. After an\ninterrupted response, inspect provider and Action state before another upload.\n\nPreview one message file\n\nSupply the file and the same stable Dify user identity that owns access:\n\n{\n  \"fileid\": \"file-identifier\",\n  \"user\": \"tenant-user-0190\"\n}\n\nThe connector renders fileid in the path and user in the query. It returns\nbounded bytes as base64:\n\n{\n  \"httpstatus\": 200,\n  \"contentbase64\": \"ZXhhbXBsZQ==\",\n  \"contenttype\": \"text/plain\",\n  \"sizebytes\": 7,\n  \"providerrequestid\": null\n}\n\nDecode only after authorization, content-type policy, malware controls, and\noutput-size checks. The connector does not write the result to a\ncaller-selected path.\n\nRecover safely\n\n| Observation | Decision |\n\n| Metadata read is unauthorized | Verify the selected app descriptor and key without printing it |\n| Preview is unauthorized | Verify both app scope and exact end-user identity |\n| Path field is rejected | Supply one non-empty identifier within 512 bytes |\n| File basename or base64 is rejected | Correct the input before provider dispatch |\n| Upload remains pending approval | Review and decide the same immutable Action |\n| Upload response is temporary, transport-failed, or oversized | Treat provider outcome as uncertain; inspect file state |\n| Binary result exceeds the response limit | Review expected file size and policy; do not retry blindly |\n| Returned data belongs to another user or app | Stop traffic and treat it as an isolation incident |\n\nFor reads, retry support still requires the same Action policy, budget, and\nverified error. For upload, neither a key nor approval authorizes automatic\nreplay.\n\nRelated documentation\n• Dify capability index (README.md)\n• Dify connector configuration (../reference/configuration.md)\n• Authentication and credential scopes (../getting-started/authentication-and-credential-scopes.md)\n• Dify connector overview (../README.md)\n• Errors and retry decisions (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "05ea2075e9f27232646e26298d852cd80261217b62a0b922ec782c5e3660e9e6"
  }
}